Questions people ask

Machine Mode is an open standard for how a command-line tool behaves when an AI agent runs it. A conforming tool writes typed JSON events to stdout, describes itself without credentials, reports errors from a closed list of categories, and ends every run with a summary that says whether it worked. Its formal specification is AOI-CLI.

AOI-CLI is the command-line profile of the Agent-Operable Interface, the formal specification behind Machine Mode. Version 1.0-alpha splits into a small normative core (Part I) that's required for conformance and a recommended profile (Part II) covering safety, bounds and the standard CLI surface.

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.

One JSON object per line on stdout: an aoi:meta event naming the tool and its versions, the results as typed events, and a terminal aoi:summary with ok set to true or false. It also answers a schema command with no credentials or network.

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.

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.

It depends on the sandbox. An AOI-CLI tool is a process, so container-style sandboxes can run it directly, while V8-isolate sandboxes such as Cloudflare Workers can only reach it through a binding that runs the process elsewhere.

Because a single document arrives all at once or not at all. JSON Lines lets an agent act on the first result while the rest are still being computed, keeps long-running commands observable, and lets a consumer detect a cut stream from a missing final line.

Zero for success at the process level and sysexits-style codes (64 to 78) for failures, with 124, 130 and 141 for timeout, interrupt and a closed pipe. Exit codes alone are not enough: AOI requires a terminal aoi:summary with ok set explicitly, because exit 0 with a truncated stream is a common failure.

By reading the last event. Success is exit 0 plus a terminal aoi:summary with ok:true; a stream that ends without a summary is incomplete, whatever the exit code says. The ok field has no default, so a tool can't claim success by omission.

The consumer can tell. Every event carries aoi.seq, a counter that starts at 0 with no gaps, and the summary carries event_count; if seq jumps or the count is short, lines are missing even though the summary survived.

As aoi:error events with a category from a closed list (usage, validation, authn, not_found, rate_limited, unavailable, timeout and others), a stable code, a one-line message and a required retryable flag. Agents branch on retryable to decide whether to retry and on category to decide where to route the error.

Machine mode never prompts. If a command would need a browser login or an MFA prompt, it emits an aoi:error with category authn and code INTERACTIVE_REQUIRED, plus a hint naming the human-mode command to run. A person completes the login once, and later machine-mode calls inherit the credential.

Machine Mode makes it safer, not automatic. Commands default to read-only, mutations support --dry-run with aoi:plan events, destructive operations require --confirm, and writes accept idempotency keys. A script can pass --confirm as easily as a person can, so decisions that need a human still belong in the agent runtime.

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.

Both aim at CLIs agents can call reliably. CLI Agent Spec is broader, with 167 requirements, a single JSON envelope per command and opt-in JSONL streaming; Machine Mode is stream-first, with a small normative core and a measured survey of how existing tools behave.

Kevin Hunt edits the specification, and the work happens in the open on GitHub under the agentoperable organization. Open an issue for a question, a gap in the spec or a tool you want measured.