CLI Design

Summary

CLI Design covers command-line surfaces that agents can script without scraping terminal prose. Use it when a product exposes capabilities through commands, local automation, package scripts, or developer tools.

• Owns: command structure, JSON output, raw payload input, schema introspection, exit codes, context window discipline, input hardening, safety flags, and packaging CLI knowledge for agents.
• Does not own: model-callable tool schemas in general; see Tool Design. HTTP service contracts; see API Surface.
• Agent-ready means: every command can be discovered, invoked non-interactively, parsed structurally, retried safely, and diagnosed from exit status plus error body.

Start Here

1. Command Structure - Shape commands around stable resources and verbs.
2. Machine-Readable Output - Return parseable JSON, not terminal-only formatting.
3. Raw Payload Input - Accept files or stdin for complex structured input.
4. Schema Introspection - Let agents discover commands and options programmatically.
5. Context Window Discipline - Keep help, logs, and results compact.
6. Input Hardening - Reject malformed arguments with actionable errors.
7. Safety Rails - Support dry runs, confirmations, and non-interactive execution.
8. Agent Knowledge Packaging - Ship command guidance agents can retrieve.
9. CLI Scale - Score a CLI against the seven-axis agent-readiness framework.

Related

1. Error Handling: CLI Errors - Structured failures and stable exit codes.
2. Tool Design - Use when commands become model-callable tools.
3. Context Files - Document canonical commands for coding agents.
4. Testing - Add contract tests for CLI output and failure modes.