### Force Task Start

Source: https://github.com/nukesor/pueue/wiki/Get-started

Use the `start` command with the `--force` flag to ignore constraints on parallel tasks and start a task immediately.

```bash
pueue start --force
```

--------------------------------

### Start and Manage Pueue Daemon

Source: https://context7.com/nukesor/pueue/llms.txt

Commands to start, daemonize, and manage the `pueued` daemon. Includes options for custom configuration and systemd/Windows service management.

```bash
pueued

# Fork into the background
pueued -d

# Use a custom config file
pueued -c /path/to/pueue.yml

# Shut the daemon down gracefully from the client
pueue shutdown

# Systemd user service (Linux)
systemctl --user start pueued
systemctl --user enable pueued   # auto-start on login
systemctl --user status pueued

# Windows service (run as Administrator)
pueued service install   # install & set to autostart
pueued service start     # start the service
pueued service stop      # stop the service
pueued service uninstall # remove the service
```

--------------------------------

### Start Tasks with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Use `pueue start` to resume tasks. You can start the default group, a specific group, all groups, or force-start specific tasks ignoring parallelism and dependencies.

```bash
pueue start
```

```bash
pueue start -g cpu
```

```bash
pueue start --all
```

```bash
pueue start 4 7
```

--------------------------------

### Add Task with Immediate Start

Source: https://github.com/nukesor/pueue/wiki/Get-started

Force a task to start immediately upon adding it using the `add` subcommand.

```bash
pueue add --force <command>
```

--------------------------------

### Enable Systemd User Service

Source: https://github.com/nukesor/pueue/wiki/Get-started

Enable the Pueue daemon to start automatically on user login.

```bash
systemctl --user enable pueued
```

--------------------------------

### Enqueue and Start Stashed Tasks

Source: https://github.com/nukesor/pueue/wiki/Get-started

Manage stashed tasks. Enqueue them for normal processing with `enqueue` or start them immediately with `start $task_id`.

```bash
pueue enqueue $task_id
```

```bash
pueue start $task_id
```

--------------------------------

### Start Pueue Windows Service

Source: https://github.com/nukesor/pueue/wiki/Get-started

Start the Pueue Windows service. This command requires administrator privileges.

```powershell
pueued service start
```

--------------------------------

### Start Systemd User Service

Source: https://github.com/nukesor/pueue/wiki/Get-started

Start the Pueue daemon as a systemd user service. This allows it to run automatically.

```bash
systemctl --user start pueued
```

--------------------------------

### Example Pueue Configuration with Profiles

Source: https://github.com/nukesor/pueue/wiki/Configuration

This YAML configuration demonstrates how to define multiple profiles, including a default shared configuration and a specific 'remote' profile overriding certain settings. Use the `--profile` flag to select a profile.

```yaml
---
shared:
  use_unix_socket: true
  host: 127.0.0.1
  port: "6924"
client:
  restart_in_place: true
  read_local_logs: true
  max_status_lines: 10
daemon:
  pause_group_on_failure: false
  pause_all_on_failure: false
profiles:
profiles:
  remote:
    shared:
      use_unix_socket: false
      host: some.remote_host.com
      port: "6924"
      daemon_cert: "~/.local/share/pueue/certs/remote_daemon.cert"
      shared_secret_path: "~/.local/share/pueue/remote_shared_secret"

```

--------------------------------

### Install Pueue Windows Service

Source: https://github.com/nukesor/pueue/wiki/Get-started

Install Pueue as a Windows service. This command requires administrator privileges.

```powershell
pueued service install
```

--------------------------------

### Install Pueue via Cargo

Source: https://github.com/nukesor/pueue/blob/main/README.md

Installs the latest stable version of Pueue using the Cargo package manager. This command installs Pueue to your Cargo bin directory.

```bash
cargo install --locked pueue
```

--------------------------------

### Configure Task Completion Callback

Source: https://github.com/nukesor/pueue/wiki/Advanced-usage

Set up a callback command in `pueue.yml` to be executed upon task completion. This example uses `notify-send` for Linux desktop notifications.

```yaml
callback: "notify-send \"Task {{ id }}\nCommand: {{ command }}\nPath: {{ path }}\nFinished with status '{{ result }}'\nTook: $(bc <<< \"{{end}} - {{start}}\") seconds\""
```

--------------------------------

### Cross Compile a Project

Source: https://github.com/nukesor/pueue/blob/main/docs/Cross.md

Use this command to build your project for a different architecture. Ensure `cargo-cross` and `qemu` are installed.

```bash
cross build --target=aarch64-unknown-linux-musl
```

--------------------------------

### Start Pueue Daemon in Background

Source: https://github.com/nukesor/pueue/wiki/Get-started

Fork and run the Pueue daemon in the background. Use `pueue shutdown` to stop it.

```bash
pueued -d
```

--------------------------------

### Resume a specific group

Source: https://github.com/nukesor/pueue/wiki/Groups

Resume all paused tasks within a specific group using the `--group` flag with the `start` command. For example, `pueue start -g cpu` resumes the 'cpu' group.

```bash
pueue start -g cpu
```

--------------------------------

