Pueue task queue: verify success

By Built with Rust editorial · Published · Sources and exercise checked November 17, 2026

Use the Pueue task queue when you want to line up shell commands and inspect their outcomes. A successful enqueue is not a successful command. Capture the task ID, wait for success rather than completion, and check the output you actually need before letting the next operation depend on it.

Pueue is a Rust command-line task manager with a separate daemon, pueued, that executes queued work. Start with the Pueue project entry for upstream links, or browse Rust productivity applications for other jobs. If you need a terminal window, shell or history search instead, use the terminal workflow guide.

We ran six synthetic tasks using Pueue and pueued 4.0.4, Python 3.11.2 and Bash 5.2.15 on Linux. The exercise produced seven observations, including two different waits on the same failed task. It checks file state as well as process results. This is a functional example, not a throughput benchmark or a durability test.

Pueue task queue: separate acceptance from success

Treat a queued operation as three decisions. First, did the daemon accept the command and return the intended task ID? Second, did that task finish with a successful process result? Third, does its output satisfy the requirement? These questions need different evidence. A task ID answers the first; a success result answers the second; an artifact assertion answers the third.

In the trial, a script containing exit 7 was accepted: the add client returned 0. An ordinary wait on that ID also returned 0 after the script finished. A wait with the success target returned 1, while the stored task result retained the original failure code, 7. The wait client's code is a gate, not a copy of the child's exit code. This agrees with the pinned wait implementation.

id=$(pueue add --print-task-id -- 'your-command')
pueue wait --status success "$id"
pueue log "$id"

That sketch assumes an already configured queue and a real command you have inspected. In a script, check that add succeeded and the returned ID exists before waiting. Handle a failed wait explicitly; do not run the next step unconditionally after it. Keep the task record until verification finishes. Pueue 4.0.4's wait implementation can return success when no matching tasks remain, so an empty selection must not become evidence that work ran.

1. Prepare pinned binaries and a private queue

Use a Linux machine with Python 3.11 or later and Bash. Obtain the client and daemon from the official 4.0.4 release or your trusted package source, and check both version outputs. The exercise rejects other versions instead of silently applying these observations to a different release. It does not download software or require administrator privileges.

Download and inspect the Python success-boundary exercise. Supply absolute paths to the two executables. The script creates a temporary configuration, Unix socket and data directory, then starts its own foreground daemon. Every client call selects that configuration explicitly. It never targets your normal queue, changes your service manager or accepts a directory of your real files.

The fixture disables pause-on-failure behavior for its own daemon so failed dependencies can reach a terminal result. It supplies a small environment rather than copying your credentials into synthetic task records. The generated shell scripts only create sample files in the temporary directory. On exit, the exercise shuts down its daemon and removes that generated directory; it does not run a reset against your existing tasks.

2. Run the Pueue task queue exercise

python3 lab.py \
  --pueue /absolute/path/to/pueue \
  --pueued /absolute/path/to/pueued

Successful output is JSON containing seven check records and artifact_content_checked set to true. The script bounds individual client calls with a timeout and fails if the daemon cannot start, a task disappears, a status differs or a file assertion fails. A timeout or traceback is a failed exercise, not a slow pass. The printed task outcomes describe only this disposable run.

The first task deliberately fails. Its dependent tries to create a marker but should never execute under normal scheduling. Two independent tasks contrast an unguarded Bash pipeline with a straight-line script using set -e -o pipefail. A final producer writes sample input; its dependent checks that input and writes a confirmation. This positive control matters: checking only that a failed dependency did nothing would not establish that the queue could execute useful work.

If a result differs, keep the error locally, confirm both versions, and inspect the script before changing any assertion. Do not turn a failing check into a pass by removing the success target or accepting a missing task. The private fixture is removed after the run, so it is not a permanent log archive. Its JSON is a compact record of the checks, not a dump of a user's commands or environment.

3. Read task outcomes alongside file evidence

Observed November 17, 2026; Pueue 4.0.4, Linux, six synthetic tasks
TaskStored resultSuccess-wait exitFile evidence
Explicit exit 7Failed(7)1No output required
Depends on exit 7DependencyFailed1Blocked marker absent
Unguarded false | catSuccess0Marker present
Strict Bash pipelineFailed(1)1Strict marker absent
Sample producerSuccess0Input file present
Successful dependentSuccess0Confirmation content checked

