Repository navigation
Description
Task
| slice | size | difficulty | model | who | estimated lines |
|---|---|---|---|---|---|
| Docs | S | routine | standard | an agent | 120 (0 code, 40 tests, 80 docs) |
docs/reference/cli-min.mdlists everymin/v1/errorcode with its exit code, and a test keeps the list matching the code.
Made a plan task on 2026-11-19 from the docs ask in this issue. In a machine output mode, min writes a min/v1/error object on stderr whose code names the error kind (BCLI-033). Scripts match on that string. docs/reference/cli-min.md has an exit-code table (line 427) but does not list the codes.
What to do:
docs/reference/cli-min.md: add a section on themin/v1/errorobject, next to the exit-code table. Give its fields (schema,code,message,hint), and a table of everycodewith its exit code and when it is given. State that acodeis stable once it is listed here.- Find the codes from the code, not from this issue:
machine_mode_answerincrates/minimal/src/main.rs, and thecode()functions incrates/minimal/src/cli.rs,crates/minimal/src/cmd/box_audit.rs,crates/minimal/src/cmd/boxes/address.rsandcrates/minimal/src/cmd/boxes/wait.rs. Includeunspecified, and say it is the code for a failure with no kind of its own. crates/minimal/src/tests.rs: addcli_reference_lists_every_error_code. It collects every code the CLI can give and fails when the reference's table is missing one, or lists one that the code never gives. Prefer one list in the code thatmachine_mode_answerand the test both read over a second hand-kept list in the test.- Change no code or exit code. A code with no exit code that matches the architecture's exit-code table goes in Notes for the runner, not into a fix.
Covers:
- BCLI-033 (the error object's
code)
Layers:
- client:
- docs/reference/cli-min.md: the
min/v1/errorsection and its code table - crates/minimal/src/tests.rs:
cli_reference_lists_every_error_code - crates/minimal/src/main.rs: only if the test needs one list of the codes to read
cargo nextest run -p minimal cli_reference_lists_every_error_code
- docs/reference/cli-min.md: the
Original issue
Problem
min in a machine output mode (-o json) prints a min/v1/error object whose code names the error kind. Scripts match on that string. docs/reference/cli-min.md does not list the codes, so a script author cannot tell which codes exist or which exit code each stands for.
#3386 adds the box address refusal codes:
| Exit | code |
When |
|---|---|---|
| 2 | usage |
the address matches more than one box, or an id start is ambiguous |
| 4 | not_found |
the address matches no box |
| 7 | host_unreachable |
the box's host does not answer |
usage is new. No other code or document defined a kind for exit 2. The review on #3386 flagged that a later rename would break scripts.
Ask
Document the min/v1/error object in docs/reference/cli-min.md: its fields (code, message, hint), and every code the CLI emits with the exit code it goes with. Include the three above and the ones emitted elsewhere (BoxAddressRefusal::code in crates/minimal/src/cmd/boxes/address.rs, and machine_mode_answer in crates/minimal/src/main.rs). State that a code is stable once documented.
This is a residual of epic #2879 (BCLI).
Plan block
### T65 — The CLI reference lists every min/v1/error code and its exit code
slice: S3
kind: task
covers: BCLI-033
size: S
est: 0 code, 40 tests, 80 docs
executor: agent
difficulty: routine
model: standard
diagnostics: none new
observability: none new
layers:
- client:
- docs/reference/cli-min.md: the `min/v1/error` object, its fields, and every `code` with its exit code and when it is given
- crates/minimal/src/tests.rs: `cli_reference_lists_every_error_code`
- crates/minimal/src/main.rs: one list of the codes, only if the test needs it
test: cargo nextest run -p minimal cli_reference_lists_every_error_code
produces: none
consumes: none
proof: `docs/reference/cli-min.md` lists `usage` (2), `not_found` (4) and `host_unreachable` (7) among the others, and the test fails when a code is added in the code but not in the reference.
Activity
[-]docs: list the min/v1/error codes and their exit codes in cli-min.md[/-][+]T65 — The CLI reference lists every min/v1/error code and its exit code[/+]agent-137 commentedon Nov 19, 2026
/implement
minimal-foundry commentedon Nov 19, 2026
Pull request #3667 is open for T65.
branch
agent/3402-the-cli-reference-lists-every-min-v1-error-code3ab5d81b9de861a673434021cargo nextest run -p minimal cli_reference_lists_every_error_codeVerify
min task run agent-verify: exit 100 — FAIL [ 12.934s] (1251/1251) minimal::otel_cli exec_run_attach_and_task_run_share_the_commands_trace thread 'exec_run_attach_and_task_run_share_the_commands_trace' (11132) panicked at crates/minimal/tests/otel_cli.rs:807:13: exec: no daemon exec span under cmd b727735bc2b29c31: [Updated 2026-11-20T06:36:51.491Z.
agent-137 commentedon Nov 19, 2026
/implement