### Pueue Configuration File Example

Source: https://context7.com/nukesor/pueue/llms.txt

This YAML configuration file defines settings for Pueue, including directories, network modes (Unix socket vs. TCP), host/port details, TLS certificates, client behavior, and daemon options like callbacks and environment variables. It also shows how to define multiple profiles.

```yaml
---
shared:
  pueue_directory: ~/.local/share/pueue      # task state and log storage
  use_unix_socket: true                       # false = use TCP
  unix_socket_path: ~/.local/share/pueue/pueue_myuser.socket
  host: "localhost"                           # TCP mode only
  port: "6924"                                # TCP mode only
  daemon_cert: ~/.local/share/pueue/certs/daemon.cert
  daemon_key: ~/.local/share/pueue/certs/daemon.key
  shared_secret_path: ~/.local/share/pueue/shared_secret

client:
  restart_in_place: false          # always restart in-place if true
  read_local_logs: true            # set to false for remote client
  show_confirmation_questions: false
  show_expanded_aliases: false
  dark_mode: false
  max_status_lines: null           # truncate long rows in status table
  status_time_format: "%H:%M:%S"
  status_datetime_format: "%Y-%m-%d\n%H:%M:%S"

daemon:
  pause_group_on_failure: false    # pause group when a task fails
  pause_all_on_failure: false      # pause all groups when a task fails
  callback: "notify-send \"Task {{ id }} finished with status '{{ result }}'\""
  callback_log_lines: 10           # lines available in {{ output }} template variable
  shell_command: ["bash", "-c", "{{ pueue_command_string }}"]  # custom shell
  env_vars:
    MY_ENV: "injected into every task"

# Multiple profiles in one file
profiles:
  remote:
    shared:
      use_unix_socket: false
      host: myserver.example.com
      port: "6924"
      daemon_cert: ~/.local/share/pueue/certs/remote_daemon.cert
      shared_secret_path: ~/.local/share/pueue/remote_shared_secret
    client:
      read_local_logs: false

```

--------------------------------

### Pause and Start Specific Tasks

Source: https://github.com/nukesor/pueue/wiki/Get-started

Pause or start individual tasks by providing their IDs. This does not affect the daemon's state or other tasks.

```bash
pueue pause 1
```

```bash
pueue start 1
```

--------------------------------

### Using Pueue Aliases

Source: https://context7.com/nukesor/pueue/llms.txt

Add commands using aliases to have them automatically expanded. For example, 'ls /home' will be expanded based on the 'ls' alias defined in your `pueue_aliases.yml`.

```bash
# "ls" is expanded to "ls -ahl --color=auto /home"
pueue add 'ls /home'

# Show the expanded command in status view
# (set show_expanded_aliases: true in client config)
pueue status

```

--------------------------------

### Send Add Request to Pueue Daemon with Rust

Source: https://context7.com/nukesor/pueue/llms.txt

This Rust example demonstrates how to send an 'Add' request to the Pueue daemon using the pueue-lib crate. It requires loading settings, creating a client, constructing an AddMessage, and sending it.

```rust
use pueue_lib::
client::Client,
message::{AddMessage, Message},
settings::Settings,
;

#[tokio::main]
async fn main() -> color_eyre::Result<()> {
    let settings = Settings::load(None, None)?;
    let mut client = Client::new(settings).await?;

    let add_msg = Message::Add(AddMessage {
        command: "sleep 30".to_string(),
        path: std::env::current_dir()?,
        envs: std::env::vars().collect(),
        start_immediately: false,
        stashed: false,
        group: "default".to_string(),
        dependencies: vec![],
        label: Some("my rust task".to_string()),
        priority: None,
        delay_until: None,
        print_task_id: false,
    });

    let response = client.send_request(add_msg).await?;
    println!("{response:?}");
    Ok(())
}
```

--------------------------------

### Start Pueue Daemon Locally

Source: https://github.com/nukesor/pueue/wiki/Get-started

Run the Pueue daemon in the current shell. The daemon will exit when the terminal is closed.

```bash
pueued
```

--------------------------------

### Multiline Callback Script

Source: https://github.com/nukesor/pueue/wiki/Advanced-usage

For complex callbacks, define them in an external file or use a multiline YAML string. This example uses `notify-send` with multiple lines for better readability.

```yaml
callback: |
    notify-send \
    "Task {{ id }}
    Command: {{ command }}
    Path: {{ path }}
    Finished with status '{{ result }}'"
```

--------------------------------

### Add a new group

Source: https://github.com/nukesor/pueue/wiki/Groups

Use the `group add` command to create a new group. For example, `pueue group add cpu` creates a group named 'cpu'.

```bash
pueue group add cpu
```

--------------------------------

### Add a Simple Command to Pueue

Source: https://github.com/nukesor/pueue/wiki/Get-started

Add a basic command to the Pueue queue. For example, `sleep 60`.

```bash
pueue add sleep 60
```

--------------------------------

### Pause and Resume All Tasks

Source: https://github.com/nukesor/pueue/wiki/Get-started

Use `pueue pause` to pause all running tasks and the daemon. Resume normal operation with `pueue start`.

