// Design and review the project's CLI commands so they follow the modular router-plus-libexec pattern with consistent help, validation, and exit codes. Use when adding a new subcommand to `pi-usb-backup`, modifying an existing one, or reviewing command-line UX.
| name | cli-command-style |
| description | Design and review the project's CLI commands so they follow the modular router-plus-libexec pattern with consistent help, validation, and exit codes. Use when adding a new subcommand to `pi-usb-backup`, modifying an existing one, or reviewing command-line UX. |
| argument-hint | Add or review a pi-usb-backup subcommand |
| user-invocable | true |
| disable-model-invocation | false |
Every command exposed by this project (currently pi-usb-backup and its subcommands) follows the same shape, so users always get predictable help text, predictable error behavior, and predictable exit codes. This skill captures that shape so new subcommands stay coherent with the existing ones.
pi-usb-backup.Repo paths mirror deploy paths. The only divergence is the .sh extension on the router, which is stripped at install time so the command can be invoked as a bare name.
| Repo path | Deployed path | Notes |
|---|---|---|
usr/local/sbin/<name>.sh | /usr/local/sbin/<name> | Router / entry point. Installer strips .sh at deploy. |
usr/local/libexec/<name>/<subcmd>.sh | /usr/local/libexec/<name>/<subcmd>.sh | One file per subcommand. Same name in repo and on disk. |
Where <name> is the program name (currently pi-usb-backup).
The router lives at usr/local/sbin/<name>.sh and is intentionally minimal.
#!/bin/bash, set -euo pipefail.PROG (the program name) and LIBEXEC_DIR (the deployed libexec path). No subcommand-specific knowledge.print_help <stream> writes the top-level help text to file descriptor $stream (1 for stdout, 2 for stderr).dispatch "$@" is the only dispatcher:
print_help 1, exit 0.help, -h, --help → print_help 1, exit 0.${LIBEXEC_DIR}/<cmd>.sh does not exist or is not executable) → write "<prog>: unknown command: <cmd>" then print_help 2, exit 1.exec "${LIBEXEC_DIR}/<cmd>.sh" "$@" so the helper inherits stdio and replaces the process; the helper's exit code becomes the router's exit code without an extra wait.require_root. All of that lives in the subcommand helpers.libexec). Adding a new subcommand requires adding exactly one line to the help's Commands: block in the router. This is the only router edit needed when adding a subcommand.Canonical implementation: usr/local/sbin/pi-usb-backup.sh.
Each subcommand lives in its own file at usr/local/libexec/<name>/<subcmd>.sh.
#!/bin/bash, set -euo pipefail.log/die/require_root/have_cmd utilities. Shared helpers are not sourced from a common library today — duplication is tolerated until it actually hurts (see Decision Rules).print_<subcmd>_help <stream> writes the subcommand help to fd $stream.parse_and_dispatch "$@" is the single parse-and-act function:
print_<subcmd>_help 1, exit 0."$@". Recognise only:
--flag=value (with =).status, info).action="" variable. Each recognised token sets it. Setting action a second time is an error.print_<subcmd>_help 2, exit 1:
--flag value).--flag=value where the value is not in the allowed set.require_root (only if the action mutates state), run any tool-presence checks (have_cmd ip, etc.), then dispatch via a small case on $action to the implementation function.--flag=value. The space form (--flag value) is explicitly rejected. Document this in the subcommand help line and in the command's section of docs/manual-installation.md if relevant.action slot as --flag=value. They cannot be combined.Canonical implementation: usr/local/libexec/pi-usb-backup/wifi.sh (--mode=ap, --mode=client, status, duplicate-action rejection, space-form rejection).
<prog> — <one-line description>
Usage:
<prog> <command> [options]
<prog> help
Commands:
<subcmd> <one-line description>
help Show this help message
Run '<prog> <command>' with no further arguments to see per-command help.
Examples:
sudo <prog> <subcmd> --flag=value
<prog> <subcmd> — <one-line description>
Usage:
<prog> <subcmd> --flag=value <description>
<prog> <subcmd> status <description>
This command must be run as root (use sudo).
The closing This command must be run as root (use sudo). line is included only if the subcommand actually requires root.
help, -h, --help) → written to stdout, exit code 0.exec dispatch, no validation, no root check.--mode=ap|client, positional status, single-set action slot, space-form rejection, require_root after parsing.Read both files before adding a new subcommand and follow them as templates.
--flag=value of that subcommand. Do not create a new top-level subcommand for closely-related actions.usr/local/libexec/<name>/_lib.sh and source it from each subcommand. Do not introduce the shared library preemptively — let duplication justify it.--flag=value form is reasonable but inconvenient (e.g. interactive input, multi-word values), prefer a positional subcommand over relaxing the flag syntax. Keep the rule.When adding a new subcommand:
usr/local/libexec/<name>/<subcmd>.sh, mirrored on disk at /usr/local/libexec/<name>/<subcmd>.sh.chmod 0755) and starts with #!/bin/bash + set -euo pipefail.print_<subcmd>_help exists and is called with stdout (fd 1) for no-args / explicit help (exit 0) and stderr (fd 2) for invalid input (exit 1).--flag=value; the space form is rejected.action slot is set exactly once; duplicate sets are rejected with help on stderr.require_root is called only for state-changing actions, and only after parsing succeeds.Commands: block in usr/local/sbin/pi-usb-backup.sh lists the new subcommand (single-line entry)./usr/local/libexec/<name>/<subcmd>.sh (use deploy_script with paths added to the constants section).patch_wifi_country as precedent).