{"id":51068020,"url":"https://github.com/yzfly/ai-first-cli","last_synced_at":"2026-06-23T08:03:24.163Z","repository":{"id":361445353,"uuid":"1254494072","full_name":"yzfly/ai-first-cli","owner":"yzfly","description":"A design philosophy for command-line tools whose primary user is an AI agent — 12 principles, a source-verified Vercel case study, a self-audit checklist, and an installable Claude skill. 面向 AI Agent 的命令行设计哲学。","archived":false,"fork":false,"pushed_at":"2026-05-30T16:29:54.000Z","size":43,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T18:13:00.396Z","etag":null,"topics":["agent-tools","agentic","ai-agents","ai-first","claude-skill","cli","command-line","developer-experience","llm","mcp","vercel"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yzfly.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T16:28:30.000Z","updated_at":"2026-05-30T16:29:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yzfly/ai-first-cli","commit_stats":null,"previous_names":["yzfly/ai-first-cli"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/yzfly/ai-first-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2Fai-first-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2Fai-first-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2Fai-first-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2Fai-first-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yzfly","download_url":"https://codeload.github.com/yzfly/ai-first-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yzfly%2Fai-first-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34680621,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","agentic","ai-agents","ai-first","claude-skill","cli","command-line","developer-experience","llm","mcp","vercel"],"created_at":"2026-06-23T08:03:20.356Z","updated_at":"2026-06-23T08:03:24.155Z","avatar_url":"https://github.com/yzfly.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# AI-First CLI\n\n### A design philosophy for command-line tools whose primary user is an AI agent — not a human.\n\n**English** · [简体中文](./README.zh-CN.md)\n\n[![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](./LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)\n[![Claude Skill](https://img.shields.io/badge/Claude-Skill-d97757.svg)](./skill/ai-first-cli)\n[![Validate](https://github.com/yzfly/ai-first-cli/actions/workflows/validate.yml/badge.svg)](https://github.com/yzfly/ai-first-cli/actions/workflows/validate.yml)\n[![Stars](https://img.shields.io/github/stars/yzfly/ai-first-cli?style=social)](https://github.com/yzfly/ai-first-cli/stargazers)\n\n*12 principles · a Vercel case study · a copy-paste audit checklist · a ready-to-install Claude skill.*\n\n\u003c/div\u003e\n\n---\n\n\u003e **The CLI's primary reader is shifting from humans to agents.**\n\u003e 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.\n\nThe one-line test:\n\n\u003e **After reading a command's output, an agent should know exactly what to do next — without guessing, hallucinating a command, or stalling.**\n\nThis 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.\n\n## Table of Contents\n\n- [Why this exists](#why-this-exists)\n- [The 12 Principles](#the-12-principles)\n- [One example: prose error vs. actionable error](#one-example-prose-error-vs-actionable-error)\n- [CLI vs. MCP — which to build](#cli-vs-mcp--which-to-build)\n- [Case study: how Vercel pushes this to the limit](#case-study-how-vercel-pushes-this-to-the-limit)\n- [Use it as a Claude skill](#use-it-as-a-claude-skill)\n- [The self-audit checklist](#the-self-audit-checklist)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n- [Citation](#citation)\n- [Author](#author)\n\n## Why this exists\n\nAgentic 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.\n\nThis 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`](./docs/sources.md), including an honest bias statement.\n\n## The 12 Principles\n\n| # | Principle | In one line |\n|---|-----------|-------------|\n| 1 | **Machine output is the default, not a flag** | Structured envelope on non-TTY; pretty output only for humans at a terminal |\n| 2 | **Separate stdout from stderr** | Data → stdout, diagnostics/logs/errors → stderr, so pipes stay clean |\n| 3 | **Accept raw payloads** | Take JSON isomorphic to the API schema — zero translation loss for an LLM |\n| 4 | **Errors must be actionable** | Exit code + stable error code + message + fix command + retryable flag |\n| 5 | **Be self-describing \u0026 discoverable** | `--help`, schema introspection, `explain CODE`; the CLI is the source of truth for what the API accepts *now* |\n| 6 | **Non-interactive by default** | Every prompt has a flag bypass; auth via env vars, never a browser flow |\n| 7 | **Zero dependencies, self-contained** | A single signed binary: fast start, trustworthy, no dependency-chain surprises in a sandbox |\n| 8 | **Composable (Unix)** | Pipeable, reads stdin, streams NDJSON for pagination |\n| 9 | **Guardrails for autonomy** | `--dry-run`, idempotency keys, input hardening, response sanitization against prompt injection |\n| 10 | **Token-frugal** | Field selection, pagination, terse output — don't blow the context window |\n| 11 | **Determinism over cleverness** | Stable output contracts + versioned schemas; agents prize predictability |\n| 12 | **One core, many surfaces** | CLI / MCP / SDK / env var share a single capability core |\n\nFull rationale, do/don't, and edge cases: **[`docs/principles.md`](./docs/principles.md)**.\n\n## One example: prose error vs. actionable error\n\n```diff\n- Error: something went wrong\n- (exit 1)\n```\n\n```json\n{\n  \"ok\": false,\n  \"error\": {\n    \"code\": \"AUTH_004\",\n    \"message\": \"Token expired\",\n    \"fix\": \"run `tool auth login`\",\n    \"retryable\": false\n  }\n}\n```\n\nThe 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.\n\n## CLI vs. MCP — which to build\n\n| Dimension | A well-built CLI | A custom MCP server |\n|-----------|------------------|---------------------|\n| Integration cost | Zero — the agent just shells out | Build a server per integration |\n| Composability | Native Unix pipes | Weaker in-protocol composition |\n| Discovery | `--help` built in | Needs schema definitions |\n| Permissions / audit | Reuses system perms + shell history | Build your own |\n| When to pick MCP | Persistent connections, structured bidirectional streams, rich typed negotiation |\n\n**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.\n\n## Case study: how Vercel pushes this to the limit\n\nVercel 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`](./docs/vercel-case-study.md)**. Highlights:\n\n- **CLI → zero-dependency, self-updating, code-signed native binary.** No Node runtime, fast start, OS-verifiable provenance — exactly Principle 7.\n- **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).\n- **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).\n- **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.\n\n\u003e ⚠️ 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.\n\n## Use it as a Claude skill\n\nThis methodology ships as an installable [Claude Code](https://claude.com/claude-code) skill, so an agent applies the principles automatically when you design or review a CLI.\n\n```bash\n# Install for Claude Code\ngit clone git@github.com:yzfly/ai-first-cli.git\ncp -r ai-first-cli/skill/ai-first-cli ~/.claude/skills/\n```\n\nThe 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`](./skill/ai-first-cli).\n\n## The self-audit checklist\n\nDrop this into any CLI review. Full version with rationale in **[`docs/checklist.md`](./docs/checklist.md)**.\n\n- [ ] Structured output by default on non-TTY? Does `--json` exist?\n- [ ] Data → stdout, logs/errors → stderr?\n- [ ] Non-zero exit on failure, with `code` + `message` + `fix` + `retryable`?\n- [ ] Error codes stable and backed by an `explain`?\n- [ ] Every interactive prompt has a flag bypass? Env-var auth?\n- [ ] Mutating operations offer `--dry-run` / idempotency?\n- [ ] Inputs hardened against path traversal, control chars, injection?\n- [ ] Output contract stable, versioned, token-frugal?\n- [ ] `--help` / schema fully self-describing?\n- [ ] Packaging as close to zero-dependency and trustworthy as possible?\n\n## Documentation\n\n| Doc | What's inside |\n|-----|---------------|\n| [`docs/principles.md`](./docs/principles.md) | The 12 principles in depth, with do/don't |\n| [`docs/vercel-case-study.md`](./docs/vercel-case-study.md) | Source-verified Vercel methodology + bias statement |\n| [`docs/checklist.md`](./docs/checklist.md) | The full self-audit checklist |\n| [`docs/sources.md`](./docs/sources.md) | All sources, with confidence \u0026 bias notes |\n| [`skill/ai-first-cli`](./skill/ai-first-cli) | The installable Claude skill (Chinese, agent-optimized) |\n\n## Contributing\n\nContributions are warmly welcome — a sharper principle, a counter-example, a new case study, a translation. Read **[CONTRIBUTING.md](./CONTRIBUTING.md)** and our **[Code of Conduct](./CODE_OF_CONDUCT.md)** first. Proposing or challenging a principle? Use the *Principle proposal* issue template.\n\n## License\n\n[**Creative Commons Attribution 4.0 International (CC BY 4.0)**](./LICENSE) — use it anywhere, including commercially; just give attribution.\n\n## Citation\n\nIf this work informs your tools or writing, please cite it (see [`CITATION.cff`](./CITATION.cff)):\n\n```\n云中江树 (yzfly). AI-First CLI: A design philosophy for command-line tools whose\nprimary user is an AI agent. 2026. https://github.com/yzfly/ai-first-cli\n```\n\n## Author\n\n**云中江树** · WeChat Official Account: **云中江树** · GitHub: [@yzfly](https://github.com/yzfly)\n\n\u003cdiv align=\"center\"\u003e\n\nIf this clarified how you think about agent-facing tools, consider leaving a ⭐.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyzfly%2Fai-first-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyzfly%2Fai-first-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyzfly%2Fai-first-cli/lists"}