The seventh observation is the failed task's enqueue/completion pair: both clients returned 0. That explains why a script built around add followed by ordinary wait can look green while the command failed. The dependency row supplies a stronger negative control: the task record shows DependencyFailed and the attempted output is absent. The final rows demonstrate the working path with an actual content check.

The pipeline example is a shell boundary, not a Pueue bug. Bash normally uses the last pipeline command's exit status; cat can succeed after false fails. The strict fixture uses Bash explicitly, enables pipefail and stops on this failed pipeline before writing its marker. See the Bash pipeline rules. This particular example does not establish that set -e handles every shell construct. Test the script you intend to queue.

4. Give each queued task an acceptance contract

Before queueing a real conversion, build or import, fill in the worksheet below. The useful unit is one task and one observable output, not an entire terminal session. For a report generator, the artifact check could verify required columns and a known sample row. For an archive, it could list and restore a sample into another directory. Choose checks that would fail for the wrong result.

Command and working directory:
Captured task ID and record still present:
Required successful prerequisite IDs:
Expected process result:
Expected artifact path and content assertion:
Negative control that proves the check can fail:
Observed result and local evidence location:
Retry decision after inspecting possible side effects:

Record paths and task IDs explicitly rather than assuming the newest task is yours. Retain logs until you have compared the artifact with its requirement. A command that exits zero after producing an empty or incorrect file can still be reported as successful. Use a validator inside the command when appropriate, then independently inspect the destination before a consequential next step. The worksheet is a proposed acceptance method, not a claim that Pueue validates your data for you.

For dependencies, let normal scheduling evaluate --after. The 4.0.4 CLI definitions explicitly allow start with a task ID to bypass dependencies and parallel limits. Do not use force-start as a dependency-safe recovery shortcut. A paused group can also leave dependency failure unresolved while you repair a prerequisite. Check the group state and the upstream dependency recovery guidance before reusing an existing chain; our running-queue fixture does not test that recovery path.

When Pueue is the wrong layer

Pueue is worth evaluating when the work already makes sense as commands owned by one operator: queue them, limit concurrency and inspect the results. The project's own scope describes a single-user tool rather than a shared cluster scheduler. Use a different selection process when you need multi-user authorization, distributed resource scheduling or application-level delivery guarantees. This lab establishes none of those properties.

Application jobs are a different boundary. ShipRust's background-job documentation gives a concrete example: Postgres job rows, transactional enqueueing and retrying workers. That is a useful contrast when the requirement is to commit business data and its job together, rather than queue an operator's shell command. The reference describes that implementation; it is not an endorsement or a comparative reliability test.

Even for local commands, inspect shell quoting and daemon lifecycle separately. Pueue's official pitfalls guide warns that a background ampersand can make a task finish before the detached work does. A foreground daemon is also not proof of a service surviving terminal closure. Our trial does not test logout, reboot, daemon crashes, remote connections, Windows or macOS. Start with the disposable exercise, then validate the exact environment and output your workflow needs.

Common questions

Does pueue wait fail when a task fails?

In Pueue 4.0.4, ordinary wait targets completion, including failed tasks. Use wait --status success with the actual task ID to check success. In our exercise, a task exited 7, ordinary wait returned 0, and success-wait returned 1. Keep the task record: an empty selection can also return success.

Does --after guarantee a dependent command cannot run?

Normal Pueue scheduling requires successful dependencies. Our failed-prerequisite case left the dependent marker absent and recorded DependencyFailed. Explicitly force-starting a task can bypass dependencies, however. A paused group can also defer failure propagation. Use the normal scheduler and inspect the selected records rather than treating --after as an authorization barrier.

Why can a failing pipeline look successful in Pueue?

Pueue observes the command process, not the meaning of each output. In Bash, a pipeline normally reports its last command's status. Our false-piped-to-cat script continued and produced a marker. A straight-line Bash script using set -e -o pipefail stopped instead. Confirm the intended artifact as well as the task result.

Next: inspect the Pueue source and project links, run the private exercise, and write one acceptance contract before moving real work into a queue.