Compare
Several efforts want command-line tools that agents can rely on. Here's how they line up.
Machine Mode and CLI Agent Spec are both specifications for CLIs that AI agents call; clig.dev and 12 Factor CLI Apps are design guidelines written for people at a terminal. The two agent specs agree on more than they differ, and where they differ it's mostly about shape: one JSON envelope per command, or a stream of events.
Everything about other projects below comes from their own published pages, read on 2026-10-23. If something here is out of date, open an issue and it gets fixed.
Side by side
| Machine Mode (AOI-CLI 1.0-alpha) | CLI Agent Spec v1.16 | clig.dev | 12 Factor CLI Apps | |
|---|---|---|---|---|
| Written for | AI agents and automation calling a CLI | AI agents calling a CLI | People at a terminal, with script-friendly options | People at a terminal |
| Output shape | A JSONL event stream: aoi:meta first, typed events, aoi:summary last | One JSON envelope per command: ok, data, error, warnings, meta | Recommends --json, plus --plain for line tools | See the essay |
| Streaming | Every run is a stream; unbounded streams are defined | Opt-in --format jsonl / --stream (REQ-O-004), plus progress and heartbeats | Not specified | See the essay |
| Errors | Closed category list, stable code, required retryable, retry_after_ms | code and message, retryable, retry_after_ms (REQ-C-014), an executable fix_command (REQ-C-030) | Human-readable error guidance | See the essay |
| Exit codes | sysexits-compatible (64 to 78), plus 124, 130 and 141 | 15 named codes, 0 to 14, each with retryable and side_effects | Zero on success, non-zero mapped to the main failure modes | See the essay |
| Discovery | schema and capabilities commands that must work offline, without credentials | Declared input and output schemas, --schema, a tool manifest command | Help text and docs | Help text |
| Success signal | aoi:summary.ok with no default; no summary means the run is incomplete | ok in the envelope, and meta.exit_code | Exit status | Exit status |
| Conformance | aoi-lint, per factor (in development); aoi-probe measures any CLI today | A deterministic conformance kit with levels | None; guidelines | None; guidelines |
| Size | A small required core (Part I) plus a recommended profile (Part II) | 167 requirements: 81 framework-automatic, 36 command contract, 50 opt-in | One long guide | Twelve principles |
| Published evidence | A measured survey of 16 widely used CLIs | 76 documented failure modes | Not applicable | Not applicable |
| Maintained by | Kevin Hunt, github.com/agentoperable | github.com/cli-agent-spec (no individual named on the site) | Aanand Prasad, Ben Firshman, Carl Tashian, Eva Parish | Jeff Dickey (2018, from the Heroku CLI and oclif work) |
Envelope or stream
CLI Agent Spec wraps each command's result in a single JSON object, which is easy to parse and easy to check: read ok, then data. Streaming is available as an opt‑in mode. Machine Mode makes every run a stream, so long operations stay observable, a consumer can act on the first result early, and a cut stream shows up as a missing final summary or a gap in seq.
Both arrived at the same answers on retries. Each carries a retryable flag and a retry_after_ms delay, and each tells the agent when a side effect may already have happened: CLI Agent Spec through side_effects on its exit codes, Machine Mode by requiring retryable:falsewhenever the tool can't tell.
Field mapping: CLI Agent Spec to AOI-CLI
| CLI Agent Spec | AOI-CLI | Notes |
|---|---|---|
ok | aoi:summary.ok | Both explicit booleans. |
data | Domain events | One event per record, each with its own type. |
error.code | aoi:error.code + category | AOI adds a category from a closed list for routing. |
retryable | retryable | Same meaning; required on every AOI error. |
retry_after_ms | retry_after_ms | Same field name and unit. |
warnings | aoi:warning events | Emitted in the stream where they occur. |
meta.exit_code | Process exit status | AOI keeps the exit code on the process, not in the payload. |
| Schema and tool versions in meta | aoi:meta and aoi:summary | AOI carries tool, AOI and schema versions at both ends of the stream. |
| Request and trace IDs in meta | aoi.run and aoi.trace_id | On every event, so a line stays attributable after a grep. |
Which to follow
clig.dev and 12 Factor CLI Apps are about the human interface, and nothing in either agent spec conflicts with them: follow them for the default output and pick an agent spec for the machine mode. If your tool already emits one JSON document per command, CLI Agent Spec asks for less change. If your commands run long, stream results, or feed pipelines, Machine Mode fits the shape you already have.
Sources
- CLI Agent Spec v1.16, cli-agent-spec.github.io, read 2026-10-23.
- Command Line Interface Guidelines, clig.dev, read 2026-10-23.
- Jeff Dickey, “12 Factor CLI Apps,” 2018.
- AOI‑CLI v1.0-alpha, machinemode.io/spec.