pueue-*: add page (#5285)

pages/common/pueue-add.md

@@ -0,0 +1,28 @@
+# pueue add
+
+> Enqueue a task for execution.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Add any command to the default queue:
+
+`pueue add {{command}}`
+
+- Pass a list of flags or arguments to a command when enqueuing:
+
+`pueue add -- {{command --arg -f}}`
+
+- Add a command but do not start it if it's the first in a queue:
+
+`pueue add --stashed -- {{rsync --archive --compress /local/directory /remote/directory}}`
+
+- Add a command to a group and start it immediately, see `pueue group` to manage groups:
+
+`pueue add --immediate --group "{{CPU_intensive}}" -- {{ffmpeg -i input.mp4 frame_%d.png}}`
+
+- Add a command and start it after commands 9 and 12 finish successfully:
+
+`pueue add --after {{9}} {{12}} --group "{{torrents}}" -- {{transmission-cli torrent_file.torrent}}`
+
+- Add a command with a label after some delay has passed, see `pueue enqueue` for valid datetime formats:
+
+`pueue add --label "{{compressing large file}}" --delay "{{wednesday 10:30pm}}" -- "{{7z a compressed_file.7z large_file.xml}}"`

pages/common/pueue-clean.md

@@ -0,0 +1,12 @@
+# pueue clean
+
+> Remove all finished tasks from the list and clear logs.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Remove finished tasks and clear logs:
+
+`pueue clean`
+
+- Only clean commands that finished successfully:
+
+`pueue clean --successful-only`

pages/common/pueue-completions.md

@@ -0,0 +1,16 @@
+# pueue completions
+
+> Generates shell completion files for bash, elvish, fish, powershell, and zsh.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Generate completions for bash:
+
+`sudo pueue completions bash {{/usr/share/bash-completion/completions/pueue.bash}}`
+
+- Generate completions for zsh:
+
+`sudo pueue completions zsh {{/usr/share/zsh/site-functions}}`
+
+- Generate completions for fish:
+
+`sudo pueue completions fish {{/usr/share/fish/completions}}`

pages/common/pueue-edit.md

@@ -0,0 +1,16 @@
+# pueue edit
+
+> Edit the command or path of a stashed or queued task.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Edit a task, see `pueue status` to get the task ID:
+
+`pueue edit {{task_id}}`
+
+- Edit the path from which a task is executed:
+
+`pueue edit {{task_id}} --path`
+
+- Edit a command with the specified editor:
+
+`EDITOR={{nano}} pueue edit {{task_id}}`

pages/common/pueue-enqueue.md

@@ -0,0 +1,29 @@
+# pueue enqueue
+
+> Enqueue stashed tasks.
+> See also: `pueue stash`.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Enqueue multiple stashed tasks at once:
+
+`pueue enqueue {{task_id}} {{task_id}}`
+
+- Enqueue a stashed task after 60 seconds:
+
+`pueue enqueue --delay {{60}} {{task_id}}`
+
+- Enqueue a stashed task next Wednesday:
+
+`pueue enqueue --delay {{wednesday}} {{task_id}}`
+
+- Enqueue a stashed task after four months:
+
+`pueue enqueue --delay "4 months" {{task_id}}`
+
+- Enqueue a stashed task on 2021-02-19:
+
+`pueue enqueue --delay {{2021-02-19}} {{task_id}}`
+
+- List all available date/time formats:
+
+`pueue enqueue --help`

pages/common/pueue-follow.md

@@ -0,0 +1,13 @@
+# pueue follow
+
+> Follow the output of a currently running task.
+> See also: `pueue log`.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Follow the output of a task (stdout + stderr):
+
+`pueue follow {{task_id}}`
+
+- Follow the stderr of a task:
+
+`pueue follow --err {{task_id}}`

pages/common/pueue-group.md

@@ -0,0 +1,16 @@
+# pueue group
+
+> Display, add or remove groups.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Show all groups with their statuses and number of parallel jobs:
+
+`pueue group`
+
+- Add a custom group:
+
+`pueue group --add "{{group_name}}"`
+
+- Remove a group and move its tasks to the default group:
+
+`pueue group --remove "{{group_name}}"`

pages/common/pueue-help.md

@@ -0,0 +1,12 @@
+# pueue help
+
+> Display help for subcommands.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Show all available subcommands and flags:
+
+`pueue help`
+
+- Show help for a specific subcommand:
+
+`pueue help {{subcommand}}`

pages/common/pueue-kill.md

@@ -0,0 +1,24 @@
+# pueue kill
+
+> Kill running tasks or whole groups.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Kill all tasks in the default group:
+
+`pueue kill`
+
+- Kill a specific task:
+
+`pueue kill {{task_id}}`
+
+- Kill a task and terminate all its child processes:
+
+`pueue kill --children {{task_id}}`
+
+- Kill all tasks in a group and pause the group:
+
+`pueue kill --group {{group_name}}`
+
+- Kill all tasks across all groups and pause all groups:
+
+`pueue kill --all`

pages/common/pueue-log.md

@@ -0,0 +1,21 @@
+# pueue log
+
+> Display the log output of 1 or more tasks.
+> See also: `pueue status`.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Show the last few lines of output from all tasks:
+
+`pueue log`
+
+- Show the full output of a task:
+
+`pueue log {{task_id}}`
+
+- Show the last few lines of output from several tasks:
+
+`pueue log {{task_id}} {{task_id}}`
+
+- Print a specific number of lines from the tail of output:
+
+`pueue log --lines {{number_of_lines}} {{task_id}}`

pages/common/pueue-parallel.md

@@ -0,0 +1,12 @@
+# pueue parallel
+
+> Set the amount of allowed parallel tasks.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Set the maximum number of tasks allowed to run in parallel, in the default group:
+
+`pueue parallel {{max_number_of_parallel_tasks}}`
+
+- Set the maximum number of tasks allowed to run in parallel, in a specific group:
+
+`pueue parallel --group {{group_name}} {{maximum_number_of_parallel_tasks}}`

pages/common/pueue-pause.md

@@ -0,0 +1,25 @@
+# pueue pause
+
+> Pause running tasks or groups.
+> See also: `pueue start`.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Pause all tasks in the default group:
+
+`pueue pause`
+
+- Pause a running task:
+
+`pueue pause {{task_id}}`
+
+- Pause a running task and stop all its direct children:
+
+`pueue pause --children {{task_id}}`
+
+- Pause all tasks in a group and prevent it from starting new tasks:
+
+`pueue pause --group {{group_name}}`
+
+- Pause all tasks and prevent all groups from starting new tasks:
+
+`pueue pause --all`

pages/common/pueue-remove.md

@@ -0,0 +1,12 @@
+# pueue remove
+
+> Remove tasks from the list. Running or paused tasks need to be killed first.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Remove a killed or finished task:
+
+`pueue remove {{task_id}}`
+
+- Remove multiple tasks at once:
+
+`pueue remove {{task_id}} {{task_id}}`

pages/common/pueue-reset.md

@@ -0,0 +1,16 @@
+# pueue reset
+
+> Kill everything and reset.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Kill all tasks and remove everything (logs, status, groups, task IDs):
+
+`pueue reset`
+
+- Kill all tasks, terminate their children, and reset everything:
+
+`pueue reset --children`
+
+- Reset without asking for confirmation:
+
+`pueue reset --force`

pages/common/pueue-restart.md

@@ -0,0 +1,28 @@
+# pueue restart
+
+> Restart tasks.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Restart a specific task:
+
+`pueue restart {{task_id}}`
+
+- Restart multiple tasks at once, and start them immediately (do not enqueue):
+
+`pueue restart --start-immediately {{task_id}} {{task_id}}`
+
+- Restart a specific task from a different path:
+
+`pueue restart --edit-path {{task_id}}`
+
+- Edit a command before restarting:
+
+`pueue restart --edit {{task_id}}`
+
+- Restart a task in-place (without enqueuing as a separate task):
+
+`pueue restart --in-place {{task_id}}`
+
+- Restart all failed tasks and stash them:
+
+`pueue restart --all-failed --stashed`

pages/common/pueue-send.md

@@ -0,0 +1,12 @@
+# pueue send
+
+> Send input to a task.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Send input to a running command:
+
+`pueue send {{task_id}} "{{input}}"`
+
+- Send confirmation to a task expecting y/N (e.g. apt, cp):
+
+`pueue send {{task_id}} {{y}}`

pages/common/pueue-shutdown.md

@@ -0,0 +1,9 @@
+# pueue shutdown
+
+> Remotely shut down the daemon.
+> Only use this subcommand if the daemon isn't started by a service manager.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Shutdown the daemon without a service manager:
+
+`pueue shutdown`

pages/common/pueue-start.md

@@ -0,0 +1,25 @@
+# pueue start
+
+> Resume operation of specific tasks or groups of tasks.
+> See also: `pueue pause`.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Resume all tasks in the default group:
+
+`pueue start`
+
+- Resume a specific task:
+
+`pueue start {{task_id}}`
+
+- Resume multiple tasks at once:
+
+`pueue start {{task_id}} {{task_id}}`
+
+- Resume all tasks and start their children:
+
+`pueue start --all --children`
+
+- Resume all tasks in a specific group:
+
+`pueue start group {{group_name}}`

pages/common/pueue-stash.md

@@ -0,0 +1,21 @@
+# pueue stash
+
+> Stash tasks to prevent them starting automatically.
+> See also `pueue start` and `pueue enqueue`.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Stash an enqueued task:
+
+`pueue stash {{task_id}}`
+
+- Stash multiple tasks at once:
+
+`pueue stash {{task_id}} {{task_id}}`
+
+- Start a stashed task immediately:
+
+`pueue start {{task_id}}`
+
+- Enqueue a task to be executed when preceding tasks finish:
+
+`pueue enqueue {{task_id}}`

pages/common/pueue-status.md

@@ -0,0 +1,12 @@
+# pueue status
+
+> Display the current status of all tasks.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Show the status of all tasks:
+
+`pueue status`
+
+- Show the status of a specific group:
+
+`pueue status --group {{group_name}}`

pages/common/pueue-switch.md

@@ -0,0 +1,8 @@
+# pueue switch
+
+> Switches the queue position of two enqueued or stashed commands.
+> More information: <https://github.com/Nukesor/pueue>.
+
+- Switch the priority of two tasks:
+
+`pueue switch {{task_id1}} {{task_id2}}`

pages/common/pueue.md

@@ -3,34 +3,14 @@
 > Pueue is a command-line task management tool for sequential and parallel execution of long-running tasks.
 > More information: <https://github.com/Nukesor/pueue>.
 
-- Add a command to the task list:
+- Show general help and available subcommands:
 
-`pueue add -- "{{command}}"`
+`pueue --help`
 
-- List tasks in the task list:
+- Check the version of pueue:
 
-`pueue status`
+`pueue --version`
 
-- Send data to a task's stdin:
+- Execute a pueue subcommand:
 
-`pueue send {{task_id}} {{"hello"}}`
-
-- View a task's stdout and stderr, as well as basic information about that task:
-
-`pueue log {{task_id}}`
-
-- Create a task group:
-
-`pueue group --add {{group_name}}`
-
-- Kill a task:
-
-`pueue kill {{task_id}}`
-
-- Set maximum amount of parallel tasks (queued tasks are started as needed to meet this limit):
-
-`pueue parallel {{number_of_parallel_tasks}}`
-
-- Edit the command line of a stopped task in the default editor (as specified by `$EDITOR`):
-
-`pueue edit {{task_id}}`
+`pueue {{subcommand}}`