#193 docs: audit and document every CLI exit code

[Anonymous]

Originally created by: fu351
Originally owned by: Maqbool61

What

src/doberman/cli/main.py has 44 typer.Exit(code=...) call sites across its commands, with no single place documenting what each code means. Enumerate every one into a table in docs/CLI.md (issue [#185]), and fix any case where the same code is used for two genuinely different meanings on different commands (callers scripting against exit codes need them to be consistent).

Difficulty: level-5

The audit itself (grep -n "typer.Exit(code=") is mechanical, but deciding whether two same-valued, different-meaning exit codes are an actual bug (vs. two commands legitimately both using 1 for "generic failure") takes judgment, and any code you change is a breaking change for scripts — call it out explicitly in the PR description. Good follow-on from [#185] — this adds a section to the page that issue creates.

Safety constraints (do not weaken these)

• Fail-closed automation: scripts/CI may already branch on a specific exit code to detect a BLOCK/failure. Do not change an exit-code value to "clean up" a collision unless it's a genuine bug — and if you do, the PR description must call it out explicitly as a breaking change, so a script that greps for that code doesn't silently start treating a failure as success (or vice versa).
• Do not touch any non-CLI exit path (the MCP proxy's own fail-closed behavior, hook handlers) while auditing — this issue is scoped to typer.Exit(code=...) call sites in the CLI only.

Starting files

• src/doberman/cli/main.py — grep -n "typer.Exit(code=" for all 44 call sites.
• docs/CLI.md — from issue [#185]; add an "Exit codes" section.

Acceptance criteria

• [ ] docs/CLI.md lists every distinct exit code used across the CLI, which command(s) use it, and what it means.
• [ ] Any exit-code value change is called out explicitly and prominently in the PR description (breaking-change warning), not silently included in the diff.
• [ ] Existing behaviour unchanged unless a genuine collision is fixed (no test weakened, no output format broken)
• [ ] ruff check . && ruff format --check . and lint-imports pass
• [ ] pytest passes

How to validate

grep -n "typer.Exit(code=" src/doberman/cli/main.py
# cross-check the resulting list against the new docs/CLI.md table

Out of scope

• Do not change exit-code behaviour for commands where the same code across commands is legitimately consistent (e.g. 1 = "generic failure" everywhere is fine, not a collision).
• Do not touch non-CLI exit paths (the MCP proxy, hook handlers).

Notes for contributors

New here? Start with CONTRIBUTING.md. Issues are labelled level-1 (docs only) through level-10 (new subsystem) — pick one at your level and climb. Comment to claim an issue before starting.

[Anonymous]

Originally posted by: Maqbool61

Can you assign me to this issue.

[Anonymous]

• assigned_to: Maqbool61

[Anonymous]

Originally posted by: fu351

Assigned. Natural next step after [#396]: that PR pinned down the JSON-output contract, and this one does the same for exit codes in the same docs/CLI.md.

One correction to the body, now fixed: it said 21 typer.Exit(code=...) sites, but main is up to 44. The judgment call is the real work — 1 as generic-failure everywhere is fine, but fixing a genuine collision by changing a code value is a breaking change for anyone scripting against it, so flag that loudly in the PR.

[Anonymous]

Originally posted by: fu351

@Maqbool61 Congrats again on landing [#396]; the shared JSON-output contract closed a real gap, and this exit-code audit is in good hands.

Quick community roll-call: are you in the Doberman Discord? If yes, drop your handle here (or DM me there) so I can match the GitHub side of your work to your Discord name. If not, you're warmly invited: https://discord.gg/Sfy5XGNqty

[Anonymous]

Originally posted by: Maqbool61

@Maqbool61 Congrats again on landing #396; the shared JSON-output contract closed a real gap, and this exit-code audit is in good hands.

Quick community roll-call: are you in the Doberman Discord? If yes, drop your handle here (or DM me there) so I can match the GitHub side of your work to your Discord name. If not, you're warmly invited: https://discord.gg/Sfy5XGNqty

Here is my Discord username: maqbool61 and i have joined discord channel.

[Anonymous]

Ticket changed by: fu351

• status: open --> closed