pueue-add

Add any command to the default queue

$ pueue add [command]

$ pueue add -- [command --arg -f]

$ pueue add [[-s|--stashed]] -- [rsync --archive --compress /local/directory /remote/directory]

$ pueue add [[-i|--immediate]] [[-g|--group]] "[CPU_intensive]" -- [ffmpeg -i input.mp4 frame_%d.png]

$ pueue add [[-a|--after]] [9] [12] [[-g|--group]] "[torrents]" -- [transmission-cli torrent_file.torrent]

$ pueue add [[-l|--label]] "[compressing large file]" [[-d|--delay]] "[wednesday 10:30pm]" -- "[7z a compressed_file.7z large_file.xml]"

pueue add [options] [arguments...]

--group
    Assigns the task to a specific group. Groups can be paused, started, or configured for parallel execution limits independently.

--after
    Adds the task to the queue immediately after the specified task ID has finished (successfully or not).

--before
    Adds the task to the queue immediately before the specified task ID.

--delay
    Delays the execution of the task by a specified duration (e.g., 10m, 1h, 1d).

--at
    Schedules the task to be executed at a specific date and time (e.g., 2023-10-27 15:30, tomorrow 08:00).

--priority
    Assigns a numerical priority to the task. Tasks with higher priority values are executed sooner.

--depends-on
    Makes the current task dependent on the successful completion of another task with the given ID.

--path , --working-directory
    Sets the working directory for the command's execution.

--env
    Adds or overrides an environment variable for the command's execution. Can be specified multiple times.

--stdout , --stderr
    Redirects the command's standard output or standard error to a specified file.

--start-immediately, --queue-immediately
    Instructs Pueue to start the task immediately upon addition, bypassing the queue's regular processing order.

--name
    Assigns a human-readable name to the task, useful for easier identification.

--print-task-id
    Prints the unique task ID of the newly added task to standard output.

--replace
    Replaces an existing task with the specified ID with the newly added task. The existing task must not be running.

--no-dependencies
    Prevents Pueue from automatically loading and applying dependencies defined in a pueue.yml file in the current directory.


    The shell command to be executed by Pueue.

[arguments...]
    Any arguments to be passed to the shell command.

The pueue-add is a subcommand of the pueue task queue manager. Pueue itself is a lightweight, command-line utility designed to queue and manage shell commands. It allows users to run commands in the background, sequentially or in parallel, ensuring that system resources are managed efficiently.

The pueue-add command is used to add a new command to the Pueue queue. When a command is added, Pueue assigns it a unique ID, records its execution details (like working directory, environment variables, output logs), and schedules it for execution according to its priority, group, or dependencies. This enables users to launch long-running tasks without blocking their terminal, recover output logs, and manage task lifecycles effectively. It's particularly useful for development workflows, CI/CD-like local setups, or any scenario where a series of commands needs to be executed reliably in the background.

Pueue operates as a client-server application. For pueue-add to function, the Pueue daemon (server) must be running in the background.
Commands added via pueue-add are executed in a non-interactive shell environment. Ensure that necessary environment variables (like PATH) are explicitly set or sourced if critical for command execution.
Task IDs are unique only for the current Pueue session and can be reused after a full restart or if tasks are removed and new ones are added, so relying on long-term fixed IDs is not advisable.

Each command added with pueue-add receives a unique integer task ID. This ID is crucial for interacting with the task later using other pueue commands (e.g., pueue status , pueue log , pueue remove ).

Pueue consists of a client (the pueue command itself) and a daemon (server). When you run pueue add, the client sends the task details to the daemon, which then manages the execution and state of the task.

Pueue emerged as a modern, user-friendly task queue solution for Linux and macOS, offering a more intuitive and flexible alternative to traditional batch systems like cron or at for personal background job management. It focuses on simplicity, clear status reporting, and robust task management from the command line, gaining popularity among developers for managing local build processes, tests, and long-running scripts.

pueue(1), pueue status(1), pueue start(1), pueue stop(1), pueue remove(1), pueue log(1), pueue edit(1)