What Is Pueue? The Beginner's Guide to the CLI Task Queue Manager

CodexFuse Team · 2026-11-04T22:51:55.474Z · 11 min read min read

What Is Pueue, Exactly?

What is pueue? "Pueue is a command-line task management tool for sequential and parallel execution of long-running tasks" — that is the README's own definition — and, "simply put, it's a tool that processes a queue of shell commands." Instead of chaining ten long jobs with && in one terminal and hoping your connection holds, you hand each command to pueue's queue and the daemon runs them for you, one by one or a few at a time, in the background.

The name comes from the German word for "queue." It is an open-source project by Arne Beer (Nukesor on GitHub), written in Rust, and it has two parts: the pueue client you type commands into, and the pueued daemon that actually runs them. "Since Pueue is not bound to any terminal, you can control your tasks from any terminal on the same machine" — and crucially, "the queue will be continuously processed, even if you no longer have any active ssh sessions."

That last line is why people on VPS hosting boxes reach for it: a two-hour rsync, a dataset download, or a video encode keeps going after you close the laptop lid. With about 6,411 GitHub stars as of November 4, 2026, pueue has quietly become the standard answer to "how do I run this overnight without babysitting a terminal." That, in one paragraph, is pueue explained: a queue of shell commands that survives you.

Why Pueue Exists: The Scenario That Built It

An early version of the project's README tells the origin story with two very concrete scenarios: "You have to unpack large amounts of data into various directories. Usually, something like this ends with 10+ open terminals/tmux sessions and an over-challenged hard drive." The other: "you want to re-encode 10 movies and each re-encode takes 10+ hours. Creating a chained command with &&s isn't ergonomic at all and running that many re-encodes in parallel will break your CPU."

Pueue was designed for exactly that middle ground — jobs too long to babysit, too numerous to run one at a time, too heavy to fire off all at once. "You can schedule your task and continue on the same shell without waiting," and "you can specify how many tasks should run in parallel and group tasks to maximize system resource utilization." The author's listed applications read like a server-admin's weekend: copying large amounts of data, machine learning, compression tasks, movie encoding, rsync tasks — "anything that takes longer than 5 minutes."

One note on provenance: the current README links to a wiki FAQ page that no longer exists (both links return page-not-found), so the "why should I use it" text above is quoted from the archived pueue 1.0.3 README preserved on docs.rs — the author's words, from the earliest documented version.

How to Install Pueue (pueue install)

Install is quick, but the one thing to know first: pueue is two binaries, the client pueue and the daemon pueued, and you need both on your $PATH. The project recommends your system's package manager as the preferred route; the README defers to a repology packaging table for the distro list, so check that table for your system rather than guessing a package name.

Follow these steps in order:

1. Check your package manager first. "The preferred way to install Pueue is to use your system's package manager. This will usually deploy service files and completions automatically." Per-distro packaging routes were not individually verifiable this week, so treat the README's packaging table as the source of truth.
2. Use prebuilt binaries if you prefer. "Statically linked (if possible) binaries for Linux (incl. ARM), Mac OS and Windows are built on each release. You can download the binaries for the client and the daemon (pueue and pueued) for each release" from the GitHub releases page. "Just download both binaries for your system, rename them to pueue and pueued and place them in your $PATH/program folder."
3. Or install with Cargo. Run cargo install --locked pueue. "Pueue is built for the current stable Rust version," and it installs to $CARGO_HOME/bin/pueue (default ~/.cargo/bin/pueue). From source: clone [email protected]:Nukesor/pueue, then cargo build --release --locked --path ./pueue; the binaries land in target/release/{pueue,pueued}.
4. Confirm the install. Run pueue -V. As of November 4, 2026 the current release is 4.0.4 (2026-03-02), from the project's CHANGELOG on main; 4.0.0 (2025-03-09) was the breaking release that wiped pre-4.0 state and reworked the daemon protocol.

Start the pueued Daemon Before Anything Else

Before you can use the pueue client, you have to start the daemon — say it once, because every "nothing happens" debugging story starts here. The wiki's Get-started page gives you four options depending on how permanent you want the setup to be.

The quick options: "The daemon can be run in the current shell. Just run pueued anywhere on your command line. It'll exit if you close the terminal, though." For a backgrounded daemon: "To fork and run pueued into the background, add the -d or --daemonize flag. E.g. pueued -d."

For a permanent Linux setup, the wiki recommends a systemd user service: "Systemd user services allow every user to start/enable their own session on Linux operating system distributions." If you did not install via a package manager, download pueued.service from the GitHub releases page, place it in /etc/systemd/user/ or ~/.config/systemd/user/, make the binaries executable, and put pueued at /usr/bin/ — then run systemctl --user start pueued, systemctl --user enable pueued, and systemctl --user status pueued to confirm it is active (running).

On Windows, 4.0 added native service support: "In 4.0+, pueued has built in support for Windows services" via pueued service install / start / stop (all with administrator privileges; one user per machine only). And when the day is done: "The daemon can always be shut down using the client command pueue shutdown."

