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

183 lines
9.5 KiB
Markdown

# 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.