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
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>
9.5 KiB
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,searchread;set,add,remove,reload,fixchange 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
--flagform 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 Nor--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--jsonit 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(CheckStatusininclude/strawberry/doctor.hpp). Use them in lowercase in the left column, padded to 8 characters.store verify,rules checkand future checks use the same words, not other words likeOK/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_COLORis unset andTERMis notdumb(the same test as yamsui::colors_enabled()). Never color--jsonoutput. - 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)
--jsonputs 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).
- keys are
- Every command whose output is data (lists, show, search, status, checks,
reports) supports
--json. Commands that only perform an action can return the daemon'sdataobject. - Errors in
--jsonmode: 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-settoenforce,store compact,doctor fixwithout--dry-run) say what they will do and askProceed? [y/N]when stdin is a TTY. Pressing Enter or EOF means no. (yams'sprompt_yes_notreats 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>(yamsHint: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>andstrawberry <cmd> --helpprint the same text. A barestrawberryprints 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 versionprints 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
- Add a row to the table in
src/cli_commands.cpp: words, args, summary, group, flags (kJsonif the output is data,--dry-runif it changes state). - Implement or extend the
run_*function insrc/main.cpp: human renderer,--jsonshape, exit codes from the table above, evidence escaping. - Add tests in
tests/test_cli.cpp: the translation, one error case, and that help lists the command. - Document any new JSON shape in API_CONTRACT.md, and add an example line to README.md.
- 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 checkhave no--json.- Errors use the
[Main]prefix rather thanError:/Hint:. - No colors yet. The version string is hard-coded.
- Done: completions (
strawberry completion, installed by install.sh), evidence escaping (term_safe.hpp), barestrawberryprints 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--yesfor 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.