Machine Mode
Every CLI gets a second interface. This one is for agents.
Machine Mode is an open standard for how a command‑line tool behaves when an AI agent runs it. The tool writes typed JSON events, describes itself without credentials, and reports errors an agent can act on. Code mode has agents write code against tools; Machine Mode makes the tools easy to write code against.
What a tool in machine mode returns
One JSON object per line. A meta event says which tool is talking and which schema applies, the results follow, and a summary at the end says whether the run worked. If the summary never arrives, the run didn't finish.
$ outline search "agent operable" --output jsonl --limit 2{"type":"aoi:meta","aoi":{"seq":0,"run":"01JZQ7X4TQ9"},"tool":"outline","aoi_version":"1.0-alpha","schema_version":"1.0.0"}{"type":"hit","aoi":{"seq":1,"run":"01JZQ7X4TQ9"},"rank":1,"id":"doc_123","title":"Agent-Operable Tools"}{"type":"hit","aoi":{"seq":2,"run":"01JZQ7X4TQ9"},"rank":2,"id":"doc_207","title":"Typed CLI output"}{"type":"aoi:summary","aoi":{"seq":3,"run":"01JZQ7X4TQ9"},"ok":true,"event_count":4,"truncated":false}
Ten factors
What makes a tool easy for an agent to operate. Measure any CLI against them, whether or not you adopt the spec.
Typed
Every event carries a type field and matches a declared schema, so a consumer knows the shape before it reads the data. Code dispatches on event.type instead of running a regex over prose.
Discoverable
A tool describes its schema and capabilities on request, with no credentials, no network and no side effects. An agent plans against the real command surface instead of guessing at flags.
Streamable
Results go out one line at a time as they're produced, so a long operation stays observable and a consumer can act on the first result while the rest are still being computed.
Bounded
Every read takes a limit and returns a cursor when there's more. The response says when it stopped early, so one call can't pour an unbounded result into an agent's context window.
Safe
A read never writes, and a write runs only when the caller asks for it by name. Destructive commands require --confirm, and bulk deletes should take --confirm-count with the exact number, so an agent that guesses wrong gets a refusal instead of an outage.
Idempotent
Writes accept an idempotency key, so replaying a request after a timeout can't apply it twice. When a tool can't tell whether a write landed, it says so and marks the error as not retryable.
Auditable
Every side effect produces a structured record of what was created, changed, deleted or sent, with stable IDs. The audit is part of the output, not something a log scraper rebuilds later.
Verifiable
Success, partial success, truncation, cancellation and crash look different on the wire. A finished run emits aoi:summary with ok set explicitly; a stream that ends without one didn't finish, whatever the exit code says.
Composable
One tool's output is the next tool's input, and failure semantics survive the pipe. Errors and retry detail keep their structure through every stage, and pipefail makes a broken stage visible.
Versioned
Tool version, AOI version and schema version are separate fields, and a breaking change to output bumps the schema major. A consumer can tell whether its parser still applies before it parses anything.
How today's CLIs emit machine output
We probed 16 widely used tools with aoi‑probe and read their documentation, last on . The matrix, method and raw JSON are on the survey page.
Read the survey →Works with code mode, MCP and plain bash
Code mode lets an agent write a script instead of making one tool call per turn. Those scripts read whatever the tool returns, so they do best when the tool returns something typed. A Machine Mode tool publishes its schema offline, which is what a code‑mode runtime needs to generate bindings.
The same tool can sit behind an MCP server through a thin adapter, or be piped through jq in a shell. The interface doesn't change with the caller.
Questions
Do I have to rewrite my CLI?
No. You add a machine mode, usually behind --output jsonl, and leave the human output exactly as it is. The required core is an envelope, a type field, a declared schema version, a terminal summary, a portable error taxonomy and predictable exit codes; a maintainer can implement it in an afternoon.
How does Machine Mode relate to MCP?
They work at different layers and fit together. MCP is how an agent finds and calls a tool; Machine Mode is what a command-line tool returns once it's called. A Machine Mode tool can sit behind an MCP server through a thin adapter that maps its schema to outputSchema and its errors to isError results.
Does Machine Mode work with code mode?
Yes. Code mode has agents write code against tools, and Machine Mode makes a CLI easy to write code against: a code-mode runtime can generate typed bindings from the tool's offline schema, and generated code can check aoi:summary and branch on structured errors.
Does any tool conform today?
Not end to end. aoi-probe, the measurement tool, conforms; aoi-lint, aoi-coreutils and a TypeScript SDK are in development. The tools registry lists each project with its honest status.