knowledge/technology/applications/cli/pueue.md

obj	repo
application	https://github.com/nukesor/pueue

pueue

Pueue is a command-line task management tool for sequential and parallel execution of long-running tasks.

Simply put, it's a tool that processes a queue of shell commands. On top of that, there are a lot of convenient features and abstractions.

Since Pueue is not bound to any terminal, you can control your tasks from any terminal on the same machine. The queue will be continuously processed, even if you no longer have any active ssh sessions.

Start the Daemon

Before you can use the pueue client, you have to start the daemon.

Local: The daemon can be run in the current shell. Just run pueued anywhere on your command line. It'll exit if you close the terminal, though.

Background: To fork and run pueued into the background, add the -d or --daemonize flag. E.g. pueued -d.
The daemon can always be shut down using the client command pueue shutdown.

Systemd

Systemd user services allow every user to start/enable their own session on Linux operating system distributions.

If you didn't install Pueue with a package manager, follow these instructions first:

1. download pueued.service from the GitHub Releases page;
2. place pueued.service in /etc/systemd/user/ or ~/.config/systemd/user/;
3. make sure the pueued binary is placed at /usr/bin, which is where pueued.service expects is to be.

Then, regardless of how you installed Pueue, run:

1. systemctl --user start pueued, to start the pueued service;
2. systemctl --user enable pueued, to run the pueued service at system startup;
3. systemctl --user status pueued, to ensure it is active (running).

Using pueue

Usage: pueue <action> <options>

pueue add

Enqueue a task for execution.
Usage: pueue add <options> <command>

Options

Option	Description
-w, --working-directory <working-directory>	Specify current working directory
-e, --escape	Escape any special shell characters (" ", "&", "!", etc.). Beware: This implicitly disables nearly all shell specific syntax ("&&", "&>")
-i, --immediate	Immediately start the task
-s, --stashed	Create the task in Stashed state. Useful to avoid immediate execution if the queue is empty
-d, --delay <delay>	Prevents the task from being enqueued until <delay> elapses.
-g, --group <GROUP>	Assign the task to a group. Groups kind of act as separate queues. I.e. all groups run in parallel and you can specify the amount of parallel tasks for each group. If no group is specified, the default group will be used
-a, --after <after>	Start the task once all specified tasks have successfully finished. As soon as one of the dependencies fails, this task will fail as well
-o, --priority <PRIORITY>	Start this task with a higher priority. The higher the number, the faster it will be processed
-l, --label <LABEL>	Add some information for yourself. This string will be shown in the "status" table. There's no additional logic connected to it
-p, --print-task-id	Only return the task id instead of a text. This is useful when working with dependencies

pueue remove

Remove tasks from the list. Running or paused tasks need to be killed first
Usage: pueue remove <TASK_IDS>...

pueue switch

Switches the queue position of two commands. Only works on queued and stashed commands
Usage: pueue switch <TASK_ID_1> <TASK_ID_2>

pueue stash

Stashed tasks won't be automatically started. You have to enqueue them or start them by hand
Usage: pueue stash <TASK_IDS>...

pueue enqueue

Enqueue stashed tasks. They'll be handled normally afterwards
Usage: pueue enqueue [-d, --delay <delay>] [TASK_IDS]...

pueue start

Resume operation of specific tasks or groups of tasks.
By default, this resumes the default group and all its tasks.
Can also be used force-start specific tasks.
Usage: pueue start [-g, --group <GROUP>] [TASK_IDS]...

pueue restart

restart Restart failed or successful task(s).
By default, identical tasks will be created and enqueued, but it's possible to restart in-place.
You can also edit a few properties, such as the path and the command, before restarting.

pueue pause

Restart failed or successful task(s).
By default, identical tasks will be created and enqueued, but it's possible to restart in-place.
You can also edit a few properties, such as the path and the command, before restarting.
Usage: pueue restart [OPTIONS] [TASK_IDS]...

Options

Option	Description
-a, --all-failed	Restart all failed tasks across all groups. Nice to use in combination with -i/--in-place
-g, --failed-in-group <FAILED_IN_GROUP>	Like --all-failed, but only restart tasks failed tasks of a specific group. The group will be set to running and its paused tasks will be resumed
-k, --start-immediately	Immediately start the tasks, no matter how many open slots there are. This will ignore any dependencies tasks may have
-s, --stashed	Set the restarted task to a "Stashed" state. Useful to avoid immediate execution
-i, --in-place	Restart the task by reusing the already existing tasks. This will overwrite any previous logs of the restarted tasks
--not-in-place	Restart the task by creating a new identical tasks. Only applies, if you have the restart_in_place configuration set to true
-e, --edit	Edit the tasks' commands before restarting
-p, --edit-path	Edit the tasks' paths before restarting
-l, --edit-label	Edit the tasks' labels before restarting

pueue kill

Kill specific running tasks or whole task groups..
Kills all tasks of the default group when no ids or a specific group are provided.
Usage: pueue kill [-g, --group <GROUP>] [TASK_IDS]...

pueue send

Send something to a task. Useful for sending confirmations such as 'y\n'

Usage: pueue send <TASK_ID> <INPUT>

pueue edit

Edit the command, path or label of a stashed or queued task.
By default only the command is edited.
Multiple properties can be added in one go.
Usage: pueue edit [OPTIONS] <TASK_ID>

Options

Option	Description
-c, --command	Edit the task's command
-p, --path	Edit the task's path
-l, --label	Edit the task's label
-h, --help	Print help

pueue group

Use this to add or remove groups.
By default, this will simply display all known groups.
Usage: pueue group [-j, --json] [COMMAND]

Add a group by name:
Usage: pueue group add [-p, --parallel <PARALLEL>] <NAME>

Remove a group by name. This will move all tasks in this group to the default group!
Usage: pueue group remove <NAME>

pueue status

Display the current status of all tasks
Usage: pueue status [-j, --json] [-g, --group <GROUP>] [QUERY]...

pueue log

Display the log output of finished tasks.
Only the last few lines will be shown by default.
If you want to follow the output of a task, please use the "follow" subcommand.
Usage: pueue log [-l, --lines <LINES>] [-f, --full] [TASK_IDS]...

pueue follow

Follow the output of a currently running task. This command works like "tail -f"
Usage: pueue follow [TASK_ID]

pueue wait

Wait until tasks are finished.
By default, this will wait for all tasks in the default group to finish.
Note: This will also wait for all tasks that aren't somehow 'Done'.

Usage: pueue wait [ -g, --group <GROUP>] [-a, --all] [-q, --quiet] [TASK_IDS]...

pueue clean

Remove all finished tasks from the list
Usage: pueue clean [-s, --successful-only] [-g, --group <GROUP>]