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>
183 lines
9.5 KiB
Markdown
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.
|