Add Machine-Readable Output to a CLI
Added 2026-11-06
Output for humans and output for programs should be separate.
I have a CLI: [purpose, current output, users]. Add machine-readable output: 1) design the schema for a `--json` mode — success, failure, partial success; 2) explain how it coexists with human output without breaking existing scripts; 3) define exit codes and error objects so scripts can tell failure types apart; 4) handle pagination, streaming, and very large output; 5) state the stability promise — which fields may change, and how experimental ones are marked; 6) list the tests and docs to add, plus one migration example.
Site original
Chinese original
Replace these placeholders 1
Swap the bracketed parts for your own details before sending.
[purpose, current output, users]
How to use
Define JSON and exit codes first; polish the human output after.
Try tweaking it
- Have it restate requirements and constraints before writing code.
- Ask for the smallest change plus a rollback path, not a full-file rewrite.
What you should get
- A minimal, runnable change with copy-ready code
- Impact list: which files and call sites must follow
Common mistakes
- Asking it to touch ten files at once, then losing track of what broke what.
- Pasting only the error, with no code or version, and getting an unfixable answer.
How to check the output
- The change runs, can be rolled back, and touches nothing unrelated.
- Edge cases (empty, oversized, concurrent) are covered or explained.
Where it works
- Good for: having it restate requirements and constraints, then propose the smallest runnable change.
- Watch out: include versions and a minimal reproduction with the error, or the fix may look plausible but not fit.