utilities/pueue
utilities/pueue
1
0
Fork 0
mirror of https://github.com/nukesor/pueue synced 2024-09-30 04:53:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: pueue -h formatting and update README

Browse source
This commit is contained in:
Arne Beer 2023-05-22 17:39:04 +02:00
parent 375f947aa7
commit 1d507a51b9
No known key found for this signature in database
GPG key ID: CC9408F679023B65
3 changed files with 68 additions and 65 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

111
README.md
View file

@ -128,66 +128,69 @@ There are also detailed sections for (hopefully) every important feature:
On top of that, there is a help option (-h) for all commands.
```text
Pueue client 2.0.0
Arne Beer <contact@arne.beer>
Interact with the Pueue daemon
USAGE:
pueue [OPTIONS] [SUBCOMMAND]
Usage: pueue [OPTIONS] [COMMAND]
OPTIONS:
-c, --config <CONFIG> Path to a specific pueue config file to use. This ignores all other
config files
-h, --help Print help information
-p, --profile <PROFILE> The name of the profile that should be loaded from your config file
-v, --verbose Verbose mode (-v, -vv, -vvv)
-V, --version Print version information
Commands:
add Enqueue a task for execution.
There're many different options when scheduling a task.
Check the individual option help texts for more information.
SUBCOMMANDS:
add Enqueue a task for execution
clean Remove all finished tasks from the list
completions Generates shell completion files. This can be ignored during normal
operations
edit Edit the command or path of a stashed or queued task.
The command is edited by default.
enqueue Enqueue stashed tasks. They'll be handled normally afterwards
follow Follow the output of a currently running task. This command works like tail
-f
format-status Accept a list or map of JSON pueue tasks via stdin and display it just like
"status". A simple example might look like this: pueue status --json | jq
-c '.tasks' | pueue format-status
group Use this to add or remove groups. By default, this will simply display all
known groups
help Print this message or the help of the given subcommand(s)
kill Kill specific running tasks or whole task groups. Kills all tasks of the
default group when no ids are provided
log Display the log output of finished tasks. When looking at multiple logs,
only the last few lines will be shown. If you want to "follow" the output
of a task, please use the "follow" subcommand
parallel Set the amount of allowed parallel tasks. By default, adjusts the amount of
the default group
pause Either pause running tasks or specific groups of tasks.
By default, pauses the default group and all its tasks.
A paused queue (group) won't start any new tasks.
remove Remove tasks from the list. Running or paused tasks need to be killed first
reset Kill all tasks, clean up afterwards and reset EVERYTHING!
restart Restart task(s). Identical tasks will be created and by default enqueued.
By default, a new task will be created
send Send something to a task. Useful for sending confirmations such as 'y\n'
shutdown Remotely shut down the daemon. Should only be used if the daemon isn't
started by a service manager
start Resume operation of specific tasks or groups of tasks.
Furthermore, please remember that scheduled commands are executed via your system shell.
This means that the command needs proper shell escaping.
The safest way to preserve shell escaping is to surround your command with quotes, for example:
pueue add 'ls $HOME && echo "Some string"'
remove Remove tasks from the list. Running or paused tasks need to be killed first
switch Switches the queue position of two commands. Only works on queued and stashed commands
stash Stashed tasks won't be automatically started. You have to enqueue them or start them by hand
enqueue Enqueue stashed tasks. They'll be handled normally afterwards
start Resume operation of specific tasks or groups of tasks.
By default, this resumes the default group and all its tasks.
Can also be used force-start specific tasks.
stash Stashed tasks won't be automatically started. You have to enqueue them or
start them by hand
status Display the current status of all tasks
switch Switches the queue position of two commands. Only works on queued and
stashed commands
wait Wait until tasks are finished. By default, this will wait for all tasks
in the default group to finish. Note:
This will also wait for all tasks that aren't somehow 'Done'. Includes:
[Paused, Stashed, Locked, Queued, ...]
restart Restart failed or successful task(s).
By default, identical tasks will be created and enqueued, but it's possible to restart in-place.
You can also edit a few properties, such as the path and the command, before restarting.
pause Either pause running tasks or specific groups of tasks.
By default, pauses the default group and all its tasks.
A paused queue (group) won't start any new tasks.
kill Kill specific running tasks or whole task groups..
Kills all tasks of the default group when no ids or a specific group are provided.
send Send something to a task. Useful for sending confirmations such as 'y\n'
edit Edit the command, path or label of a stashed or queued task.
By default only the command is edited.
Multiple properties can be added in one go.
group Use this to add or remove groups.
By default, this will simply display all known groups.
status Display the current status of all tasks
format-status Accept a list or map of JSON pueue tasks via stdin and display it just like "pueue status".
A simple example might look like this:
pueue status --json | jq -c '.tasks' | pueue format-status
log Display the log output of finished tasks.
Only the last few lines will be shown by default.
If you want to follow the output of a task, please use the "follow" subcommand.
follow Follow the output of a currently running task. This command works like "tail -f"
wait Wait until tasks are finished.
By default, this will wait for all tasks in the default group to finish.
Note: This will also wait for all tasks that aren't somehow 'Done'.
Includes: [Paused, Stashed, Locked, Queued, ...]
clean Remove all finished tasks from the list
reset Kill all tasks, clean up afterwards and reset EVERYTHING!
shutdown Remotely shut down the daemon. Should only be used if the daemon isn't started by a service manager
parallel Set the amount of allowed parallel tasks
By default, adjusts the amount of the default group.
No tasks will be stopped, if this is lowered.
This limit is only considered when tasks are scheduled.
completions Generates shell completion files. This can be ignored during normal operations
help Print this message or the help of the given subcommand(s)
Options:
-v, --verbose... Verbose mode (-v, -vv, -vvv)
--color <COLOR> Colorize the output; auto enables color output when connected to a tty [default: auto] [possible values: auto, never, always]
-c, --config <CONFIG> Path to a specific pueue config file to use. This ignores all other config files
-p, --profile <PROFILE> The name of the profile that should be loaded from your config file
-h, --help Print help
-V, --version Print version
```
## Design Goals

