Design spec with 98 rules for building CLI tools that AI agents can safely use. Covers structured JSON output, error handling, input contracts, safety guardrails, exit codes, and agent self-description.
When building or modifying CLI tools, follow these rules to make them safe and reliable for AI agents to use.
A comprehensive design specification for building AI-native CLI tools. It defines 98 rules across three certification levels (Agent-Friendly, Agent-Ready, Agent-Native) with prioritized requirements (P0/P1/P2). The spec covers structured JSON output, error handling, input contracts, safety guardrails, exit codes, self-description, and a feedback loop via a built-in issue system.
--humanThis spec uses two orthogonal axes:
core, recommended, ecosystemP0, P1, P2Use layers for migration and certification:
agent/, skills, issue, inline contextCertification maps to layers:
core rules passcore + recommended rules passDefault is agent mode (JSON). Explicit flags to switch:
$ mycli list # default = JSON output (agent mode)
$ mycli list --human # human-friendly: colored, tables, formatted
$ mycli list --agent # explicit agent mode (override config if needed)
Every CLI tool MUST have an agent/ directory at its project root. This is the
tool's identity and behavior contract for AI agents.
agent/
brief.md # One paragraph: who am I, what can I do
rules/ # Behavior constraints (auto-registered)
trigger.md # When should an agent use this tool
workflow.md # Step-by-step usage flow
writeback.md # How to write feedback back
skills/ # Extended capabilities (auto-registered)
getting-started.md
Each level includes all rules from the previous level.
Priority tag [P0]=agent breaks without it, [P1]=agent works but poorly, [P2]=nice to have.
Goal: CLI is a stable, callable API. Agent can invoke, parse, and handle errors.
Output -- default is JSON, stable schema
[P0] O1: Default output is JSON. No --json flag needed[P0] O2: JSON MUST pass jq . validation[P0] O3: JSON schema MUST NOT change within same versionError -- structured, to stderr, never interactive
[P0] E1: Errors -> {"error":true, "code":"...", "message":"...", "suggestion":"..."} to stderr[P0] E4: Error has machine-readable code (e.g. MISSING_REQUIRED)[P0] E5: Error has human-readable message[P0] E7: On error, NEVER enter interactive mode -- exit immediately[P0] E8: Error codes are API contracts -- MUST NOT rename across versionsExit Code -- predictable failure signals
[P0] X3: Parameter/usage errors MUST exit 2[P0] X9: Failures MUST exit non-zero -- never exit 0 then report error in stdoutComposability -- clean pipe semantics
[P0] C1: stdout is for data ONLY[P0] C2: logs, progress, warnings go to stderr ONLYInput -- fail fast on bad input
[P1] I4: Missing required param -> structured error, never interactive prompt[P1] I5: Type mismatch -> exit 2 + structured errorSafety -- protect against agent mistakes
[P1] S1: Destructive ops require --yes confirmation[P1] S4: Reject ../../ path traversal, control charsGuardrails -- runtime input protection
[P1] G1: Unknown flags rejected with exit 2[P1] G2: Detect API key / token patterns in args, reject execution[P1] G3: Reject sensitive file paths (*.env, *.key, *.pem)[P1] G8: Reject shell metacharacters in arguments (; | && $())Goal: CLI is self-describing, well-named, and pipe-friendly. Agent discovers capabilities and chains commands without trial and error.
Self-Description -- agent discovers what CLI can do
[P1] D1: --help outputs structured JSON with commands[][P1] D3: Schema has required fields (help, commands)[P1] D4: All parameters have type declarations[P1] D7: Parameters annotated as required/optional[P1] D9: Every command has a description[P1] D11: --help outputs JSON with help, rules, skills, commands[P1] D15: --brief outputs agent/brief.md content[P1] D16: Default JSON (agent mode), --human for human-friendly[P2] D2/D5/D6/D8/D10: per-command help, enums, defaults, output schema, versionInput -- unambiguous calling convention
[P1] I1: All flags use --long-name format[P1] I2: No positional argument ambiguity[P2] I3/I6/I7: --json-input, boolean --no-X, array paramsError
[P1] E6: Error includes suggestion field[P2] E2/E3: errors to stderr, error JSON validSafety
[P1] S8: --sanitize flag for external input[P2] S2/S3/S5/S6/S7: default deny, --dry-run, no auto-update, destructive markingExit Code
[P1] X1: 0 = success[P2] X2/X4-X8: 1=general, 10=auth, 11=permission, 20=not-found, 30=conflictComposability
[P1] C6: No interactive prompts in pipe mode[P2] C3/C4/C5/C7: pipe-friendly, --quiet, pipe chain, idempotencyNaming -- predictable flag conventions
[P1] N4: Reserved flags (--agent, --human, --brief, --help, --version, --yes, --dry-run, --quiet, --fields)[P2] N1/N2/N3/N5/N6: consistent naming, kebab-case, max 3 levels, --version semverGuardrails
[P1] I8/I9: no implicit state, non-interactive auth[P1] G6/G9: precondition checks, fail-closed[P2] G4/G5/G7: permission levels, PII redaction, batch limits| Flag | Semantics | Notes |
|---|---|---|
--agent | JSON output (default) | Explicit override |
--human | Human-friendly output | Colors, tables, formatted |
--brief | One-paragraph identity | For sync into agent config |
--help | Full self-description JSON | Brief + commands + rules + skills + issue |
--version | Semver version string | |
--yes | Confirm destructive ops | Required for delete/destroy |
--dry-run | Preview without executing | |
--quiet | Suppress stderr output | |
--fields | Filter output fields | Save tokens |
Goal: CLI has identity, behavior contract, skill system, and feedback loop. Agent can learn the tool, extend its use, and report problems -- full closed-loop collaboration.
Agent Directory -- tool identity and behavior contract
[P1] D12: agent/brief.md exists[P1] D13: agent/rules/ has trigger.md, workflow.md, writeback.md[P1] D17: agent/rules/*.md have YAML frontmatter (name, description)[P1] D18: agent/skills/*.md have YAML frontmatter (name, description)[P2] D14: agent/skills/ directory + skills subcommandResponse Structure -- inline context on every call
[P1] R1: Every response includes rules[] (full content from agent/rules/)[P1] R2: Every response includes skills[] (name + description + command)[P1] R3: Every response includes issue (feedback guide)Meta -- project-level integration
[P2] M1: AGENTS.md at project root[P2] M2: Optional MCP tool schema export[P2] M3: CHANGELOG.md marks breaking changesFeedback -- built-in issue system
[P2] F1: issue subcommand (create/list/show)[P2] F2: Structured submission with version/context/exit_code[P2] F3: Categories: bug / requirement / suggestion / bad-output[P2] F4: Issues stored locally, no external service dependency[P2] F5: issue list / issue show <id> queryable[P2] F6: Issues have status tracking (open/in-progress/resolved/closed)[P2] F7: Issue JSON has all required fields (id, type, status, message, created_at, updated_at)[P2] F8: All issues have status field$ mycli list
{"result": [{"id": 1, "title": "Buy milk", "status": "todo"}], "rules": [...], "skills": [...], "issue": "..."}
{
"error": true,
"code": "AUTH_EXPIRED",
"message": "Access token expired 2 hours ago",
"suggestion": "Run 'mycli auth refresh' to get a new token"
}
0 success 10 auth failed 20 resource not found
1 general error 11 permission denied 30 conflict/precondition
2 param/usage error
Implement by layer -- each phase gets you the next certification level.
Phase 1: Agent-Friendly (core)
--json flag needed{ error, code, message, suggestion } to stderr--yes guard on destructive operationsPhase 2: Agent-Ready (+ recommended)
8. --help returns structured JSON (help, commands[], rules[], skills[])
9. --brief reads and outputs agent/brief.md content
10. --human flag switches to human-friendly format
11. Reserved flags: --agent, --version, --dry-run, --quiet, --fields
12. Exit codes: 20 not found, 30 conflict, 10 auth, 11 permission
Phase 3: Agent-Native (+ ecosystem)
13. Create agent/ directory: brief.md, rules/trigger.md, rules/workflow.md, rules/writeback.md
14. Every command response appends: rules[] + skills[] + issue
15. skills subcommand: list all / show one with full content
16. issue subcommand for feedback (create/list/show/close/transition)
17. AGENTS.md at project root
suggestion field in every error responseagent/brief.md to one paragraph for token efficiencyProblem: CLI outputs human-readable text by default, breaking agent parsing
Solution: Make JSON the default output format; add --human flag for human-friendly mode
Problem: Errors reported in stdout with exit code 0 Solution: Always exit non-zero on failure and write structured error JSON to stderr
Problem: CLI prompts for missing input interactively Solution: Return structured error with suggestion field and exit immediately
@cli-best-practices - General CLI design patterns (this skill focuses specifically on AI agent compatibility)