pueue

Show general help and available subcommands

$ pueue [[-h|--help]]

$ pueue [subcommand]

$ pueue [[-V|--version]]

pueue [GLOBAL_OPTIONS] <SUBCOMMAND> [SUBCOMMAND_OPTIONS] [ARGUMENTS]

Common Subcommands:
  pueue add [OPTIONS] <COMMAND>
  pueue status [OPTIONS]
  pueue start [OPTIONS] [<TASK_ID>]
  pueue stop [OPTIONS] [<TASK_ID>]
  pueue logs [OPTIONS] [<TASK_ID>]
  pueue remove [OPTIONS] [<TASK_ID>]
  pueue reset [OPTIONS]

--help, -h
    Display help message for Pueue or a specific subcommand.

--version, -V
    Print Pueue version information.

--daemon, -d
    Starts the Pueue daemon in the background. This command is typically run once to initialize the Pueue service, allowing it to manage tasks persistently.

--config <PATH>, -c <PATH>
    Specify a custom path to the Pueue configuration file. Useful for managing multiple Pueue instances or custom setups.

--path <PATH>, -P <PATH>
    Set a custom daemon directory path. Overrides the default Pueue data directory where tasks and logs are stored.

--host <HOST>, -H <HOST>
    Specify the Pueue daemon host address. Allows the client to connect to a daemon running on a different network interface or machine.

--log-level <LEVEL>, -L <LEVEL>
    Set the log level for Pueue messages. Common levels include error, warn, info, debug, trace.

--kill-client, -k
    Kills any running Pueue client process. Primarily for development or troubleshooting, not typically used in daily operations.

pueue is a sophisticated command-line utility designed to manage and execute tasks in the background. Unlike simple shell job control (&, bg, fg) or nohup, Pueue employs a client-server architecture, where a persistent daemon manages a queue of commands. This allows tasks to continue running even after the terminal session is closed or a system reboot (provided the daemon is restarted). It provides robust features for queuing commands, running them sequentially or in parallel, grouping tasks, and viewing their status and logs. Pueue is ideal for long-running processes like compilations, data processing scripts, or continuous integration tasks, offering a reliable way to orchestrate background operations with ease and visibility. It simplifies the process of managing multiple background jobs, providing control over their execution order, concurrency, and output.

Pueue operates on a client-server model, requiring a daemon process to be running for any commands to function. If the daemon is not active, Pueue commands will fail to connect. Users must ensure the daemon is started, often with pueue --daemon. Task output, especially for long-running processes, needs to be handled carefully; direct terminal output is not automatically streamed to the client and should be redirected to files within the command definition (e.g., my_script.sh > output.log 2>&1) if persistent logging is desired. While Pueue provides persistence, tasks are only re-queued upon daemon restart if they were in a pending or running state; completed tasks are not automatically re-run.

Pueue is primarily driven by its extensive set of subcommands, each dedicated to a specific aspect of task management. Key subcommands include:
add: Adds a new command to the queue.
status: Displays the current state of the queue, including running, queued, and finished tasks.
start: Starts the next pending task or a specific task by ID.
stop: Pauses the execution of the queue or a specific running task.
logs: Shows the stdout/stderr output of a specific task.
remove: Deletes tasks from the queue.
reset: Clears all tasks from the queue and resets Pueue's state.
parallel / sequential: Changes the execution mode of a task group.
group: Manages task groups, allowing for concurrent execution of multiple groups while tasks within a group run sequentially or in parallel.
Each subcommand often has its own set of options for fine-grained control.

Pueue functions through a client-server model. The Pueue daemon (server) runs continuously in the background, managing the task queue, executing commands, and storing their state and output. The Pueue client (the pueue command you run in your terminal) communicates with this daemon to add, manage, or query tasks. This design ensures that tasks persist and continue running even if the client terminal is closed, crashes, or the user logs out. The daemon's state, including the task queue, is saved to disk, providing robustness against system restarts.

A core feature of Pueue is its ability to persist tasks across sessions and even system reboots. Once a task is added to the queue, its status and output (if not redirected by the command itself) are maintained by the Pueue daemon. The output of executed tasks is stored by the daemon and can be reviewed at any time using the pueue logs command. Users should be aware that Pueue captures stdout and stderr internally; for complex logging or long-term storage, it's often best practice to explicitly redirect command output to a file when adding a task (e.g., pueue add "my_script.sh > /var/log/my_script.log 2>&1").

Pueue was developed by Arne Beer as a personal solution to better manage long-running background tasks. Frustrated by the limitations of existing tools like nohup or complex screen/tmux sessions for simple background execution, Beer created Pueue to offer a more structured and persistent queuing system. The project, written in Rust, emphasizes reliability, performance, and a user-friendly command-line interface. It has evolved to include sophisticated features like task grouping, parallel execution, and configurable daemon behavior, establishing itself as a robust tool for managing background processes in development and system administration contexts.

at(1), cron(8), nohup(1), screen(1), tmux(1), jobs(1) (shell builtin), bg (shell builtin), fg (shell builtin)