How to Install and Use Pueue in Linux to Manage Shell Commands and Task Queues

Long-running shell operations—such as video transcoding with FFmpeg, executing intensive build pipelines, downloading large remote datasets, or transferring system archives—can quickly clutter active terminal windows. While background operators like & or terminal multiplexers like tmux and screen keep processes alive, they lack queue management, rate limiting, and granular execution control. Pueue is a robust command-line task management tool that runs as a lightweight daemon, allowing users to queue shell commands, organise execution sequences, limit parallel workloads, and inspect output logs without keeping terminal sessions open.

What Is Pueue and Why Use It?

Pueue operates on a client-server architecture consisting of two primary components:

• pueued (Daemon): The background service responsible for tracking tasks, executing scheduled commands, managing parallel worker pools, and capturing command outputs.
• pueue (Client): The command-line interface used to enqueue jobs, monitor queues, pause or resume tasks, and inspect output streams.

Unlike raw shell backgrounding, Pueue allows you to control how many tasks execute simultaneously, group tasks into independent queues, restart failed jobs with identical environment variables, and review historical terminal logs even across terminal reconnects or system reboots.

Step 1: Installing Pueue on Linux

Pueue is available across major Linux distributions through package managers, pre-compiled standalone binaries, and Cargo.

Option A: Install via Native Package Managers

On Arch Linux and its derivatives, install Pueue directly from the official repositories:

sudo pacman -S pueue

On Alpine Linux (Edge/Testing):

sudo apk add pueue

Option B: Install via Pre-Compiled GitHub Binaries

For Debian, Ubuntu, Fedora, or distributions without Pueue in their base repositories, download the latest official binaries directly from GitHub:

# Download the latest daemon and client binaries
curl -LO https://github.com/Nukesor/pueue/releases/latest/download/pueue-linux-x86_64
curl -LO https://github.com/Nukesor/pueued-linux-x86_64

# Move them to your local user executable path
chmod +x pueue-linux-x86_64 pueued-linux-x86_64
sudo mv pueue-linux-x86_64 /usr/local/bin/pueue
sudo mv pueued-linux-x86_64 /usr/local/bin/pueued

Option C: Install via Rust Cargo

If you maintain a Rust toolchain on your workstation:

cargo install --locked pueue

Step 2: Starting and Enabling the Pueue Daemon

Pueue requires its background daemon, pueued, to be active before the client can accept commands. It is designed to run as a user-level service without root privileges.

Running via systemd User Service

Create a user systemd service to ensure Pueue launches automatically on login and remains persistent:

# Create the systemd user service directory
mkdir -p ~/.config/systemd/user

# Download the official user service template
curl -o ~/.config/systemd/user/pueued.service https://raw.githubusercontent.com/Nukesor/pueue/main/utils/pueued.service

# Reload systemd user daemon and enable pueued
systemctl --user daemon-reload
systemctl --user enable --now pueued

Verify that the daemon is active and running cleanly:

systemctl --user status pueued

If running without systemd (such as within lightweight containers or minimalist environments), start the daemon directly in background mode:

pueued -d

Step 3: Enqueueing Shell Commands

Adding tasks to the queue is handled using the pueue add command. Pueue records the command string, working directory, and environment variables at the time of invocation.

Adding Single Commands

pueue add "sleep 30 && echo 'Task completed'"

Pueue assigns an incremental task ID to each submission and immediately begins execution if worker capacity is available.

Adding Commands with Custom Working Directories

By default, Pueue inherits the current working directory. You can specify a different execution path using the --working-directory flag:

pueue add --working-directory /var/log "tar -czf logs-archive.tar.gz *.log"

Adding Dependent Tasks

You can configure tasks to execute strictly after a prerequisite task finishes successfully using the --after flag:

# Add first compilation task
pueue add "make build"

# Add package packaging task dependent on task ID 0
pueue add --after 0 "tar -czf release-build.tar.gz bin/"

Step 4: Managing Task Groups and Parallelism

By default, Pueue runs tasks inside a default group with a concurrency limit of one task at a time. You can create custom groups with distinct parallel limits to manage diverse workloads simultaneously.

Creating Dedicated Groups

# Create a dedicated group for video processing
pueue group add transcoding

# Set parallel execution limit for the transcoding group to 2 concurrent workers
pueue parallel 2 -g transcoding

Enqueueing Tasks into Specific Groups

pueue add -g transcoding "ffmpeg -i input1.mp4 -c:v libx265 -crf 28 output1.mp4"
pueue add -g transcoding "ffmpeg -i input2.mp4 -c:v libx265 -crf 28 output2.mp4"
pueue add -g transcoding "ffmpeg -i input3.mp4 -c:v libx265 -crf 28 output3.mp4"

In this scenario, Pueue runs two transcoding jobs simultaneously while placing the third in a queued status until a worker slot frees up.

Step 5: Monitoring Queues and Reading Process Logs

Pueue provides high-level queue overviews and real-time log tracking tools.

Checking Queue Status

pueue status

This command displays a table listing task IDs, current status (Running, Queued, Done, Failed), exit codes, execution runtimes, and assigned groups.

Inspecting Task Logs

To inspect terminal outputs without opening log files:

# View complete log output for task ID 2
pueue log 2

# View only the last 20 lines of output for all tasks
pueue log --lines 20

# Stream live terminal output of a running task (follow mode)
pueue follow 2

Step 6: Controlling, Pausing, and Removing Tasks

Pueue gives you full lifecycle control over queued and active commands:

• Pause Active Tasks: pueue pause 2 (pauses specific task) or pueue pause (pauses the entire default queue).
• Start / Resume Tasks: pueue start 2 or pueue start -g transcoding.
• Kill Running Jobs: pueue kill 2 terminates execution cleanly using SIGTERM, falling back to SIGKILL if unresponsive.
• Restart Failed Tasks: pueue restart 2 or pueue restart --failed re-enqueues failed tasks automatically.
• Clean Old History: pueue clean removes finished tasks from the status table while keeping active jobs untouched.

Verifying Daemon Persistence and Task Recovery

A crucial advantage of Pueue is resilience against session disconnections. If your SSH connection drops or your graphical desktop restarts, pueued continues executing commands in the background. Once you reconnect to the server, run pueue status to view current progress or pueue follow [ID] to resume monitoring live task outputs seamlessly.