About

Why This Exists

AI agents are operating CLI tools at scale, right now. They deploy infrastructure with Pulumi and OpenTofu. They manage repositories with git and gh. They orchestrate pipelines with kubectl and docker. Every week, agents take on more of the work that humans used to do by hand.

But the tools they use were built for a different user. A user with eyes who can parse colored tables, interpret progress spinners, and read between the lines of an error message. Agents can't do any of that. They burn tokens on decorative output, guess at error meanings, and break on interactive prompts.

Some projects (like RTK) address this with proxy layers that strip noise and restructure output. That works, but it's a band-aid. The real fix is upstream: CLIs should be designed for both audiences from the start.

Agent-First CLI captures 16 principles for doing exactly that. It's a shared contract between CLI tool makers and the agent builders who consume their tools.

What About MCP?

The Model Context Protocol (MCP) provides a structured interface specifically designed for agent-tool communication. If you are building a new tool from scratch and your primary consumer is an AI agent, an MCP server may be the better surface. But CLIs are not going away. Millions of existing tools speak CLI. Agents need to operate them today, not after a rewrite.

Agent-first CLI design and MCP are complementary, not competing. Principles 14 (Capability Negotiation) and 15 (Machine-Readable Help) describe patterns that are effectively lightweight MCP: queryable capabilities, typed flag schemas, structured output contracts. A CLI that follows these principles is one thin adapter layer away from also being an MCP server. Start with the CLI. If agent traffic grows, add an MCP interface that reuses the same structured output and capability metadata you already built.

Contributing

This is an open project. If a principle is wrong, incomplete, or missing, open an issue or submit a PR.

• Propose a new principle: open an issue explaining the pain point, the anti-pattern, and the fix.
• Improve an existing principle: submit a PR against the relevant markdown file in src/content/principles/.
• Report a problem: open an issue describing what's broken or unclear.

All contributions are welcome. The repo is at github.com/agentfirstcli/agentfirstcli.github.io.

Maintainer

Created by @wlami.

License

Content is licensed under CC BY 4.0. Site code is licensed under MIT.