CLI design for AI agents (98 guidelines)

--- name: ai-native-cli description: "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." risk: safe source: https://github.com/ChaosRealmsAI/agent-cli-spec date_added: "2026-03-15" --- # Agent-Friendly CLI Spec v0.1 When building or modifying CLI tools, follow these rules to make them safe and reliable for AI agents to use. ## Overview 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. ## When to Use This Skill - Use when building a new CLI tool that AI agents will invoke - Use when retrofitting an existing CLI to be agent-friendly - Use when designing command-line interfaces for automation pipelines - Use when auditing a CLI tool's compliance with agent-safety standards ## Core Philosophy 1. Agent-first -- default output is JSON; human-friendly is opt-in via --human 2. Agent is untrusted -- validate all input at the same level as a public API 3. Fail-Closed -- when validation logic itself errors, deny by default 4. Verifiable -- every rule is written so it can be automatically checked ## Layer Model This spec uses two orthogonal axes: - Layer answers rollout scope: core, recommended, ecosystem - Priority answers severity: P0, P1, P2 Use layers for migration and certification: - core -- execution contract: JSON, errors, exit codes, stdout/stderr, safety - recommended -- better machine UX: self-description, explicit modes, richer schemas - ecosystem -- agent-native integration: agent/, skills, issue, inline context Certification maps to layers: - Agent-Friendly -- all core rules pass - Agent-Ready -- all core + recommended rules pass - Agent-Native -- all layers pass ## How It Works ### Step 1: Output Mode Default is agent mode (JSON). Explicit flags to switch: ``bash $ 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) ` - **Default (no flag)** -- JSON to stdout. Agent never needs to add a flag. - **--human** -- human-friendly format (colors, tables, progress bars) - **--agent** -- explicit JSON mode (useful when env/config overrides default) ### Step 2: agent/ Directory Convention 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 ` ### Step 3: Four Levels of Self-Description 1. **--brief** (business card, injected into agent config) 2. **Every Command Response** (always-on context: data + rules + skills + issue) 3. **--help** (full self-description: brief + commands + rules + skills + issue) 4. **skills \<name\>** (on-demand deep dive into a specific skill) ## Certification Requirements 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. ### Level 1: Agent-Friendly (core -- 20 rules) 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 version **Error** -- 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 versions **Exit 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 stdout **Composability** -- clean pipe semantics - [P0] C1: stdout is for data ONLY - [P0] C2: logs, progress, warnings go to stderr ONLY **Input** -- fail fast on bad input - [P1] I4: Missing required param -> structured error, never interactive prompt - [P1]` I5: