AI-native CLI — a spec

A working spec for command-line tools designed for LLM agents alongside humans. The pattern is being articulated independently by several teams; this document doesn't claim to invent it. What it tries to do is name it precisely, list the verifiable invariants, and link the production implementations that already satisfy them. See Prior usage of the term for the wider landscape.

This is a working draft, version 0.2. Feedback, push-back, and alternative phrasings are welcome via Issues.

The underlying idea

LLM agents are a new kind of operator. Anything that has operated a system in the past — humans typing commands, shell scripts, CI pipelines — has used the same primitive: the command-line interface. The Unix philosophy spent fifty years optimizing that primitive: composable, self-describing, deterministic, plain-text, one-tool-one-job.

When agents arrived, the dominant response was to invent a parallel universe: SDKs, MCP servers, custom transports, JSON-RPC schemas delivered out-of-band. That works, but it splits the world in two — a "human surface" (the CLI) and an "agent surface" (the MCP server) — and now you maintain both, document both, debug both, and audit both.

The AI-native CLI claim is simpler: the existing CLI already does most of what an agent needs. The handful of additions are small, local, and don't require a parallel ecosystem:

• A short embedded skill the agent reads up-front — the agent's equivalent of skimming a man-page preface (what is this for, when do I reach for it?).
• Schema introspection so the agent can pull only the actions it needs — the equivalent of man -k plus --help <subcmd>, but machine-readable.
• A uniform structured output so the agent doesn't have to parse free text — the equivalent of git status --porcelain or kubectl -o json, generalized.

Everything else — distribution (Homebrew, Cargo, npm, package managers), discoverability (<bin> --help), debuggability (strace, 2>&1 | jq), reproducibility (the user can re-run the exact command the agent ran) — comes for free. Humans and agents share one surface; debugging an agent run looks like debugging a shell script, because it is a shell command.

What an AI-native CLI looks like

A single self-contained binary that:

1. Ships an embedded skill — a markdown hinge, not a manual. The skill tells the agent the CLI exists, when to reach for it, and which two doors to open (schema, --help). It lists no commands, no flags, no examples, no field formats. Adding a feature does not grow the skill; only the doors behind it grow. Production floor, measured: a YAML description (trigger, ≤ 1024 characters) plus a hinge of ≤ 50 lines. Longer skills exist (session bootstrap, update checks); they are optional, not the minimum.
2. Exposes its surface through built-in schema introspection. Drill-down, not a dump. The exact arity varies with the command tree (two levels, or three when a domain has a sub-family), the shape does not:

   <bin> schema                         # catalog: categories + action_count
   <bin> schema <category>              # actions in that category (name + summary)
   <bin> schema <category> <action>     # leaf: params, examples, errors, effects
   <bin> schema --search <query>        # optional: match across categories
   

   The leaf is what the agent copies. It names parameters and types, defaults, closed enums, runnable examples that cover the variation space, a destructive flag when the world changes, and effects[] — factual side-effects, never prescriptions ("Persists a new row…", not "You should confirm before…").
3. Returns a uniform JSON envelope for every action:

   {"ok": true,  "result": { ... }}
   {"ok": true}
   {"ok": false, "error": {"code": 1, "kind": "user_error", "message": "..."}}

   error.message is part of the agent's self-correction loop: it names the canonical invocation, echoes the offending values, and gives a concrete example the agent can imitate in one pass. "Invalid argument" is not an error message; it is a wasted turn.
4. Honours humans too: meta commands (version, skill show, …) default to plain text; structured output is --format json opt-in. Action commands default to JSON, with --format text opt-in for piping.

The binary also installs its skill into agent harnesses without the agent inventing a path:

<bin> skill show
<bin> skill install --for claude|cursor|cline|codex|gemini|windsurf|copilot|pi

--for is forgiving on input (aliases such as claude-code are absorbed) and canonical on output (help and schema show only the short names).

Three documentation layers

The skill is paid for in every agent turn that loads it. The schema is paid for only when the agent drills. --help is paid for only when the agent peeks. Confusing the three dilutes the context budget.

