Definition
A CLI is agent-ready when a human can safely let an AI agent install it, run predictable commands, parse the output, and stop before risky state changes.
Why ordinary CLIs fail agents
Many CLIs were designed for humans. They prompt for confirmation, emit colored text instead of structured data, hide state changes, or require broad credentials. Those patterns make agents brittle.
Scoring rubric
| Dimension | What we test | Good signal | Risk signal |
|---|---|---|---|
| Installability | Common package managers and simple setup | Homebrew, npm, pipx, cargo, go install | Manual binary hunting |
| Cross-platform | macOS, Linux, Windows support | documented install paths | single-platform behavior |
| Non-interactive execution | Can common workflows run without prompts? | --yes, --non-interactive, env vars | forced prompts |
| Structured output | Can agents parse output? | --json, --format json, SARIF | colored prose only |
| Auth friendliness | Can credentials be scoped? | read-only tokens, OAuth scopes, CI env vars | broad admin tokens |
| Safety boundaries | Are risky commands clear? | dry-run, read-only, preview | hidden mutations |
| Agent docs | Can rules be copied to AGENTS.md/SKILL.md? | command examples and policy snippets | scattered docs |
| MCP/API mapping | Is there a typed alternative? | MCP, REST API, SDK docs | CLI only with no schema |
| Maintenance and trust | Is the publisher credible? | official repo, recent releases, license | abandoned or unverified |
Safety levels
- Safe: read-only inspection, local parsing, version checks, report generation.
- Review: preview deployments, test-mode events, dependency updates, config edits.
- Dangerous: production deploy, merge, delete, refund, drop table, live payment mutation.
Standard agent instruction template
Use this CLI for read-only inspection first.
Prefer JSON, SARIF, CSV, or markdown output.
Show the exact command before running any state-changing operation.
Ask for approval before deploy, delete, merge, refund, destructive database changes, or production mutation.
Summarize command output with file paths, IDs, URLs, and error codes.Practical rule
A CLI can be powerful and still not be agent-ready if it forces prompts, hides side effects, lacks structured output, or cannot be constrained with safe credentials.