Your First Pueue Commands: A Five-Step Walkthrough (pueue tutorial)

With the daemon running, the whole mental model is: add a command, watch it with status, read its output with log. Here is the walkthrough the wiki itself teaches:

1. Queue something simple. "To add a simple command, just write: pueue add sleep 60." If the command has its own flags, pass them behind a double dash: pueue add -- ls -al /tmp/no_spaces_allowed. If it contains characters that need escaping, surround the whole command with quotes: pueue add 'ls -al /tmp/dir\ with\ spaces/'.
2. Check the queue. "To get the status of currently running commands, just type pueue status or pueue as a shortcut." You get a uniform table of every task with its state — queued, running, paused, finished, or failed.
3. Read the output. "To look at the current output of a command, use pueue log or pueue log $task_id." Logs are captured automatically and "persisted onto the disk and survive a crash" — so a finished task's output is still there tomorrow.
4. Follow a running task. "If you want to follow the output of a running command, use pueue follow $task_id" — it works like tail -f, with a -e flag to follow stderr. Most commands accept multiple task IDs at once, e.g. pueue log 0 1 2 3 15 19.
5. Pause and resume. "Without any parameters, the pause subcommand pauses all running tasks and the daemon itself," and "to resume normal operation, just write pueue start." To pause a single task: pueue pause 1; start can also force a task to run immediately, ignoring parallelism constraints.

Beyond the walkthrough: restart re-runs failed or finished tasks (with --in-place after a fix), send feeds input — like confirming a package-manager prompt — to interactive processes, clean sweeps finished tasks off the list, and wait blocks a script until tasks finish — handy for batch pipelines.

The && Quoting Trap That Bites Every Beginner

This is the single most important thing to internalize about pueue add: pueue wraps your command in an sh -c call — but your shell strips its quotes before pueue ever sees them, which can silently rewrite what actually runs. The wiki leads with the author's own dangerous example: pueue add -- echo "&& rm /tmp" — "It might seem a little unintuitive at first, but this task will try to delete /tmp."

Why? "Pueue sees these parameters as two distinct strings ['echo', '&& rm /tmp']." The quotes around the && rm /tmp part never reach pueue — "the shell removes all shell specific characters before the command line arguments are passed to the called program" — and then "Pueue takes the given command and places it in a sh -c '$command' call." So echo "&& rm /tmp" becomes sh -c 'echo && rm /tmp', and the rm executes for real.

The fix is the wiki's own rule, quoted verbatim: "The safest way to prevent any of this, is to surround the command with quotes!" Write pueue add 'echo "&& rm /tmp"' instead — the outer single quotes keep everything intact for the sh -c wrap. Related traps from the Common Pitfalls page: "A single & somewhere in your command detaches the process, causing the Pueue task to finish immediately," and pueue cannot use aliases from your shell's .*rc files — it ships its own aliasing via pueue_aliases.yml. When in doubt, test the raw form first: "Try to run the command without adding it to Pueue. Do this by calling sh -c '$COMMAND' instead of pueue add '$COMMAND'. If this fails, it's not a problem with Pueue."

Running Tasks in Parallel, Groups, and Stashes (pueue add)

"By default, pueue only executes a single task at a time" — parallelism is something you opt into, not something that surprises you. The feature list reads like a direct answer to the over-challenged-hard-drive scenario: "Add tasks as you go," "run multiple tasks at once — you decide how many tasks should run concurrently," "change the order of the scheduled tasks," and "specify dependencies between tasks."

Setting parallelism takes one command: "Just use the parallel subcommand, e.g., pueue parallel 3 — now there'll always be up to three tasks running in parallel." Groups go further: pueue group add cpu creates a separate queue, pueue add -g cpu -- 'sleep 60' puts a task in it ("if no group is specified, the task will just be added to the default queue"), and pueue parallel -g cpu 2 sets that group's own limit. Groups are the answer to "two CPU-hungry encodes and four tiny downloads" — each lane gets its own budget.

Stashed tasks are for "not yet": add with --stashed and the task waits — "a Stashed task is not Queued and will thereby not be automatically started" — then pueue enqueue or pueue start $task_id fires it when you are ready. The wiki's own pattern for this is an rsync job: pueue add --stashed -- rsync --archive --compress /local/directory /remote/directory — stage the long transfer during the day, enqueue it at night. (Our rsync guide covers the transfer side.) Dependencies round it out: add with --after/-a, and "a task will only be executed if all dependencies were successful" — a build step that only runs if the download step succeeded.

Pueue vs tmux vs nohup: Which Tool Answers Which Need

Pueue and tmux solve different problems — one queues commands, the other keeps terminals — and nohup is a third, cruder thing again. The author himself addressed the tmux question directly (in the archived README, since the current FAQ link is dead): "One of the most frequent questions is, why one should use Pueue, when there're terminal multiplexer such as Tmux or Screen. My response is, that there're simply a lot of missing convenience features." His list: "the ability to queue commands and not start them all at once," "specifying how many tasks should run in parallel," "easy pausing/resuming of tasks," "pretty and accessible task status overviews," and "no need to attach to multiple tmux sessions." He adds, honestly, "I used tmux for this stuff all the time before writing Pueue. However, after using it for a really long time, it just kept feeling annoying and inconvenient."