2
pueue/Cargo.toml
View file

@ -19,7 +19,7 @@ pueue-lib = { version = "0.21.3", path = "../pueue_lib" }
anyhow = "1.0"
chrono-english = "0.1"
clap = { version = "4.1", features = ["derive", "cargo"] }
clap = { version = "4.1", features = ["derive", "cargo", "help"] }
clap_complete = "4.1"
comfy-table = "6.1"
crossterm = { version = "0.25", default-features = false }

20
pueue/src/client/cli.rs
View file

@ -13,7 +13,7 @@ use super::commands::WaitTargetStatus;
#[derive(Parser, Debug)]
pub enum SubCommand {
#[command(
about = "Enqueue a task for execution.\n\n\
about = "Enqueue a task for execution.\n\
There're many different options when scheduling a task.\n\
Check the individual option help texts for more information.\n\n\
Furthermore, please remember that scheduled commands are executed via your system shell.\n\
@ -127,7 +127,7 @@ pub enum SubCommand {
},
#[command(
about = "Resume operation of specific tasks or groups of tasks.\n\n\
about = "Resume operation of specific tasks or groups of tasks.\n\
By default, this resumes the default group and all its tasks.\n\
Can also be used force-start specific tasks.",
verbatim_doc_comment
@ -153,7 +153,7 @@ pub enum SubCommand {
},
#[command(
about = "Restart failed or successful task(s).\n\n\
about = "Restart failed or successful task(s).\n\
By default, identical tasks will be created and enqueued, but it's possible to restart in-place.\n\
You can also edit a few properties, such as the path and the command, before restarting.",
alias("re")
@ -205,7 +205,7 @@ pub enum SubCommand {
edit_label: bool,
},
#[command(about = "Either pause running tasks or specific groups of tasks.\n\n\
#[command(about = "Either pause running tasks or specific groups of tasks.\n\
By default, pauses the default group and all its tasks.\n\
A paused queue (group) won't start any new tasks.")]
Pause {
@ -230,7 +230,7 @@ pub enum SubCommand {
children: bool,
},
#[command(about = "Kill specific running tasks or whole task groups..\n\n\
#[command(about = "Kill specific running tasks or whole task groups..\n\
Kills all tasks of the default group when no ids or a specific group are provided.")]
Kill {
/// Kill these specific tasks.
@ -265,7 +265,7 @@ pub enum SubCommand {
},
#[command(
about = "Edit the command, path or label of a stashed or queued task.\n\n\
about = "Edit the command, path or label of a stashed or queued task.\n\
By default only the command is edited.\n\
Multiple properties can be added in one go."
)]
@ -315,7 +315,7 @@ pub enum SubCommand {
},
#[command(
about = "Accept a list or map of JSON pueue tasks via stdin and display it just like \"pueue status\".\n\n\
about = "Accept a list or map of JSON pueue tasks via stdin and display it just like \"pueue status\".\n\
A simple example might look like this:\n\
pueue status --json | jq -c '.tasks' | pueue format-status",
after_help = "DISCLAIMER:\n\
@ -328,7 +328,7 @@ pub enum SubCommand {
group: Option<String>,
},
#[command(about = "Display the log output of finished tasks.\n\n\
#[command(about = "Display the log output of finished tasks.\n\
Only the last few lines will be shown by default.\n\
If you want to follow the output of a task, please use the \"follow\" subcommand.")]
Log {
@ -366,7 +366,7 @@ pub enum SubCommand {
lines: Option<usize>,
},
#[command(about = "Wait until tasks are finished.\n\n\
#[command(about = "Wait until tasks are finished.\n\
By default, this will wait for all tasks in the default group to finish.\n\
Note: This will also wait for all tasks that aren't somehow 'Done'.\n\
Includes: [Paused, Stashed, Locked, Queued, ...]")]
@ -416,7 +416,7 @@ pub enum SubCommand {
/// Remotely shut down the daemon. Should only be used if the daemon isn't started by a service manager.
Shutdown,
#[command(about = "Set the amount of allowed parallel tasks\n\n\
#[command(about = "Set the amount of allowed parallel tasks\n\
By default, adjusts the amount of the default group.\n\
No tasks will be stopped, if this is lowered.\n\
This limit is only considered when tasks are scheduled.")]