```bash
pueue pause
```

```bash
pueue start
```

--------------------------------

### Get Task Log

Source: https://github.com/nukesor/pueue/wiki/Get-started

View the output log of a specific task using its task ID.

```bash
pueue log $task_id
```

--------------------------------

### Remote Connection via TLS

Source: https://context7.com/nukesor/pueue/llms.txt

Connect a local Pueue client to a remote daemon over an encrypted TCP connection. This requires configuring the daemon to use TCP and copying TLS certificates and shared secrets to the client machine. Alternatively, use SSH port forwarding for a simpler setup without explicit TLS configuration.

```bash
# On the remote server — edit pueue.yml:
# shared:
#   use_unix_socket: false
#   host: "0.0.0.0"
#   port: "6924"
# Then restart the daemon:
pueued -d

# Copy cert and secret to the client machine
scp user@server:~/.local/share/pueue/certs/daemon.cert ./remote_daemon.cert
scp user@server:~/.local/share/pueue/shared_secret ./remote_shared_secret

# Client config for remote (e.g. ~/.config/pueue/remote.yml):
# shared:
#   use_unix_socket: false
#   host: myserver.example.com
#   port: "6924"
#   daemon_cert: ~/remote_daemon.cert
#   shared_secret_path: ~/remote_shared_secret
# client:
#   read_local_logs: false

pueue -c ~/.config/pueue/remote.yml status

# Or SSH port-forwarding (no TLS config needed)
ssh -L 127.0.0.1:6924:127.0.0.1:6924 user@myserver &
pueue status   # connects to local port which is forwarded to the server

# SSH Unix-socket forwarding
ssh -L /tmp/local.sock:/home/user/.local/share/pueue/pueue_user.sock user@myserver &

```

--------------------------------

### Rust Test Function with test-log Macro

Source: https://github.com/nukesor/pueue/wiki/Development

Example of a Rust asynchronous test function using the `test_log::test` macro for debug logging. Ensure the test is annotated with this macro to capture logs.

```rust
use test_log::test;

// ...

#[test(tokio::test(flavor = "multi_thread", worker_threads = 2))]
/// Test if adding a normal task works as intended.
async fn test_edit_flow() -> Result<()> {
```

--------------------------------

### Pueue Fuzzy Finder Script

Source: https://github.com/nukesor/pueue/wiki/Advanced-usage

A shell script function that integrates Pueue with fzf for an interactive fuzzy finder experience. It allows for quick searching, filtering, and performing actions on tasks directly from the fzf interface. Assumes `jq`, `fzf`, and `bat` are installed.

```shell
pf() {
  set -f
  local PUEUE_TASKS="pueue status --json | jq -c '.tasks' | jq -r '.[] | \"\(.id | tostring | (\" \" * (2 - length)) + .) | \(.group) | \(.path[-15:]) | \(.status) | \(.command[-15:]) | \(.start[:19])\"'"
  local header="p:pause | s:start | r:restart | k:kill | l:log | f:reload"

local bind="\
ctrl-p:execute-silent(echo {} | cut -d'|' -f1 | xargs pueue pause > /dev/null)+reload^$PUEUE_TASKS^,\
ctrl-s:execute-silent(echo {} | cut -d'|' -f1 | xargs pueue start > /dev/null)+reload^$PUEUE_TASKS^,\
ctrl-r:execute-silent(echo {} | cut -d'|' -f1 | xargs pueue restart -ik > /dev/null)+reload^$PUEUE_TASKS^,\
ctrl-k:execute-silent(echo {} | cut -d'|' -f1 | xargs pueue kill > /dev/null)+reload^$PUEUE_TASKS^,\
ctrl-l:execute-silent(echo {} | cut -d'|' -f1 | xargs pueue log | less > /dev/tty),\ 
ctrl-f:reload^$PUEUE_TASKS^\
"

  echo $PUEUE_TASKS | sh | fzf --header "${header}" -m \
    --preview="echo {} | cut -d'|' -f1 | xargs pueue log | bat -l log --style=rule,numbers --color=always -r ':200'" \
    --bind="$bind"
  set +f
}
```

--------------------------------

### Filter JSON Status Output with JQ

Source: https://github.com/nukesor/pueue/wiki/Advanced-usage

Use `pueue status --json` combined with `jq` to filter and format task information. This example extracts only the tasks array.

```sh
pueue status --json | jq -c '.tasks' | pueue format-status
```

--------------------------------

### wget progress with dot format

Source: https://github.com/nukesor/pueue/wiki/Advanced-usage

Demonstrates how to use wget with the --show-progress and --progress=dot:mega flags for verbose dot output. This is useful for visualizing download progress in single-line summaries.

```bash
$ wget https://www.example.com/sample_file.zip -q --show-progress --progress=dot:mega
Resolving www.example.com (www.example.com)... 233.252.0.127
Connecting to www.example.com (www.example.com)|233.252.0.127|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 222882919 (213M) [application/zip]

     0K ........ ........ ........ ........ ........ ........  1% 40.4K 88m33s
  3072K ........ ........ ........ ........ ........ ........  2% 39.9K 87m50s
  6144K ........ ........ ........ ........ ........ ........  4% 39.9K 86m45s
  9216K ........ ........ ........ ........ ........ ...

```

