diff --git a/README.md b/README.md index d4a4ab8..64c432a 100644 --- a/README.md +++ b/README.md @@ -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 Interact with the Pueue daemon -USAGE: - pueue [OPTIONS] [SUBCOMMAND] +Usage: pueue [OPTIONS] [COMMAND] -OPTIONS: - -c, --config Path to a specific pueue config file to use. This ignores all other - config files - -h, --help Print help information - -p, --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 Colorize the output; auto enables color output when connected to a tty [default: auto] [possible values: auto, never, always] + -c, --config Path to a specific pueue config file to use. This ignores all other config files + -p, --profile The name of the profile that should be loaded from your config file + -h, --help Print help + -V, --version Print version ``` ## Design Goals diff --git a/pueue/Cargo.toml b/pueue/Cargo.toml index bb9bff4..99970bf 100644 --- a/pueue/Cargo.toml +++ b/pueue/Cargo.toml @@ -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 } diff --git a/pueue/src/client/cli.rs b/pueue/src/client/cli.rs index fdef2ab..370ce32 100644 --- a/pueue/src/client/cli.rs +++ b/pueue/src/client/cli.rs @@ -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, }, - #[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, }, - #[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.")]