pueue-clean

Remove finished tasks and clear logs

$ pueue clean

$ pueue clean [[-s|--successful-only]]

pueue clean [TASK_IDS...]

TASK_IDS...
    Optional. One or more space-separated numeric IDs of tasks to remove. If provided, only these specific tasks will be removed from the queue, regardless of their status. If no IDs are specified, pueue clean will remove all tasks that are in a finished state (e.g., Done, Failed, Killed).

The pueue-clean command, invoked as pueue clean, serves as a crucial utility for managing the task queue within Pueue, a command-line task queue runner. Its primary function is to remove tasks that have completed their execution, whether successfully, with failure, or by being killed.

This process helps to declutter the Pueue client's display and ensure that only active, pending, or paused tasks remain visible. Without regular cleaning, the task list can grow indefinitely, making it difficult to track currently running or waiting jobs. By default, pueue clean removes all tasks that are no longer in a Running, Stalled, Paused, or Waiting state. This includes tasks that have completed (Done, Success), failed (Failed), or were manually terminated (Killed). Optionally, specific task IDs can be provided to remove only those particular tasks, regardless of their current status, making it functionally similar to the pueue rm command in such cases.

When pueue clean is invoked without any TASK_IDS, it only removes tasks that have reached a final, non-active state (like Done, Failed, Success, Killed). It will not remove tasks that are currently Running, Stalled, Paused, or Waiting.

However, if specific TASK_IDS are supplied, the command will remove those tasks irrespective of their current status, effectively behaving like pueue rm. Users should be mindful of this dual behavior to avoid unintentionally removing active tasks when specifying IDs.

The pueue clean command specifically targets tasks in the following final states when no TASK_IDS are provided:

Done/Success: The task completed successfully.
Failed: The task exited with a non-zero status code.
Killed: The task was manually terminated by the user.

Tasks in active or pending states such as Running, Stalled, Paused, or Waiting are never removed by a default pueue clean operation, ensuring critical ongoing processes are not interrupted.

Pueue emerged as a modern, user-friendly alternative to complex background job managers, focusing on simplicity and ease of use for developers and system administrators needing to queue commands from their terminal. The pueue clean subcommand has been an integral part of Pueue since its early versions, addressing the common need to maintain a tidy queue history.

As Pueue evolved with features like parallel execution, dependency management, and various task states, the clean command remained consistent in its core purpose: decluttering the interface by removing completed jobs, thus enhancing the user experience and clarity of the task list.

pueue(1), pueue rm(1), pueue status(1), pueue add(1)