```bash
        [ skipping 215040K ]
215040K ,,,,,,,, ,,,,,,,, ,,,,,,,, ,,,..... ........ 

```

--------------------------------

### Pause a specific group

Source: https://github.com/nukesor/pueue/wiki/Groups

Pause all tasks within a specific group and prevent new tasks from starting in that group using the `--group` flag with the `pause` command. For example, `pueue pause -g cpu` pauses the 'cpu' group.

```bash
pueue pause -g cpu
```

--------------------------------

### Cross Test a Project

Source: https://github.com/nukesor/pueue/blob/main/docs/Cross.md

Run your project's tests on a target architecture using `cross test`. This requires `cargo-cross` and `qemu` to be set up.

```bash
cross test --target=aarch64-unknown-linux-musl
```

--------------------------------

### Using Custom Pueue Config and Profiles

Source: https://context7.com/nukesor/pueue/llms.txt

Specify a custom configuration file using the -c flag or the PUEUE_CONFIG_PATH environment variable. You can also select a named profile from your configuration file using the --profile flag.

```bash
# Use a specific config file
pueue -c /path/to/pueue.yml status
# Or via environment variable
export PUEUE_CONFIG_PATH=/path/to/pueue.yml

# Use a named profile from the config
pueue --profile remote status

```

--------------------------------

### Get Pueue Status

Source: https://github.com/nukesor/pueue/wiki/Get-started

Display the status of all tasks currently in the Pueue queue. `pueue` is a shortcut.

```bash
pueue status
```

--------------------------------

### Build Pueue from Source

Source: https://github.com/nukesor/pueue/blob/main/README.md

Clones the Pueue repository and builds the release version from source using Cargo. The compiled binaries will be found in the target/release directory.

```bash
git clone git@github.com:Nukesor/pueue
cd pueue
cargo build --release --locked --path ./pueue
```

--------------------------------

### Pueue CLI Options

Source: https://github.com/nukesor/pueue/blob/main/README.md

Common command-line options for Pueue. Use -p to specify a profile, -h for help, and -V for version.

```bash
-p, --profile <PROFILE>  The name of the profile that should be loaded from your config file
-h, --help               Print help
-V, --version            Print version
```

--------------------------------

### Interactive Task Finder with fzf and jq

Source: https://context7.com/nukesor/pueue/llms.txt

An interactive fuzzy finder for Pueue tasks using `fzf` and `jq`. It displays task ID, status, and command, allowing actions like viewing logs, killing, or restarting tasks.

```bash
pf() {
  local TASKS="pueue status --json | jq -c '.tasks' | jq -r '.[] | \"\(.id) | \(.status) | \(.command[-30:])\"'"
  echo $TASKS | sh | fzf \
    --preview "echo {} | cut -d'|' -f1 | xargs pueue log" \
    --bind "ctrl-k:execute-silent(echo {} | cut -d'|' -f1 | xargs pueue kill)+reload($TASKS | sh)" \
    --bind "ctrl-r:execute-silent(echo {} | cut -d'|' -f1 | xargs pueue restart)+reload($TASKS | sh)"
}
```

--------------------------------

### Remove an existing group

Source: https://github.com/nukesor/pueue/wiki/Groups

Use the `group remove` command to delete an existing group. For example, `pueue group remove cpu` removes the 'cpu' group.

```bash
pueue group remove cpu
```

--------------------------------

### Pueue Daemon Callback Configuration

Source: https://context7.com/nukesor/pueue/llms.txt

Configure a shell command to run after each task completes using the 'callback' option in the daemon configuration. Template variables like {{ id }}, {{ command }}, and {{ result }} are available for dynamic messages. Ensure 'callback_log_lines' is set appropriately if using {{ output }}.

```yaml
# Desktop notification on Linux
daemon:
  callback: "notify-send \"Task {{ id }}\nCommand: {{ command }}\nPath: {{ path }}\nStatus: {{ result }}\nTook: $(bc <<< '{{ end }} - {{ start }}') seconds""
  callback_log_lines: 10

# macOS notification
daemon:
  callback: "osascript -e 'display notification \"{{ result }}\" with title \"Pueue #{{ id }}\" subtitle \"{{ command }}\"""

```

--------------------------------

### Run Test Suite in a Loop (cargo test)

Source: https://github.com/nukesor/pueue/wiki/Development

Continuously runs the test suite using the default `cargo test` command to identify flaking tests. Minimizes output for successful runs.

```shell
while cargo test --quiet
do :; done
```

--------------------------------

### Add Groups and Set Parallelism

Source: https://github.com/nukesor/pueue/wiki/Get-started

Use these commands to create distinct groups and define the number of parallel tasks allowed within each group. This sets up the foundation for worker pool simulation.

```bash
pueue group add cluster_1
pueue group add cluster_2

pueue parallel 2 -g cluster_1
pueue parallel 1 -g cluster_2
```

--------------------------------

### Run Test Suite in a Loop (cargo nextest)

Source: https://github.com/nukesor/pueue/wiki/Development

