strawberry/docs/cli-ux.md
trvon 47c3af735c
Some checks failed
Build and Test / build (debug, clang) (push) Has been cancelled
Build and Test / build (debug, gcc) (push) Has been cancelled
Build and Test / build (release, clang) (push) Has been cancelled
Build and Test / build (release, gcc) (push) Has been cancelled
Build and Test / docker (push) Has been cancelled
CLI: exit code 3 for "could not run here", confirm destructive actions
Decided 2026-10-27 (docs/cli-ux.md):
- Exit codes: 0 done/healthy, 1 negative result (unhealthy, not found,
  daemon refused), 2 usage, 3 could not run here (daemon unreachable,
  permission denied, store not readable, feature not built). Daemon
  unreachable used to exit 2, like a usage error.
- Process kill/suspend, quarantine, allowlist-add, protection-set to
  enforce, store compact and doctor fix (without --dry-run) say what they
  will do and ask "Proceed? [y/N]" on a terminal; Enter or EOF is no.
  Without a terminal they need --yes, else exit 2 with nothing done.
  This applies to the flag form too (--policy-set process-kill ...).
  The desktop app talks to the control socket directly and is unaffected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 09:44:52 -06:00

9.5 KiB

Strawberry CLI UX rules

These rules apply to every strawberry subcommand. They follow the CLI style of ../yams (command table, global --json, quiet defaults, doctor/repair with dry-run) and add the extra rules a security tool needs. The command table and help generator are in src/cli_commands.cpp; output and exit codes are in the run_* functions in src/main.cpp. "Known gaps" at the end lists the places where the code does not meet these rules yet.

Grammar and naming

  • Grammar: strawberry [--config PATH] [--json] <noun> [<verb>] [args] [--flags]. Global flags may come before or after the command.
  • Commands are noun verb (findings list, rules reload, store verify). A single word at the top level is only for host-wide commands (status, doctor, replay, help, version).
  • Reuse the verbs already in use: list, show, search read; set, add, remove, reload, fix change things. Before adding a noun, check whether an existing one fits.
  • One command per intent. If an argument's form tells you what it is, accept both forms in one command instead of adding a twin command (yams AGENTS.md: "Auto-select behavior when safe rather than exposing another switch").
  • Users should not have to type JSON for common actions. policy set <verb> <json> is the general fallback; a policy change people make often gets its own command with typed arguments.
  • The old --flag form is frozen. It keeps working (the systemd units and older scripts call it), but new features never get a new top-level --flag.

Flags

  • Long, kebab-case flags only (--min-age-days N). The only short flag is -h. A flag that takes a value shows it in help as --top N or --inject FILE, and its help text gives the default: (default 20).
  • Global flags: --config PATH, --json, -h/--help. Do not add a per-command copy of a global flag.
  • --dry-run: required on every maintenance, cleanup or bulk-change command. It does all the checks, changes nothing, and reports with "Would ..." wording. With --json it returns the same shape, plus "dry_run": true.
  • --yes: skips the confirmation prompt (see Confirmation).
  • Prefer good defaults to new flags. Add a flag only when the default can't serve both common uses.

Output: human

  • Results go to stdout. Errors, warnings, hints and progress go to stderr. Do not print config-loading chatter on stdout.
  • Layout: a first line that says what was looked at (Store: /var/lib/...), then two-space-indented rows. Key/value rows line up the values. Lists show one item per line, starting with its id.
  • Never print raw JSON in human mode. A command that only has a JSON reply from the daemon still needs a human renderer.
  • Never truncate ids, hashes or node ids. Long free text (titles, cmdlines) can be cut to the terminal width with .... JSON is never cut.
  • Empty results are one plain sentence ("No findings stored"), exit 0.
  • Use ASCII. Don't use emoji or box-drawing characters.

Status vocabulary

  • Checks use the four doctor words: ok, info, warn, problem (CheckStatus in include/strawberry/doctor.hpp). Use them in lowercase in the left column, padded to 8 characters. store verify, rules check and future checks use the same words, not other words like OK/DAMAGED/note.
  • A non-ok row can have a fix: line (strawberry doctor fix <action>) and an advice line, indented under the summary.
  • End a check run with a one-line verdict ("No problems found." / "Some checks need attention.").
  • Detection labels (DETECTED, LATE) are findings, not check statuses, and may be uppercase so they stand out.

Color and terminals

  • Color only when stdout is a TTY, NO_COLOR is unset and TERM is not dumb (the same test as yams ui::colors_enabled()). Never color --json output.
  • Color only highlights a status word or label that is already there. Output must read the same with color off.
  • Progress indicators (spinners, counters) go to stderr, only when stderr is a TTY, never with --json, and only for steps that take more than about a second. Clear the line when done.

