About this standard

The agent-native CLI standard is a specification for command-line tools that behave predictably under agent control. Eight principles, enforced by RFC 2119 requirement tiers (MUST / SHOULD / MAY), and measured by a companion linter (anc) that scores any CLI against them.

Provenance

This spec is authored and maintained in the open by Brett Davies, with contributions accepted via the channels below. It is a proposal pressure-tested in public, not a ratified industry standard. The goal is to converge on something worth ratifying, by writing it down concretely first and inviting people to break it.

Prior art

The eight-principle structure draws on two distinct lineages.

Standards and methodologies that shaped the format:

• Command Line Interface Guidelines (clig.dev): the closest direct prior art for CLI design guidance; the Unix-philosophy distillation this spec departs from when agents change the human-only assumptions.
• The Twelve-Factor App (12factor.net): the numbered-principle layout, environment-first configuration, and the discipline of writing each factor down concretely.
• IETF RFC 2119: the MUST / SHOULD / MAY contract that turns prose into a conformance bar.

Writing that informed the principles directly:

• Cloudflare's Building a CLI for all of Cloudflare (2026-04-13) and the HN discussion that followed: the most concrete public statement of "agents are the primary customer" of CLI tools, paired with crowdsourced failure modes from people who run agents against CLIs every day. Quotes from that thread shaped the framing of P3 (progressive help), P4 (actionable errors), and P6 (composable structure) directly. P2 and P6 mirror the Cloudflare team's own rules (get not info, --json always, --force not --skip-confirmations).

If a specific principle's framing seems to echo prior writing, it probably does. Credit accrues to the people whose public reasoning informed it; mistakes are mine.

Versioning

The spec uses semver-adjacent versioning with three tiers: MAJOR changes break citation IDs or remove MUSTs; MINOR changes add MUSTs or promote SHOULDs; PATCH changes edit prose without shifting requirements. The current version appears in the footer of every page.

Principle anchor slugs (#p1-non-interactive-by-default through #p8-discoverable-skill-bundle) are permanent. If a principle merges or splits in a future MAJOR version, the old slug will resolve as a permanent redirect to wherever the requirement now lives; citations made today will not 404 after a future restructuring.

RFC 2119

MUST, SHOULD, MAY, MUST NOT, and SHOULD NOT on this site carry their RFC 2119 meanings. They are not emphatic; they are contractual. A tool that does not satisfy a MUST is non-conformant with the version of the standard it claims to target.

License

Spec text on this site is available under CC BY 4.0. The anc linter is dual-licensed under MIT and Apache-2.0; see its LICENSE files.

Contributing

Pressure-testing is how the spec evolves. Three ways to contribute:

1. Submit a grading finding: score a real CLI against a principle you think the spec gets wrong, and report what you found. Name the CLI, the principle, and the specific MUST/SHOULD/MAY that failed (or passed unexpectedly).

Report a false positive or false negative: in the anc auditor. Include the command, the output, and the audit ID. 3. Propose a principle edit: merge, split, rewording, demotion of a MUST to a SHOULD. Describe the problem before proposing a solution. 4. Add a tool to the registry: propose a CLI for inclusion on the anc.dev/scorecards leaderboard. Include the install command, the source repo, and (optionally) the result of a fresh anc audit run.

For full routing guidance, see the spec repo's CONTRIBUTING.md.

Colophon

Built with Cloudflare Workers. Typeset in Uncut Sans and Monaspace Xenon. Source: github.com/brettdavies/agentnative-site.