Layer	Lives in	Purpose	Grows when
Skill	embedded markdown + YAML description	Trigger and hinge. Points at the two doors. Forbids hallucinated flags.	Almost never (invariants only)
Schema	<bin> schema … JSON	Drill-down reference. The leaf is the copy-source.	Every command change
Help	<bin> … --help	Inline syntax reminder. Per-flag formats and units; per-command discussion for non-obvious semantics.	Every flag-behaviour change

Root --help carries one deliberate exception: a short MESSAGE FOR LLM / AI AGENTS that redirects to schema. Empirically, agents told "you may use this CLI" reach for --help first and try to learn the whole tree from it. The root discussion points at the richer, cheaper door. It does not describe the tree. It is not copied onto every subcommand.

Flags, prose, errors

These rules are empirical. They come from LLM-eval on a large surface (macos-cli); they apply to any AI-native CLI, not to that domain.

Bool flags name the effect of passing them, never the state of the entity. Adjectives alone (--completed, --verbose) leave the model to infer a verb, and different models infer different verbs. Prefer a closed enum when two or more states are mutually exclusive and the default is not obvious (--status open|deferred|all). When a single bool is the right shape, one canonical prefix family, no synonyms: --with-X / --without-X (scope), --X / --clear-X (set / unset on update), --enable-X / --disable-X (config).

Agent-facing prose is positive and short. Show the canonical shape with a concrete example (items get abc-789). Naming the antipattern ("never --id") makes 14B-class models emit it more often, not less. effects[] and discussion state what happens to the world, in the vocabulary of the user's app, not the framework's types. Five to ten lines plus a small table beat a wall of text.

Forgiving on input, canonical on output. If trained agents consistently emit a variant with a clean interpretation (the kubectl family reaching for --id instead of a positional), absorb it as a hidden alias. Help, schema, and examples teach only the canonical form. Errors auto-correct in one pass: canonical shape, echoed values, concrete example.

How an agent uses it

1. Agent loads the skill (hinge + description).
   → It now knows when this CLI is the right tool, and that
     `schema` / `--help` are the only doors.

2. The user asks: "open foo.R at line 42"

3. Agent has never used `editor open`, so it discovers:
   $ <bin> schema editor open
   → Leaf ActionSpec: params, examples, effects, destructive.

4. Agent copies the closest example and runs:
   $ <bin> editor open foo.R --line 42
   → {"ok": true, "result": {"id": "1A2B3C4D"}}

5. On a user_error, the message is enough to fix the invocation
   without a second schema round-trip.

The static cost of the integration is the skill hinge — bounded and stable, regardless of how many actions the CLI exposes.

Core principles

• One binary, no SDK. No language runtime to embed in the host. Ships through Homebrew, Cargo, npm, GitHub Releases.
• Uniform structured output. Every action returns {ok, result | error} (or an equivalent envelope). Agents learn the contract once, never per-tool.
• Schema-as-discovery. Drill-down: catalog → category → leaf. The agent never sees the full surface up-front. The leaf is the copy-source (params, examples, effects, destructive).
• Three layers, three price tags. Skill (every turn) is a hinge. Schema (on drill) is the reference. Help (on peek) is syntax.
• Lockstep CLI ↔ skill version. A single version constant drives both; the skill ships inside the binary. The agent can't load a skill that doesn't match the binary it's calling.
• Audience-aware defaults. Action commands default to structured output (agent-first); meta commands default to text (human-first). Either side opts in.
• Discoverable contract. Each schema leaf traces what it does to the world (effects[]) and, when there is an upstream API, the method+path. The contract is inspectable without reading source.
• Canonical on output, forgiving on input. Teach one shape. Absorb the aliases agents already emit. Errors fix in one pass.
• Positive form. Agent-facing prose shows what works. It does not name the antipattern.

Where MCP fits

MCP isn't wrong — it's a different choice. The MCP model front-loads every tool's description into the agent's context. For tools called on nearly every prompt (filesystem, search), that overhead is amortized; the front-load is the right tradeoff.

For tools with large surfaces called occasionally — a Workspace CLI, an IDE bridge, a project-management tool — the front-load cost dominates. Linearis measured it: ~500–700 tokens via schema-on-demand versus ~13k for the Linear MCP. Mornati's "MCP vs CLI" study (Mornati 2026) finds the same shape on a broader sample.

