AI-First CLI
yzfly/ai-first-cli
Design de CLI otimizado para agentes de IA com 12 princípios verificados
Ver no GitHubFilosofia de design para ferramentas de linha de comando cujo usuário principal é um agente de IA, não humanos. Fornece 12 princípios, estudo de caso da Vercel, checklist de auditoria e skill Claude pronto para instalar, garantindo que CLIs sejam máquina-legíveis, previsíveis e parseáveis.
Instalação
npx convez-ai yzfly/ai-first-cli1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Redesenhar CLIs existentes para serem legíveis por agentes
- Estruturar saída de comandos em JSON isomórfico ao schema da API
- Implementar erros acionáveis com exit codes e error codes estáveis
- Separar stdout (dados) de stderr (diagnósticos) para manter pipes limpos
- Auditar conformidade de ferramentas CLI com padrões agent-first
Veredito

Referência técnica sólida e bem-documentada para construir CLIs agnósticas a agentes. Destaca-se pela abordagem inversora (máquina como usuário principal) e pelo rigor de sourcing das 12 regras; a skill Claude torna prático o uso imediato em workflows agenticos.
README
A tradução para o português deste README ainda está na fila.
AI-First CLI
A design philosophy for command-line tools whose primary user is an AI agent — not a human.
English · 简体中文
12 principles · a Vercel case study · a copy-paste audit checklist · a ready-to-install Claude skill.
The CLI's primary reader is shifting from humans to agents. For thirty years we designed command-line tools for people who read error messages, run
--help, and debug by hand. Agents do none of that well. AI-First CLI is the discipline of treating machine-callable, predictable, parseable as the main path — without losing the human one.
The one-line test:
After reading a command's output, an agent should know exactly what to do next — without guessing, hallucinating a command, or stalling.
This is not "bolt a --json flag onto an old CLI." It is inverting the human assumptions baked into every interface — that the caller reads prose errors, debugs interactively, and reads external docs — and rebuilding for a caller that does none of those things.
Table of Contents
- Why this exists
- The 12 Principles
- One example: prose error vs. actionable error
- CLI vs. MCP — which to build
- Case study: how Vercel pushes this to the limit
- Use it as a Claude skill
- The self-audit checklist
- Documentation
- Contributing
- License
- Citation
- Author
Why this exists
Agentic tools — Claude Code, OpenClaw, coding agents of every shape — invoke CLIs millions of times a day. Vercel CEO Guillermo Rauch calls the CLI the key embedding surface of the "cloud for agents." When the caller is a model, the old design defaults actively hurt: interactive prompts hang headless runs, colorized tables poison pipes, prose errors waste tokens and invite hallucinated fixes.
This project distills — from Vercel's first-party methodology plus independent practitioner sources, cross-checked with adversarial verification — what "agent-first" actually means in practice. Every principle is sourced; see docs/sources.md, including an honest bias statement.
The 12 Principles
| # | Principle | In one line |
|---|---|---|
| 1 | Machine output is the default, not a flag | Structured envelope on non-TTY; pretty output only for humans at a terminal |
| 2 | Separate stdout from stderr | Data → stdout, diagnostics/logs/errors → stderr, so pipes stay clean |
| 3 | Accept raw payloads | Take JSON isomorphic to the API schema — zero translation loss for an LLM |
| 4 | Errors must be actionable | Exit code + stable error code + message + fix command + retryable flag |
| 5 | Be self-describing & discoverable | --help, schema introspection, explain CODE; the CLI is the source of truth for what the API accepts now |
| 6 | Non-interactive by default | Every prompt has a flag bypass; auth via env vars, never a browser flow |
| 7 | Zero dependencies, self-contained | A single signed binary: fast start, trustworthy, no dependency-chain surprises in a sandbox |
| 8 | Composable (Unix) | Pipeable, reads stdin, streams NDJSON for pagination |
| 9 | Guardrails for autonomy | --dry-run, idempotency keys, input hardening, response sanitization against prompt injection |
| 10 | Token-frugal | Field selection, pagination, terse output — don't blow the context window |
| 11 | Determinism over cleverness | Stable output contracts + versioned schemas; agents prize predictability |
| 12 | One core, many surfaces | CLI / MCP / SDK / env var share a single capability core |
Full rationale, do/don't, and edge cases: docs/principles.md.
One example: prose error vs. actionable error
- Error: something went wrong
- (exit 1)
{
"ok": false,
"error": {
"code": "AUTH_004",
"message": "Token expired",
"fix": "run `tool auth login`",
"retryable": false
}
}
The error code is stable so an agent matches on AUTH_004 instead of parsing English, and tool explain AUTH_004 returns a structured explanation — so the agent never has to scrape external docs.
CLI vs. MCP — which to build
| Dimension | A well-built CLI | A custom MCP server |
|---|---|---|
| Integration cost | Zero — the agent just shells out | Build a server per integration |
| Composability | Native Unix pipes | Weaker in-protocol composition |
| Discovery | --help built in | Needs schema definitions |
| Permissions / audit | Reuses system perms + shell history | Build your own |
| When to pick MCP | Persistent connections, structured bidirectional streams, rich typed negotiation |
Rule of thumb: make the CLI agent-first first — it covers most cases. Reserve MCP for genuinely stateful protocols. One core, many surfaces (Principle 12) lets both share the same foundation.
Case study: how Vercel pushes this to the limit
Vercel rebuilds its entire surface around agents, and it's the most complete real-world embodiment of this philosophy — read the full, source-verified write-up in docs/vercel-case-study.md. Highlights:
- CLI → zero-dependency, self-updating, code-signed native binary. No Node runtime, fast start, OS-verifiable provenance — exactly Principle 7.
- Docker inside Vercel Sandbox, on trust-domain microVMs, not shared-kernel containers. The under-appreciated thesis: agent-generated code is untrusted by default, so isolation belongs at the VM level (Principle 9 taken to its conclusion).
- One core, many surfaces: CLI, API, MCP server, and git are all positioned as agent interfaces. Vercel MCP is an OAuth-compliant server; AI SDK 6 redefines
Agentfrom a class into an interface;mcp-to-ai-sdkcompiles dynamic MCP servers into static, versioned tools (Principles 5 + 11 as engineering). - Zero, a Vercel Labs systems language whose compiler emits JSON diagnostics with stable codes and typed repair metadata — the philosophy taken all the way down to the language itself.
⚠️ The case study draws almost entirely on first-party Vercel sources and carries an explicit bias statement; one marketing claim ("clone millions of agents in a single API call") was refuted by adversarial verification and is flagged as such.
Use it as a Claude skill
This methodology ships as an installable Claude Code skill, so an agent applies the principles automatically when you design or review a CLI.
# Install for Claude Code
git clone git@github.com:yzfly/ai-first-cli.git
cp -r ai-first-cli/skill/ai-first-cli ~/.claude/skills/
The skill auto-triggers when you're deciding output formats, error handling, flags, packaging, or autonomous-operation safety for a command-line tool. Source: skill/ai-first-cli.
The self-audit checklist
Drop this into any CLI review. Full version with rationale in docs/checklist.md.
- Structured output by default on non-TTY? Does
--jsonexist? - Data → stdout, logs/errors → stderr?
- Non-zero exit on failure, with
code+message+fix+retryable? - Error codes stable and backed by an
explain? - Every interactive prompt has a flag bypass? Env-var auth?
- Mutating operations offer
--dry-run/ idempotency? - Inputs hardened against path traversal, control chars, injection?
- Output contract stable, versioned, token-frugal?
-
--help/ schema fully self-describing? - Packaging as close to zero-dependency and trustworthy as possible?
Documentation
| Doc | What's inside |
|---|---|
docs/principles.md | The 12 principles in depth, with do/don't |
docs/vercel-case-study.md | Source-verified Vercel methodology + bias statement |
docs/checklist.md | The full self-audit checklist |
docs/sources.md | All sources, with confidence & bias notes |
skill/ai-first-cli | The installable Claude skill (Chinese, agent-optimized) |
Contributing
Contributions are warmly welcome — a sharper principle, a counter-example, a new case study, a translation. Read CONTRIBUTING.md and our Code of Conduct first. Proposing or challenging a principle? Use the Principle proposal issue template.
License
Creative Commons Attribution 4.0 International (CC BY 4.0) — use it anywhere, including commercially; just give attribution.
Citation
If this work informs your tools or writing, please cite it (see CITATION.cff):
云中江树 (yzfly). AI-First CLI: A design philosophy for command-line tools whose
primary user is an AI agent. 2026. https://github.com/yzfly/ai-first-cli
Author
云中江树 · WeChat Official Account: 云中江树 · GitHub: @yzfly
If this clarified how you think about agent-facing tools, consider leaving a ⭐.