Continuously runs the test suite using `cargo nextest` to quickly identify flaking tests. Minimizes output for successful runs.

```shell
while cargo nextest run --workspace --hide-progress-bar --status-level=fail
do :; done
```

--------------------------------

### Pause Tasks with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Use `pueue pause` to stop new tasks from starting. You can pause the default group, a specific group, specific tasks, or pause a group while letting running tasks finish.

```bash
pueue pause
```

```bash
pueue pause -g io
```

```bash
pueue pause 2 5
```

```bash
pueue pause --wait -g cpu
```

--------------------------------

### Define Task Dependencies with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Chain tasks together so that each task only runs after its predecessor has successfully completed. Use `--print-task-id` to capture task IDs for subsequent `--after` arguments.

```bash
# Step 1: download data
T1=$(pueue add --print-task-id 'wget https://example.com/data.tar.gz')

# Step 2: extract (only after download succeeds)
T2=$(pueue add --print-task-id --after $T1 'tar -xzf data.tar.gz')

# Step 3: process (only after extract succeeds)
T3=$(pueue add --print-task-id --after $T2 'python process.py data/')

# Step 4: upload result (only after process succeeds)
pueue add --after $T3 'rsync -avz results/ user@server:/results/'

# Combine with pause_on_failure to halt queue on first error
# (set in pueue.yml: daemon:
#   pause_group_on_failure: true)
# Then after fixing, restart the failed task in-place to resume the chain:
pueue restart --in-place $T2
```

--------------------------------

### Add a task to a specific group

Source: https://github.com/nukesor/pueue/wiki/Groups

Assign a task to a specific group using the `-g` flag with the `add` command. For example, `pueue add -g cpu -- 'sleep 60'` adds the 'sleep 60' task to the 'cpu' group.

```bash
pueue add -g cpu -- 'sleep 60'
```

--------------------------------

### Specify Task Dependencies

Source: https://github.com/nukesor/pueue/wiki/Get-started

Define dependencies for tasks using the `--after/-a` flag with the `add` command. A task only runs if all its dependencies were successful.

```bash
pueue add --after/-a <dependency_task_id> <command>
```

--------------------------------

### Generate Shell Completions for Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Generates shell completions for bash, zsh, and fish. Place the output in the respective completion directories for your shell.

```bash
pueue completions bash ~/.bash_completion.d/
pueue completions zsh  /usr/share/zsh/site-functions/
pueue completions fish ~/.config/fish/completions/
```

--------------------------------

### Add pueue-lib to Cargo.toml

Source: https://context7.com/nukesor/pueue/llms.txt

Add the pueue-lib crate to your Cargo.toml file to enable programmatic interaction with the Pueue daemon. Ensure you include the 'client' and 'network' features.

```toml
[dependencies]
pueue-lib = { version = "0.31", features = ["client", "network"] }
```

--------------------------------

### List all existing groups

Source: https://github.com/nukesor/pueue/wiki/Groups

Call the `group` command without any parameters to display all currently existing groups.

```bash
pueue group
```

--------------------------------

### macOS Notification Callback

Source: https://github.com/nukesor/pueue/wiki/Advanced-usage

Configure a callback for macOS using `osascript` to display task completion notifications.

```yaml
callback: "osascript -e 'display notification \"Finished with status {{ result }}\" with title \"Pueue task {{ id }}\" subtitle \"{{ command }}\""
```

--------------------------------

### Default Pueue Configuration File

Source: https://github.com/nukesor/pueue/wiki/Configuration

This is the default configuration file for Pueue, showcasing all available options for shared, client, and daemon settings. Most values can be omitted to use their default.

```yaml
---
shared:
  pueue_directory: ~/.local/share/pueue
  use_unix_socket: true
  runtime_directory: null
  unix_socket_path: ~/.local/share/pueue/pueue_your_user.socket
  host: "localhost"
  port: "6924"
  daemon_cert: ~/.local/share/pueue/certs/daemon.cert
  daemon_key: ~/.local/share/pueue/certs/daemon.key
  shared_secret_path: ~/.local/share/pueue/shared_secret

client:
  restart_in_place: false
  read_local_logs: true
  show_confirmation_questions: false
  show_expanded_aliases: false
  dark_mode: false
  max_status_lines: null
  status_time_format: "%H:%M:%S"
  status_datetime_format: "%Y-%m-%d\n%H:%M:%S"

daemon:
  pause_group_on_failure: false
  pause_all_on_failure: false
  callback: "Task {{ id }}\nCommand: {{ command }}\nPath: {{ path }}\nFinished with status '{{ result }}'"
  callback_log_lines: 10
  shell_command: ["zsh", "-c", "{{ pueue_command_string }}"]
  env_vars:
    BASH_ENV: "$HOME/.config/shell_aliases"

```

--------------------------------

### Follow Task Output

Source: https://github.com/nukesor/pueue/wiki/Get-started

Continuously stream the output of a running task. Use the `-e` flag to follow stderr.

```bash
pueue follow $task_id
```

--------------------------------

### Restart Tasks with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Use `pueue restart` to re-enqueue completed tasks. You can restart specific tasks, restart in-place, restart all failed tasks, or restart with modifications.

