Pueue — Manage Long-Running Shell Commands with a Task Queue

Introduction

Pueue provides a command queue and task manager for shell commands. Instead of running long tasks in background terminals and losing track of them, you add commands to Pueue's queue where they run sequentially or in parallel with full control over scheduling, pausing, and logging.

What Pueue Does

• Queues shell commands and executes them sequentially or in parallel
• Supports pausing, resuming, and killing individual tasks or entire groups
• Persists task state across daemon restarts
• Captures stdout and stderr for every task with log retrieval
• Allows task dependencies so one command waits for another to finish

Architecture Overview

Pueue consists of two parts: a daemon (pueued) that manages the task queue and executes commands, and a client (pueue) that communicates with the daemon over a Unix socket. Tasks are stored in a state file that survives daemon restarts. The daemon spawns child processes for each task and monitors their exit codes, managing concurrency limits per task group.

Self-Hosting & Configuration

• Install via Cargo, Homebrew, or package managers for most Linux distributions
• Start the daemon with pueued -d or configure it as a systemd service
• Configure via ~/.config/pueue/pueue.yml for parallelism and callback hooks
• Set per-group parallelism limits to control how many tasks run concurrently
• Use callback hooks to trigger notifications when tasks complete

Key Features

• Persistent task queue that survives daemon restarts
• Task groups with independent parallelism settings
• Task dependencies for ordered execution chains
• Log streaming with pueue follow for real-time output
• Stash and schedule tasks for deferred execution

Comparison with Similar Tools

• GNU Parallel — Focuses on parallel execution of similar commands, no persistent queue
• Task Spooler (ts) — Simpler sequential queue, fewer features for groups and dependencies
• nohup/disown — Basic background execution without queue management or logging
• tmux/screen — Terminal multiplexers that keep sessions alive but lack queue semantics

FAQ

Q: Can I limit how many tasks run at once? A: Yes. Set the parallel_tasks option per group in the config file or use pueue parallel 4 to allow four concurrent tasks.

Q: How do I see the output of a running task? A: Use pueue follow <task_id> to stream its stdout/stderr in real time, or pueue log <task_id> for the full captured output.

Q: Does Pueue work on macOS? A: Yes. Pueue supports macOS, Linux, and Windows.

Q: Can I set up task dependencies? A: Yes. Use pueue add --after <task_id> -- <command> to make a task wait for another to complete before starting.

Sources

• https://github.com/Nukesor/pueue
• https://github.com/Nukesor/pueue/wiki