pueue-kill

Kill a running or queued pueue task

TLDR

Kill all tasks in the default group

$ pueue kill

Kill a specific task

$ pueue kill [task_id]

Kill a task and terminate all its child processes

$ pueue kill --children [task_id]

Kill all tasks in a group and pause the group

$ pueue kill [[-g|--group]] [group_name]

Kill all tasks across all groups and pause all groups

$ pueue kill [[-a|--all]]

SYNOPSIS

pueue kill [OPTIONS] [TASK_ID|TASK_ID_RANGE]...

TASK_ID|TASK_ID_RANGE
    The ID or a range of IDs of the task(s) to kill. A range is specified like 1-5 to kill tasks 1 through 5.

-a, --all
    Kills all managed tasks.

-g, --group
    Kills all tasks within the specified group.

-q, --queue
    Kill all currently queued tasks

-w, --wait
    Wait for all child processes to exit gracefully before termination. This gives child processes a chance to clean up after themself.
This is only useful, if the program handled by the task also handles the SIGKILL signal properly, otherwise it's the same as a normal kill.

-f, --force
    Forcefully kill the task without confirmation.

-h, --help
    Displays help information about the command.

DESCRIPTION

The pueue-kill command forcefully terminates a managed task within the Pueue task manager. This is the recommended method for stopping a currently running or queued task that is no longer needed, or is behaving unexpectedly. It attempts to send a SIGKILL signal to the process, ensuring immediate termination. This command allows to specify the task ID to be killed, or to target multiple tasks via options such as --all or --group.

CAVEATS

Using pueue kill sends a SIGKILL signal. This is a forceful termination and doesn't allow the task to gracefully shut down. This can lead to data loss or corruption if the task was in the middle of writing to a file or database.

EXIT CODES

pueue-kill will exit with a code of 0 on successful termination of the task(s). A non-zero exit code indicates an error, such as an invalid task ID or failure to connect to the Pueue daemon.

SIGNAL HANDLING

pueue-kill specifically uses the SIGKILL signal (signal number 9), which cannot be caught or ignored by the target process. This ensures that the process is terminated, even if it's unresponsive.
The -w or --wait Option makes pueue kill sends SIGTERM first to allow the task to shutdown gracefully.

HISTORY

pueue-kill is part of the Pueue task management system, designed to manage and control the execution of long-running or background tasks. The kill command was introduced to provide a mechanism for immediately stopping tasks that are no longer required or are encountering issues. It's been available since the early versions of Pueue, reflecting the core need for task control in a task management system.