```bash
pueue restart 3 5
```

```bash
pueue restart --in-place 3
```

```bash
pueue restart --all-failed
```

```bash
pueue restart --failed-in-group cpu
```

```bash
pueue restart --immediate 3
```

```bash
pueue restart --stashed 3
```

```bash
pueue restart --edit 3
```

--------------------------------

### Check Systemd User Service Status

Source: https://github.com/nukesor/pueue/wiki/Get-started

Verify that the Pueue daemon is running as a systemd user service.

```bash
systemctl --user status pueued
```

--------------------------------

### Add Task with Delay

Source: https://github.com/nukesor/pueue/wiki/Get-started

Schedule a task to run after a specified delay using the `add` subcommand.

```bash
pueue add --delay 5h <command>
```

--------------------------------

### Restart Failed Task with Dependencies

Source: https://github.com/nukesor/pueue/wiki/Get-started

Restart a failed task in-place using the `--in-place` flag to allow dependent tasks to continue processing.

```bash
pueue restart --in-place <failed_task_id>
```

--------------------------------

### Retrieve Task Log Output via JSON

Source: https://context7.com/nukesor/pueue/llms.txt

Fetch the standard output of a specific task using `pueue log --json` and parse it with `jq`. The `-r` flag in jq outputs the raw string, removing quotes.

```bash
pueue log --json 5 | jq -r '.["5"].output'
```

--------------------------------

### jq script for parsing wget logs

Source: https://github.com/nukesor/pueue/wiki/Advanced-usage

A jq script designed to parse Pueue's JSON logs, specifically targeting wget download output. It summarizes progress, handles skipped data, and formats task labels with color.

```jq
# for use with pueue log --json
# Usage: pueue log -j | jq -r --arg group [groupname] -f [path to this file]
# where 'groupname' is the pueue task group that outputs wget download logs
# if omitted, defaults to "download"

# ANSI color functions
def _ansi_bright($c): tostring | "\u001b[\($c);1m\(.)\u001b[0m";
def red:    _ansi_bright(31);
def green:  _ansi_bright(32);

[
    .[]
    | select(
        .task.group==($ARGS.group // "download")
        and .task.status!="Queued"
        and .task.status!{"Done": "Success"}
    )
    | (
        if .task.status=="Running"
            then ("\(.task.label)" | green)
            else ("\(.task.label)" | red)
        end
    ) as $task_label
    | (
        .output
        | split("\n")[-2:]
        | join(" ")
        | gsub("\\.{8} "; "\u2026")               # ........ -> U+2026 HORIZONTAL ELLIPSIS
        | gsub(",[.,]{7} "; "\u223f")             # ,,,,.... -> U+223F SINE WAVE
        | sub("(?<e>[\u2026\u223f]+)"; "\(.e) ")  # keep the last space
    ) as $shortened
    | "\(.task.id): \($task_label): \($shortened)"
)
| join("\n")

```

--------------------------------

### Summarize Job States with JQ Script

Source: https://github.com/nukesor/pueue/wiki/Advanced-usage

Process `pueue status -j` output using a `jq` script to generate a summary of task states. Requires `jq` version 1.6 or newer.

```sh
pueue status -j | jq -r -f <path_to_the_script>
```

--------------------------------

### Generate Shell Completions for Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Generate shell completion scripts for your shell (e.g., bash, zsh, fish) to enable tab-completion for Pueue commands and flags. This enhances usability by providing interactive command-line assistance.

```bash
# Example for bash:
# source <(pueue --completion bash)
# For permanent installation, add the above line to your ~/.bashrc

```

--------------------------------

### Inspect Task Logs with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Retrieve stdout/stderr logs for tasks. Supports specific task IDs, ranges, line limits, JSON output, and live log following.

```bash
# Show log of the most recent task
pueue log

# Show log for specific task IDs
pueue log 3
pueue log 0 1 2 3

# Show log for a range (shell brace expansion)
pueue log {0..5}

# Show last 50 lines of a task's log
pueue log --lines 50 7

# JSON output (includes task metadata + output text)
pueue log --json
pueue log --json 4 5

# Follow the live output of a running task (like tail -f)
pueue follow 3

# Follow stderr instead of stdout
pueue follow --err 3
```

--------------------------------

### Stash and Enqueue Tasks with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Use `pueue stash` to hold tasks and `pueue enqueue` to release them. You can stash or enqueue individual tasks, all tasks in a group, or all tasks across all groups.

```bash
pueue stash 5
```

```bash
pueue stash --group cpu
```

```bash
pueue stash --all
```

```bash
pueue enqueue 5
```

```bash
pueue enqueue --group cpu
```

```bash
pueue enqueue --all
```

```bash
pueue enqueue --delay '1 week' 5
```

```bash
pueue enqueue --delay '2025-06-01 09:00' 5
```

--------------------------------

### Add Command with Flags to Pueue

Source: https://github.com/nukesor/pueue/wiki/Get-started

Add a command with flags to the Pueue queue. Use `--` to separate Pueue flags from command flags.

```bash
pueue add -- ls -al /tmp/no_spaces_allowed
```