Output: JSON (--json)

  • --json puts exactly one JSON document on stdout and nothing else. It is for scripts, the desktop app and agents, so the shape is a contract:
    • keys are snake_case. Changes are additive only: renaming or removing a key, or changing its type, is a breaking change and goes in API_CONTRACT.md with the code change;
    • arrays are always present (empty, not missing). Counts and timestamps are numbers, not strings;
    • strings are valid UTF-8 (error_handler_t::replace).
  • Every command whose output is data (lists, show, search, status, checks, reports) supports --json. Commands that only perform an action can return the daemon's data object.
  • Errors in --json mode: text on stderr, nonzero exit, nothing on stdout.

Security rules for output

  • Evidence is attacker-controlled (paths, cmdlines, rule metadata, finding titles). In human output, control characters (C0, DEL, ESC, C1) and invalid UTF-8 are shown as \xNN, so a crafted process name can't rewrite the terminal. main() does this for every CLI command by filtering stdout and stderr (src/term_safe.hpp); don't bypass it (no writes to fd 1/2 directly). JSON output is already escaped by the serializer.
  • Never print secrets: the GitHub token, policy payloads that may hold credentials, or unredacted command lines. Command lines are stored redacted (include/strawberry/redact.hpp). Don't add a path that prints them before redaction.
  • Telemetry is root-only (0600). A command that needs it fails with an explanation ("telemetry is root-only (command lines can hold secrets): run with sudo, or replay a copy") and does not fall back to partial output.
  • Process actions take only node ids (process_<pid>_<boot>_<start>), never a PID or a path. Validate the id format in the CLI before contacting the daemon. The daemon checks it again against /proc.

Confirmation

  • Destructive actions (process kill/suspend, quarantine, allowlist-add, protection-set to enforce, store compact, doctor fix without --dry-run) say what they will do and ask Proceed? [y/N] when stdin is a TTY. Pressing Enter or EOF means no. (yams's prompt_yes_no treats EOF as its default answer. Do not copy that.)
  • Without a TTY these actions need --yes. If it's missing, exit 2 and do nothing.

Errors and exit codes

Code Meaning Examples
0 Done; for checks: healthy doctor all ok, store verify clean, empty list
1 Ran, but the result is negative unhealthy, damaged store, finding not found, daemon refused the action, rules do not compile
2 Usage error, nothing was done unknown command/flag, bad argument, missing --yes without a TTY
3 Could not run here daemon unreachable, no control_socket_path, permission denied (root-only telemetry, not in group strawberry), feature not built
  • yams uses 0, 1 and 2 (2 for an unknown command). Code 3 is new in Strawberry: scripts and the tray app need to tell "the scanner says there is a problem" (1) from "could not reach the scanner" (3).
  • Message format, on stderr: Error: <what failed> and then, if there is a next step, Hint: <command to run> (yams Hint: lines, yams_cli.cpp). Do not print [Main] or other log tags. On a usage error, print the command's usage line, not the full help.

Help, version, completions

  • Help comes from the command table only. strawberry help <cmd> and strawberry <cmd> --help print the same text. A bare strawberry prints help and never starts the daemon.
  • A summary is a sentence-case phrase that says what the command does, with no trailing period. Mention the important caveat if there is one ("read-only, safe while running", "daemon stopped", "root").
  • strawberry version prints the build's version from meson, not a hard-coded string.
  • Shell completions (strawberry completion bash|zsh|fish, as in yams) are generated from the same table, so a new row shows up in them automatically.

Adding a command

  1. Add a row to the table in src/cli_commands.cpp: words, args, summary, group, flags (kJson if the output is data, --dry-run if it changes state).
  2. Implement or extend the run_* function in src/main.cpp: human renderer, --json shape, exit codes from the table above, evidence escaping.
  3. Add tests in tests/test_cli.cpp: the translation, one error case, and that help lists the command.
  4. Document any new JSON shape in API_CONTRACT.md, and add an example line to README.md.
  5. Process or policy actions: follow the AGENTS.md guardrails (node ids only, fixed control verbs, policy history, no MCP tool).

Known gaps (2026-10-27)

  • Control-socket commands (status, policy show, rules reload, scan file, process kill, ...) print the raw JSON reply in human mode.
  • process trace*, policy show, rules check have no --json.
  • Errors use the [Main] prefix rather than Error: / Hint:.
  • No colors yet. The version string is hard-coded.
  • Done: completions (strawberry completion, installed by install.sh), evidence escaping (term_safe.hpp), bare strawberry prints help, an unknown word is an error with a "did you mean" hint, exit codes 0/1/2/3 (kExit* in main.cpp), confirmation with --yes for process kill/suspend, quarantine, allowlist-add, protection-set enforce, store compact and doctor fix (confirmation_needed() in main.cpp). Exit code 3 and confirmation were confirmed by the maintainer on 2026-10-27.