crabidy/quality/cli.md

Quality gates: the CLI

Criteria beyond the automatic tests (cbd-cli, crabidy-server, cbd-tui). Each gate is pass/fail by reading the code. See architecture/cli.md. Boxes are checked as the implement stage verifies them; deviations noted inline.

Parsing and defaults

• Every binary (crabidy-server, cbd-tui, cbd) parses with clap-derive; --help, --version, and per-subcommand --help work.
• No subcommand preserves today's behavior: crabidy-server runs the server, cbd-tui runs the TUI, cbd runs the in-process server + TUI. No extra output, no behavior change on the default path.
• The client config still writes a defaults file on first run, and a provided --address/--user/--password/--spectrum overrides the file value; omitted flags fall back to the file. The cbd-tui.toml/cbd.toml schema is unchanged (same keys).

guard (server)

• Prints the argon2id PHC hash to stdout and nothing else on the hash line (pipe-friendly); the password is never logged.
• Without --no-config, writes the hash into the correct [auth] field (owner/queue_owner/queue_appender) of crabidy-server.toml, creating the file if missing and preserving the other roles and the flat shape (deny_unknown_fields still parses the result).
• --no-config only prints (the exact replacement for the old hash-password).
• A missing password argument reads one line from stdin.

scan (server)

• Walks the path (bounded, skips hidden), selects files by audio extension, and writes a <stem>.cbd-track.toml beside each with a Playable::File pointing at the file's own name; an existing toml is left untouched (warned).
• --capture ingests each file into the content store (hash + de-dup + sidecar) and writes a Playable::Store toml instead; re-scanning de-dups.
• --move moves the source into the store instead of copying; the original location keeps only the toml. --capture/--move require a store dir.
• No panic on unreadable files/dirs; each defect is a warning, the walk continues.

auth (client)

• Writes user (role name) and password (cleartext), and address when given, into the client config, preserving other fields; creates the file if missing. The help text says the password is stored in plaintext.

library / queue / global (remote)

• Each subcommand maps to the documented RPC (including a new Stop wrapper); library list prints child nodes and tracks (captured rows marked).
• Connects with basic-auth from --user/--password (config fallback); an empty user talks to an open server with no header.
• A server/RPC error exits non-zero with a readable message; no internal report (color-eyre chain) is dumped for an ordinary "server unreachable" or a gRPC status — those map to a concise message.
• The commands are available on crabidy-server, cbd-tui, and cbd (cbd = union of server + client commands).

Assets

• clap_complete + clap_mangen generate bash/zsh/fish completions and a man page for each binary from its top-level Command in build.rs (OUT_DIR), and into $CBD_ASSET_DIR when set.
• build.rs build-depends on cbd-cli with default features only (no tonic on ordinary builds).
• A completions <shell> subcommand prints a script to stdout.
• A devenv gen-cli-assets script produces dist/completions/** and dist/man/*.1.

Errors and safety

• Library errors are thiserror; CLI reports use color-eyre; no panics on bad input, missing config, or an unreachable server. (Deviation: CLI reports use Box<dyn Error>, matching the existing binaries' convention, not color-eyre — see plan/summary.md.)
• Passwords never appear in logs or error messages; the argv-exposure of a password argument is documented and a stdin path is offered.