--------------------------------

### SSH Port Forwarding for Pueue

Source: https://github.com/nukesor/pueue/wiki/Connect-to-remote

Use this command to forward a local port to the remote Pueue daemon's port. This allows your local client to connect to the remote daemon as if it were local.

```bash
ssh -L 127.0.0.1:6924:127.0.0.1:6924 $REMOTE_USER@yourhost
```

--------------------------------

### Add Tasks to the Queue with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Enqueue shell commands to Pueue with various options like immediate execution, stashing, delayed execution, group assignment, labels, priority, and scripting.

```bash
# Basic usage — enqueue a simple command
pueue add sleep 60

# Commands with flags: use -- to separate pueue flags from command flags
pueue add -- ls -al /tmp/some\ directory

# Safest: wrap in quotes to preserve shell escaping
pueue add 'rsync -avz /src/ /dst/ && echo "Done"'

# Start immediately (skip the queue)
pueue add --immediate 'tar -czf archive.tar.gz /large/dir'

# Start immediately AND follow its output live
pueue add --immediate --follow 'make all'

# Stash (don't run until manually enqueued or started)
pueue add --stashed 'heavy_job --input data.bin'

# Delay execution by 3 hours
pueue add --delay '3h' 'backup.sh'

# Delay until a specific date/time
pueue add --delay '2025-12-01 02:00' 'nightly_report.sh'

# Assign to a group
pueue add -g cpu 'ffmpeg -i input.mp4 output.mkv'

# Add with a label shown in status view
pueue add --label "encode movie" 'ffmpeg -i film.mkv film.mp4'

# Set priority (higher = scheduled sooner)
pueue add --priority 10 'important_task.sh'

# Only print the task ID (useful for scripting with --after)
TASK_ID=$(pueue add --print-task-id 'step1.sh')
pueue add --after $TASK_ID 'step2.sh'

# Run with escaped arguments (disables && and shell syntax)
pueue add --escape -- myprogram "arg with spaces" "another&arg"
```

--------------------------------

### Send input to a process waiting for confirmation

Source: https://github.com/nukesor/pueue/wiki/Common-Pitfalls-and-Debugging

If a process requires user input (e.g., 'y/n' confirmation), use the `pueue send` subcommand to provide the necessary input. Ensure to include a newline character if the input requires it.

```bash
pueue send "y\n"
```

--------------------------------

### Manipulate Multiple Tasks

Source: https://github.com/nukesor/pueue/wiki/Get-started

Execute commands on multiple tasks at once by listing their IDs or using shell range parameters.

```bash
pueue log 0 1 2 3 15 19
```

```bash
pueue log {0..3} 15 19
```

--------------------------------

### Manage Task Groups with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Use `pueue group` to manage task groups, which act as separate queues. You can list, create, remove, and configure groups, as well as add tasks to them.

```bash
pueue group
```

```bash
pueue group --json
```

```bash
pueue group add cpu
```

```bash
pueue group add io
```

```bash
pueue group add downloads
```

```bash
pueue group remove downloads
```

```bash
pueue add -g cpu 'ffmpeg -i input.mkv output.mp4'
```

```bash
pueue parallel -g cpu 2
```

```bash
pueue parallel -g io 1
```

```bash
pueue status --group cpu
```

```bash
pueue pause -g cpu
```

```bash
pueue start -g cpu
```

```bash
pueue group add cluster_1
```

```bash
pueue group add cluster_2
```

```bash
pueue parallel 2 -g cluster_1
```

```bash
pueue parallel 1 -g cluster_2
```

```bash
pueue add -g cluster_1 -- './gpu_job --gpu $PUEUE_WORKER_ID --cluster $PUEUE_GROUP'
```

```bash
pueue add -g cluster_1 -- './gpu_job --gpu $PUEUE_WORKER_ID --cluster $PUEUE_GROUP'
```

```bash
pueue add -g cluster_2 -- './gpu_job --gpu $PUEUE_WORKER_ID --cluster $PUEUE_GROUP'
```

--------------------------------

### Send Input to Tasks with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Use `pueue send` to send input to a running task's stdin. This is useful for interactive prompts or providing data to tasks.

```bash
pueue send 4 "y
"
```

```bash
pueue send 2 "mysecretpassword
"
```

--------------------------------

### Switch Task Order with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Use `pueue switch` to reorder tasks in the queue by swapping their positions.

```bash
pueue switch 3 7
```

--------------------------------

### Control Tasks with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Commands to resume, pause, or kill tasks and groups within Pueue.

```bash
# Resume a paused task
pueue start 1

# Pause a running task
pueue pause 1

# Kill a running task
pueue kill 1

# Kill all tasks in a group
pueue kill --group cpu

# Kill all tasks in the queue
pueue kill --all
```

--------------------------------

### View Task Status with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Display task status with filtering, ordering, and column selection. Supports JSON output for scripting and piping to other commands.

