add-cli-command

Add a CLI command

A CLI is an API whose consumers are humans at a terminal and scripts in a pipeline. Scripts depend on the exit code, the stdout format and the flag names; humans depend on the help text and error messages. Follow the tool's existing conventions first and the Command Line Interface Guidelines (clig.dev) where the tool is silent.

Steps

1. Read a sibling command. Find the entry point and command registry (Commander, yargs, Click, Typer, Cobra, clap, picocli, System.CommandLine) and copy an existing command's parsing, validation, output and exit handling. Call search_lore for the CLI's JSON envelope, error format and exit-code table.
2. Design the surface and write --help first. Match the tool's naming (ticket create, not createTicket). Positional arguments only for the one thing the command acts on; everything else is a long flag, with a short alias only where siblings use one. Reuse standard names: -h/--help, --version, --json, -q/--quiet, -f/--force, -n/--dry-run, --no-input, --no-color. Help leads with a usage line and one or two examples. If the help is hard to write, the surface is wrong.
3. Validate before doing any work. Parse and validate every argument, reject unknown flags, and fail with a one-line message naming the bad input and the fix. Exit codes: 0 success, non-zero on any failure, and the tool's usage-error code (commonly 2) for bad arguments. Never exit 0 after printing an error.
4. Separate output streams. stdout carries the result only; errors, warnings, progress and logs go to stderr. --json prints exactly one JSON document (or the tool's documented NDJSON) on stdout and nothing else, including on failure if the envelope defines an error shape. Disable colour and spinners when stdout is not a TTY, when NO_COLOR is set, or with --no-color.
5. Be safe to script. Prompt only when stdin is a TTY and --no-input is absent; otherwise fail with the flag that supplies the answer. Destructive or remote-changing actions confirm interactively or require --force; offer --dry-run when siblings do. Make re-runs safe (idempotent where possible) and give network calls a timeout. On Ctrl-C, stop promptly and exit non-zero (130 by convention).
6. Keep the command thin. Parse, call the same service or core the API uses, render. Business logic in the handler cannot be reused or unit-tested without a process. If the command writes shared files or state that another invocation, the server or a worker may write concurrently, follow the concurrency-and-async skill (atomic temp-and-rename, a real lock).
7. Handle configuration and secrets. Read config through the repo's config spine (the add-config-option skill), never raw env reads, and honour the siblings' --config/--db overrides. Never accept a secret as a flag value (it lands in shell history and ps); read it from a file, stdin or the configured secret source. Never print secrets.
8. Test at both levels. Unit-test the core logic. Spawn the real binary for the contract, one test per AC that exercises the AC's own behaviour, and assert:
   • exit code for success, a usage error and an operational failure;
   • --json stdout parses as JSON with the documented shape, and stderr carries diagnostics without polluting stdout;
   • the error message for bad input; --help lists the new command or flag;
   • non-TTY behaviour: no prompt, no colour; a missing answer fails with a message naming the flag that supplies it.