convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
yzfly

AI-First CLI

yzfly/ai-first-cli

Design de CLI otimizado para agentes de IA com 12 princípios verificados

Ver no GitHub
BomPluginScore · de 0 a 100

Filosofia 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-cli

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 · 简体中文

License: CC BY 4.0 PRs Welcome Claude Skill Validate Stars

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

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

#PrincipleIn one line
1Machine output is the default, not a flagStructured envelope on non-TTY; pretty output only for humans at a terminal
2Separate stdout from stderrData → stdout, diagnostics/logs/errors → stderr, so pipes stay clean
3Accept raw payloadsTake JSON isomorphic to the API schema — zero translation loss for an LLM
4Errors must be actionableExit code + stable error code + message + fix command + retryable flag
5Be self-describing & discoverable--help, schema introspection, explain CODE; the CLI is the source of truth for what the API accepts now
6Non-interactive by defaultEvery prompt has a flag bypass; auth via env vars, never a browser flow
7Zero dependencies, self-containedA single signed binary: fast start, trustworthy, no dependency-chain surprises in a sandbox
8Composable (Unix)Pipeable, reads stdin, streams NDJSON for pagination
9Guardrails for autonomy--dry-run, idempotency keys, input hardening, response sanitization against prompt injection
10Token-frugalField selection, pagination, terse output — don't blow the context window
11Determinism over clevernessStable output contracts + versioned schemas; agents prize predictability
12One core, many surfacesCLI / 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

DimensionA well-built CLIA custom MCP server
Integration costZero — the agent just shells outBuild a server per integration
ComposabilityNative Unix pipesWeaker in-protocol composition
Discovery--help built inNeeds schema definitions
Permissions / auditReuses system perms + shell historyBuild your own
When to pick MCPPersistent 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 Agent from a class into an interface; mcp-to-ai-sdk compiles 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 --json exist?
  • 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

DocWhat's inside
docs/principles.mdThe 12 principles in depth, with do/don't
docs/vercel-case-study.mdSource-verified Vercel methodology + bias statement
docs/checklist.mdThe full self-audit checklist
docs/sources.mdAll sources, with confidence & bias notes
skill/ai-first-cliThe 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 ⭐.

Ver o original no GitHub

Bom para

Relacionados