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 and immediate

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

Systemd user services allow every user to start/enable their own session with:

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

If don't install Pueue with a package manager, place pueued.service in /etc/systemd/user/.
Remember to run systemctl --user daemon-reload afterwards.

How to use the client

Adding commands

To add a simple command just write: pueue add sleep 60.

If you want to add flags to the command, pass them behind a double dash --:
pueue add -- ls -al /tmp/no_spaces_allowed

If your command contains character that need escaping, surround the whole command with a string:
pueue add 'ls -al /tmp/dir\ with\ spaces/'

For more information, please read the shell escaping section.

If you're having trouble with something else, 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.

Shell Escaping

Let's take this example: pueue add -- echo "&& rm /tmp"
It might seem a little unintuitive at first, but this task will try to delete /tmp.

Pueue sees these parameters as two distinct strings ['echo', '&& rm /tmp'].
Pay attention on the fact that the quotes around the && rm /tmp part didn't get passed through. This is due to the way shells parse parameters and the way parameters are passed through to a called process.

Let's take a look at another example: pueue add ls /tmp/Hello\ World.txt.
Pueue will see those parameters like this: ['ls', '/tmp/Hello World.txt'].
As you can see, the shell escape character \ has been removed!

The shell removes all shell specific characters before the command line arguments are passed to the called program! Under normal circumstances this is exactly what you would want, but not in the case of Pueue.
Pueue takes the given command and places it in a sh -c '$command' call. However, since some critical information may have been lost, such as the \ and " characters, commands may no longer work or misbehave.

echo "&& rm /tmp" becomes sh -c 'echo && rm /tmp'.
ls /tmp/Hello\ World.txt becomes sh -c 'ls /tmp/Hello World.txt', which then looks for /tmp/Hello and the file World.md.

The safest way to prevent any of this, is to surround the command with quotes! That way no shell specific syntax is removed and everything will be perfectly preserved.
In our example, this would look like this:
pueue add 'echo "&& rm /tmp"'
pueue add 'ls /tmp/Hello\ World.md'

PS:

There's also the special --escape flag, but this is mainly for scripting. A side-effect is, that it disables any shell specific syntax, such as && or &>.
It is not adivsed to use it unless you know what you're doing.