# 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] [] [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 ` 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 `) 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___`), 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: ` and then, if there is a next step, `Hint: ` (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 ` and `strawberry --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.