Get started

• Start the daemon
  • Systemd
• How to use the client
  • Adding commands
  • See what's going on
  • Parallel tasks
  • Pause, resume and start tasks
  • Manipulate multiple tasks at once
  • Dependencies, delays, immediate
• Common pitfalls
  • A command does not behave like expected
  • The command formatting seems to be broken
  • A process waits for input
  • My shell aliases do not work
  • Display not found

Start the Daemon

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

Local: The daemon can be be run in the current shell. Just run pueued anywhere on your commandline. 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

If you use Systemd and don't install Pueue with a package manager, place pueued.service in /etc/systemd/user/.
Afterward, every user can start/enable their own session with:

systemctl --user start pueued.service
systemctl --user enable pueued.service

How to use the client

Adding commands

To add a command just write: pueue add sleep 60
If you want to add flags to the command, you can either:

• add -- => pueue add -- ls -al
• Pass the command as a string pueue add 'ls -al'

The command will then be added and scheduled for execution, as if you executed it right now and then. For normal operation it's recommended to add an alias to your shell's rc.
E.g.: alias pad='pueue add --'

You also have to pay attention, whether case your command contains escaped characters. For instance, pueue add ls /tmp/long\ path will result in the execution of sh -c ls /tmp/long path, which will result in /tmp/long and path being interpreted as two different parameters.

There are two different approaches to solve this problem:

1. Surrounding the command with quotes, e.g. pueue add "ls /tmp/long\ path" This is the safest approach, since it simply passes the command to the shell, without resolving any escaped strings. \
2. Use the --escape flag, which automatically escapes the command, e.g. pueue add --escape ls /tmp/long\ path However, this also escapes shell specific operators such as && or &> and thereby breaks them.

If you're having trouble with anything, please take a look at the common pitfalls page.

See what's going on

To get the status of currently running commands, just type pueue status.
To look at the current output of a command use pueue log or pueue log $task_id.
If you want to follow the output of a running command use pueue follow $task_id. To follow stderr, use the -e flag.

Parallel tasks

By default, pueue only executes a single task at a time. This can be changed in the configuration file, but also on-demand during runtime. Just use the parallel subcommand, e.g. pueue parallel 3. Now there'll always be up to three tasks running in parallel.

Pause, resume and start tasks

Without any parameters, the pause subcommand pauses all running tasks and the daemon itself. A paused daemon won't start any new tasks, until it's started again.

To resume normal operation, just write pueue start. This will continue all paused tasks and the daemon will continue starting tasks.

However, you can also pause specific tasks, without affecting the daemon's state or any other tasks. Just add the id of the this task as a parameter, e.g. pueue pause 1. It can be resumed the same way with the start command.

start can also force tasks to be started, which ignores any constraints on parallel tasks.

Manipulate multiple tasks at once

Most commands can be executed on multiple tasks at once. For instance, you can look at specific logs like this:
pueue log 0 1 2 3 15 19.

This also works with your shell's range parameter, e.g. pueue log {0..3} 15 19.

Dependencies

Pueue allows to specify dependencies for tasks. A task will only be executed if all dependencies were successful.

A dependency can be specified by using the --after/-a flag on the add command.

It is advised to use this in combination with the pause_on_failure setting. This will prevent all dependant tasks of a failed task to fail as well.
Instead, one can now go ahead, debug/fix the failed task and restart it with the --in-place flag.

Any dependency handling will then continue as expected without breaking the whole dependency chain.

Delays and immediate

There are multiple other ways to specify when a command should be executed. Check the help text of the add subcommand to see all options.

As an example, you can:

• Set a delay. The task will be scheduled after e.g. 5 hours.
• force a start. The task will be started immediately.