What makes a CLI agent-friendly?
We do not treat “agent-friendly” as a vague badge. We define it with a small set of principles, a command design checklist, and a scorecard that shows how current registry tools stack up in practice.
1. Principles
These principles define what we mean by agent-friendly before we get into specific flags or implementation details.
Automatable
The main workflow should run without prompts, pagers, or human-only handoffs. Agents need a CLI they can execute end-to-end on their own.
Understandable
The command surface, parameters, and outputs should be easy to discover. Agents should be able to learn how to use the CLI from the CLI itself through noun-verb hierarchy, self-describing flags, and clear help.
Recoverable
Failures should be diagnosable and actionable. Agents need to tell what went wrong and what to try next instead of stopping at a vague error.
Controllable
Mutating operations should be explicit and safe. Agents need preview and confirmation patterns that reduce blind writes, accidental changes, and unsafe retries.
2. Command Design Checklist
An agent-friendly CLI should expose a standard command surface built around noun-verb hierarchy and self-describing long flags. These are the required checkpoints we expect from command design.
| Command | Why it matters |
|---|---|
--help | Human-readable command discovery at the root and subcommand level, with examples first and clear required, optional, default, and allowed values. |
--version | A stable version surface so agents can verify the runtime baseline. |
--json | Machine-readable output on stdout for parsing and downstream automation. |
--yes | A standard non-interactive confirmation path for commands that would otherwise prompt. |
--dry-run | A preview mode that shows intended side effects without executing them. |
schema | Machine-readable command and parameter introspection for agents, including forms like `cli schema --all` and `cli schema <command path>`. |
Behavior expectations
- Keep stdout and stderr separate so structured output stays parseable.
- Do not default into interactive shells, pagers, or setup wizards.
- Detect TTY vs non-TTY and disable color, spinner, pager, and prompts in automation.
- Prefer noun-verb command hierarchy and long self-describing flags over ambiguous short forms.
- Validate inputs strictly and prefer enums over free-form strings where possible.
- Design mutating commands to be idempotent or retry-safe.
- Use semantic exit codes so agents can distinguish classes of failure.
- Return errors that tell the agent what happened and how to recover.
3. Current Scorecard
These are machine verification results for the command checklist above. Each row is tied to a manifest entry and reflects the latest saved CI verification result we have committed to the repo.
| CLI | --help | --version | --json | --yes | --dry-run | schema | Verified At |
|---|---|---|---|---|---|---|---|
| Firebase CLI firebase | 2026-04-04 | ||||||
| Lark / Feishu CLI lark-cli | 2026-04-04 | ||||||
| Cloudflare Wrangler wrangler | 2026-04-04 | ||||||
| Docker CLI docker | 2026-04-04 | ||||||
| Netlify CLI netlify | 2026-04-04 | ||||||
| Supabase CLI supabase | 2026-04-04 | ||||||
| Fly.io CLI fly | 2026-04-04 | ||||||
| Railway CLI railway | 2026-04-04 | ||||||
| Stripe CLI stripe | 2026-04-04 | ||||||
| Turso CLI turso | 2026-04-04 | ||||||
| Vercel CLI vercel | 2026-04-04 | ||||||
| kubectl kubectl | 2026-04-04 | ||||||
| AWS CLI aws | 2026-04-04 | ||||||
| GitHub CLI gh | 2026-04-04 | ||||||
| Google Workspace CLI gws | 2026-04-04 | ||||||
| Terraform CLI terraform | 2026-04-04 |