```bash
# Show all tasks (default view)
pueue status
# Shortcut
pueue

# Show only tasks in a specific group
pueue status --group cpu

# JSON output (useful for scripting)
pueue status --json

# Filter by status
pueue status "status=Running"
pueue status "status!=Done"

# Filter by label substring
pueue status "label %= encode"

# Filter by command substring
pueue status "command %= ffmpeg"

# Order by start time descending
pueue status "order_by start desc"

# Limit output to last 5 tasks
pueue status "last 5"

# Select only specific columns
pueue status "columns=id,status,command,label"

# Combined query: filter + order + limit
pueue status "status=Done order_by end desc last 10"

# Pipe JSON through jq and re-render the table
pueue status --json | jq -c '.tasks | to_entries | map(select(.value.status=="Running")) | from_entries' | pueue format-status
```

--------------------------------

### Define Aliases with YAML

Source: https://github.com/nukesor/pueue/wiki/Advanced-usage

Configure custom aliases in `pueue_aliases.yml` to shorten frequently used commands. The first word of a task command is checked against these aliases.

```yaml
ls: 'ls -ahl'
rsync: 'rsync --recursive --partial --perms --progress'
```

--------------------------------

### Pueue Alias Configuration

Source: https://context7.com/nukesor/pueue/llms.txt

Define command aliases in a `pueue_aliases.yml` file to shorten frequently used commands. The alias replaces the first word of an added command. You can view expanded commands in the status view if `show_expanded_aliases` is enabled in the client configuration.

```yaml
# ~/.config/pueue/pueue_aliases.yml
ls: 'ls -ahl --color=auto'
rsync: 'rsync --recursive --partial --perms --progress --human-readable'
ffmpeg: 'ffmpeg -hide_banner -loglevel warning'

```

--------------------------------

### Debug Flaking Test (daemon::edit::test_edit_flow) with cargo nextest

Source: https://github.com/nukesor/pueue/wiki/Development

Runs a specific test (`daemon::edit::test_edit_flow`) in a loop with debug logging enabled to capture detailed information during failures. Uses `cargo nextest`.

```shell
while RUST_LOG=debug cargo nextest run --workspace --hide-progress-bar --status-level=fail \
    daemon::edit::test_edit_flow
do :; done
```

--------------------------------

### SSH Unix Socket Forwarding for Pueue

Source: https://github.com/nukesor/pueue/wiki/Connect-to-remote

This command forwards a local Unix socket to a remote Unix socket used by Pueue. This is an alternative to port forwarding for Unix socket communication.

```bash
ssh -L /tmp/local.socket:/home/$REMOTE_USER/.local/share/pueue/pueue_$REMOTE_USER.sock $REMOTE_USER@yourhost
```

--------------------------------

### Add Tasks with Worker ID and Group Variables

Source: https://github.com/nukesor/pueue/wiki/Get-started

Add tasks to specific groups, incorporating the `$PUEUE_WORKER_ID` and `$PUEUE_GROUP` environment variables into the command. This ensures tasks are aware of their assigned worker and group.

```bash
pueue add -g cluster1 -- './run_on_gpu_pool experiment1 --gpu $PUEUE_WORKER_ID --cluster $PUEUE_GROUP'
pueue add -g cluster1 -- './run_on_gpu_pool experiment2 --gpu $PUEUE_WORKER_ID --cluster $PUEUE_GROUP'
pueue add -g cluster2 -- './run_on_gpu_pool experiment3 --gpu $PUEUE_WORKER_ID --cluster $PUEUE_GROUP'
pueue add -g cluster2 -- './run_on_gpu_pool experiment4 --gpu $PUEUE_WORKER_ID --cluster $PUEUE_GROUP'
```

--------------------------------

### Debug Flaking Test (daemon::edit::test_edit_flow) with cargo test

Source: https://github.com/nukesor/pueue/wiki/Development

Runs a specific test (`daemon::edit::test_edit_flow`) in a loop with debug logging enabled to capture detailed information during failures. Uses the default `cargo test` command.

```shell
while RUST_LOG=debug cargo test --workspace --quiet \
    --test daemon_tests daemon::edit::test_edit_flow
do :; done
```

--------------------------------

### View status of a specific group

Source: https://github.com/nukesor/pueue/wiki/Groups

By default, `status` shows all groups with tasks. To view tasks for a specific group, use the `--group $NAME` option, e.g., `pueue status --group cpu`.

```bash
pueue status --group cpu
```

--------------------------------

### Add command with spaces and special characters

Source: https://github.com/nukesor/pueue/wiki/Common-Pitfalls-and-Debugging

When a command contains spaces or characters that require escaping, encapsulate the entire command string. This ensures that character escaping is correctly transferred to the `sh -c` execution context.

```bash
pueue add -- ls -al "/tmp/this\ is\ a\ test\ directory"
```

--------------------------------

### Kill Tasks with Pueue

Source: https://context7.com/nukesor/pueue/llms.txt

Use `pueue kill` to terminate tasks. You can kill tasks in the default group, specific tasks, all tasks across all groups, or send a specific UNIX signal.

```bash
pueue kill
```

```bash
pueue kill 3 6
```

```bash
pueue kill --all
```

```bash
pueue kill --signal sigterm 4
```

```bash
pueue kill --signal int 4
```

```bash
pueue kill --signal 15 4
```