On the pueue vs nohup side of the comparison, one caution is fair: the author never mentions nohup by name — the comparison above rests on his verified daemon facts, with the framing being this article's own. The short version: nohup detaches one process; pueue gives that process a queue, a schedule, a status board, and crash recovery. "Pueue differentiates itself" the way the author puts it against GNU Parallel too: "by focusing more on visibility across many different long running commands, and creating a central location for commands to be stored."

What Pueue Will Not Do for You

Pueue is deliberately small, and the README says so twice: "Pueue is designed to be a convenient helper tool for a single user," and "Pueue is not designed to be a heavy-duty programmable (scriptable) task scheduler/executor." "The focus of pueue lies on human interaction, i.e. it's supposed to be used by a real person on some kind of OS" — it is not cron, not Slurm, and not an orchestrator for parallel AI coding agents across machines (that lane belongs to tools like Worktrunk, which manages git worktrees for agent swarms — pueue manages shell commands on one machine; they never compete).

A few hard limits: tasks run detached in the background, so "all programs that require some kind of display/window manager won't work" — it is a non-visual environment by design. The project also considers itself "feature-complete": "all features that were planned have been added and only minor improvements, bug-fixes and regular maintenance work will get merged." That is a feature for beginners, not a gap — the tool you learn this week will not become a different tool next month.

Sources

• pueue GitHub README — github.com/Nukesor/pueue (repo tagline "Manage your shell commands."; definition, features, install routes, design goals; ~6,411 stars as of 2026-11-04; MIT and Apache-2.0 dual license; platforms "Linux is fully supported and battle-tested" / "MacOS is fully supported and on par with Linux" / "Windows is fully supported and working fine for quite a while")
• pueue GitHub wiki — Get started (daemon start, systemd user service, Windows service 4.0+, client commands, shell-escaping trap), Groups (per-group parallel, -g flags), Common Pitfalls and Debugging (sh -c wrap, & detach trap, alias note)
• pueue CHANGELOG.md on main — 4.0.4 released 2026-03-02; 4.0.5 unreleased; 4.0.0 breaking release 2025-03-09 (state wipe, protocol rework, Windows service)
• docs.rs pueue 1.0.3 archived README — the "Why should I use it" scenario and "Advantages over Using a Terminal Multiplexer" text; current README's links to these sections are dead wiki-FAQ links
• linuxcommandlibrary.com pueue man page — "Pueue (German for 'queue') was created by Arne Beer," Rust, daemon persists across terminal sessions and reboots (crawled 5 hours before writing)
• x-cmd.com pueue page — "a command-line task management tool," Rust by Nukesor, sequential/parallel long-running tasks, cross-platform
• commandmasters.com pueue-add guide — pueue add usage examples (stashed rsync pattern, double-dash flag rule)
• MacPorts pueue port page — secondary distro-packaging evidence (4.0.1 shown)
• github-wiki-see.page pueue wiki mirror — Advanced usage (aliases, callbacks, -j JSON output for status/log)

Frequently Asked Questions

Do I need to keep a terminal open for pueue to work?

No. That is the entire point: "The pueued daemon runs in the background. No need to be logged in." Start it with pueued -d or a systemd user service, and your tasks keep running with every terminal closed — you check on them from any terminal later with pueue status.

What happens to my tasks if my SSH connection drops?

Nothing bad. "The queue will be continuously processed, even if you no longer have any active ssh sessions." Reconnect, run pueue, and your queue is exactly where you left it — and if the machine itself reboots, "the queue is always saved to disk and restored on kill/system crash."

Why did my command with && do something different under pueue?

Because your shell strips the quotes before pueue sees them, and pueue wraps the result in sh -c. The author's own example — pueue add -- echo "&& rm /tmp" — would try to delete /tmp. The fix, verbatim from the wiki: "The safest way to prevent any of this, is to surround the command with quotes!" — write pueue add 'your whole command here'.

Can pueue replace tmux?

It replaces the "ten tmux sessions of long jobs" workflow, but not tmux itself. The author's answer: pueue exists because tmux lacks "the ability to queue commands and not start them all at once," per-task parallelism control, and easy pause/resume. If you want a persistent terminal to look at, use tmux; if you want a queue of jobs that run themselves, use pueue. He notes: "I used tmux for this stuff all the time before writing Pueue" — and outgrew it.

Does pueue work on Windows and macOS?

Yes. The README states all three platforms are fully supported — "Linux is fully supported and battle-tested," "MacOS is fully supported and on par with Linux," "Windows is fully supported and working fine for quite a while" — plus NetBSD as of 4.0. On Windows 4.0+ you can install pueued as a proper system service instead of using daemon mode.