---
obj: application
repo: 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 **p**rocesses a q**ueue** of [shell](Shell.md) 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](../network/SSH.md) 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](Shell.md). 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](../../linux/systemd/Systemd.md) user services allow every user to start/enable their own session on [Linux](../../linux/Linux.md) 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](Shell.md) characters (" ", "&", "!", etc.). Beware: This implicitly disables nearly all [shell](Shell.md) 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.<br>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>]`