agentnative.dev The agent-native CLI standard

The agent-native CLI standard

CLI tools are how AI agents touch everything else. Compilers, databases, git, the cloud, the shell. An agent asked to ship code, rotate a credential, grep a log, or deploy a branch does not call a SaaS API — it shells out to a binary, reads the output, decides what went right or wrong, and picks the next move. There is no human between the request and the process. The CLI either makes that loop tractable or it does not.

  1. 01 Non-Interactive by Default Every automation path MUST run without human input. A CLI tool that blocks on an interactive prompt is invisible to an agent — the agent hangs, the user sees nothing, and the operation times out silently.
  2. 02 Structured, Parseable Output CLI tools MUST separate data from diagnostics and offer machine-readable output formats. Mixing status messages with data forces agents into fragile regex extraction that breaks on any format change.
  3. 03 Progressive Help Discovery Help text MUST be layered so agents (and humans) can drill from a short summary to concrete usage examples without reading the entire manual. The critical layer is the one that appears after the flags list, because that is where readers look for invocation patterns.
  4. 04 Fail Fast with Actionable Errors CLI tools MUST detect invalid state early, exit with a structured error, and tell the caller three things: what failed, why, and what to do next. An error that says "operation failed" gives an agent nothing to act on.
  5. 05 Safe Retries and Explicit Mutation Boundaries Every CLI MUST support --dry-run so agents can preview any command before committing it. Write operations MUST clearly separate destructive actions from read-only queries. An agent that cannot distinguish a safe read from a dangerous write will either avoid the tool or execute mutations blindly — both are failure modes.
  6. 06 Composable and Predictable Command Structure CLI tools MUST integrate cleanly with pipes, scripts, and other tools. That means handling SIGPIPE, detecting TTY for color and formatting decisions, supporting stdin for piped input, and maintaining a consistent, predictable subcommand structure.
  7. 07 Bounded, High-Signal Responses CLI tools MUST provide mechanisms to control output volume. Agent context windows are finite and expensive — a tool that dumps 10,000 lines of unfiltered output wastes tokens and may exceed the context limit entirely, breaking the conversation that invoked it.