Both can coexist in the same binary. The Google Workspace CLI ships both modes: a native CLI for shell use, and gws mcp exposes the same surface via MCP for agents that prefer that contract. macos-cli does the same with macos mcp serve (bootstrap core always loaded; the rest via tools_search). The AI-native CLI is the minimum shape. MCP is one of several extensions.

Reference implementations

Tools that adopt some or all of this pattern:

• aclemen1/macos-cli — native macOS apps (Reminders, Calendar, Contacts, Notes, …). The three-layer doctrine, flag grammar, positive-form prose, hidden --id aliases, auto-correcting errors, skill install --for, and schema leaves with effects[] / destructive were measured here against LLM-eval. Deepest production statement of this spec.
• aclemen1/rstudio-cli — Rust CLI driving an RStudio Server/Desktop IDE. Embedded skill (rstudio skill install), 3-level schema (rstudio schema [<cat>] [<action>], plus --search), uniform JSON envelope, audience-aware text defaults for meta commands, MCP server with a second vocabulary-specific skill.
• aclemen1/hiverhq-cli — Hiver HQ shared-inbox REST API. Same envelope and 3-level schema; ActionSpec as the single source of truth for CLI and MCP; lockstep embedded skill.
• googleworkspace/cli (a.k.a. gws) — Google Workspace CLI for Drive/Gmail/Calendar/Docs/Sheets/etc. Structured JSON output, 100+ agent skills (SKILL.md) shipped with the binary, dynamic command surface built from the Google Discovery Service at runtime. The largest production-scale instance of the pattern.
• linearis-oss/linearis — Linear.app CLI explicitly "designed for LLM agents and humans who prefer structured data". Implements the exact drill-down: linearis usage (~200 tokens overview) → linearis <domain> usage (~300–500 tokens). JSON-only output.

Prior usage of the term

The term "AI-native CLI" — and its close variant "agent-native CLI" — has appeared in articles and product descriptions before this document. The concept is being articulated independently in several places. A non-exhaustive sample:

As "AI-native CLI":

• MCP vs. CLI for AI-native development (CircleCI).
• CLI is ALL you need (Lucifer1004 on DEV).
• How AI is Revolutionizing CLI (guptadeepak).

As "agent-native CLI":

• Super CLI: The First-ever Agent-Native CLI (Jagtap, Oct 2025) — explicit anteriority claim, applied to AI-agent development tooling.
• CLI-Anything: Making ALL Software Agent-Native (HKUDS) — academic project.
• Why CLI is the New MCP for AI Agents (OneUptime, Feb 2026).

Articles describing the same concept without coining a single term:

• Making your CLI agent-friendly (Speakeasy).
• Writing CLI Tools That AI Agents Actually Want to Use (Uenyioha on DEV).
• Learn To Love the CLI With Agentic LLMs (The New Stack).
• What is a CLI, and why do AI agents like using them? (parallel.ai).

What this document tries to add to the conversation is a crisp, implementation-anchored spec — three concrete mechanisms (embedded skill, schema drill-down, JSON envelope), a handful of invariants, and a list of production CLIs that already satisfy them — rather than the looser "agents like CLIs" thesis those earlier writings develop.

Related reading

• MCP vs CLI: Measuring the Real Token Cost for AI Agents (Mornati, 2026). Empirical measurement of token cost per call across MCP and CLI; the gateway-pattern recommendation is essentially this pattern.
• Structured CLI Output as Pipeline Glue (Kinney). On treating CLI invocation as a pipeline step the agent's structured output flows through.
• The Binary Skill: High-Performance Agentic Orchestration via CLI (Mysore, 2026). Same idea framed as orchestration via local executables.
• Anthropic Skills (Claude Code skills, Cursor skills, etc.). The "skill" half of the pattern is now industry vocabulary; this document is mostly about how a CLI should expose itself given that vocabulary.
• macos-cli documentation layering, naming, prose & input doctrine — the measured source of the 0.2 invariants (flag grammar, positive form, hidden aliases, one-pass errors, three layers).

Status

Draft 0.2. 0.1 named the three mechanisms. 0.2 adds the documentation layers, the flag/prose/error grammar, and skill install --for, shaped by macos-cli LLM-eval. The abstraction may still shift as more tools adopt it.

License

The text of this document is released under CC BY 4.0 — feel free to fork, adapt, and cite.