CLI Reference

The binary is invoked as runtime. Every command passes through the same execution lifecycle.

Your runtime carries its own contract

This site gets you installed, gets your first capabilities running, and explains how the pieces fit. Any Runtime command prepares the Home automatically; runtime bootstrap is the optional explicit report. Start at <Runtime Home>/RUNTIME-AGENT.md (the contract) and manifest.json (this binary's providers and operations). Specs and command cheatsheets for your installed version live in <Runtime Home>/specs/ and commands/. Read those for precise operational detail — they describe the binary you actually have. Come back here for concepts, upgrades, and anything not yet installed.

Documentation is a product contract

Engineering Runtime documentation is an executable product contract for humans and agents: it exposes goals, inputs, commands, expected results and recovery. External tools and CI remain authoritative for effective context; provider platforms remain authoritative for credentials. Runtime resolves one safe context snapshot, applies policy, executes through the provider, and records that same snapshot in audit. Prose or model output cannot override those controls. File Engine, exact-executable and bounded-output limits are explicit; they are not a full host sandbox or universal DLP.

Command tree

runtime
├── version                      print the binary version
├── bootstrap                    prepare / inspect the Runtime Home
├── config validate              one read-only health report
├── config diff policy           allowed_binaries vs this release's compiled default
├── context show|retire          observe native tool context; retire a leftover file
├── auth status|login|logout     validate platform credentials
├── audit tail|status|verify     read records and durable evidence integrity
├── audit recover               explicitly classify quiescent orphan intents unknown
├── resolve <command-line...>    check a command line resolves — zero side effects
├── capability list|authoring-context|validate|plan|execute
│                                      discover, author, preflight, or run a workflow
├── command run <binary> ...     the Command Engine escape hatch
├── portal status|sync           optional control plane — off by default
│
├── github <operation> ...       ┐ provider commands, generated from the
└── files  <operation> ...       ┘ provider registry

Provider commands are generated from the registry — the runtime gains a provider's whole CLI surface without a hand-written command for it.

Page	Covers
Core Commands	version, bootstrap, config validate, config diff policy, context, audit tail/status/verify/recover, resolve
auth	status, login, logout
capability	list, authoring-context, validate, plan, execute
command run	The Command Engine
portal	status, sync — the optional control-plane client
github	The GitHub provider's operations
files	The files provider's operations

Global flags

--output text|json|raw

Global, and available on every command.

runtime github repo list
runtime --output json github repo list

JSON output includes the provider, operation, transport, safe identity projection and result — the machine-readable surface for CI and AI consumers. Structured payload appears once at .data. Identity contains provider, auth_mode and subject_resolved; it never contains the raw subject or token. Text is the default and is meant for humans. A structured list operation can declare its own columns; github repo list, for example, renders a repository table and count instead of dumping the REST response. Its JSON form still exposes the complete objects.

Human identity metadata is deliberately minimal: provider, authentication mode and whether a subject resolved. It does not print the account name or a masked token fingerprint.

For an adapter-declared structured CLI response, JSON also exposes parsed .data and preserves stdout/stderr separately under .result. Raw prints only the sanitized payload and keeps stderr on stderr; it is restricted to one direct provider or Command Engine operation and is not available for capabilities or diagnostics.

Note the position: --output is a global flag, so it goes before the provider name. Provider commands disable flag parsing so their arguments reach the provider untouched (which is what lets --json reach gh), and the runtime strips its own --output off the front.

runtime --output json github pr list --json number,title    # both flags work

--help

runtime --help
runtime github --help      # every operation, with the transport its provider chose
runtime files --help

runtime <provider> --help is the authoritative list of what a provider can do. Do not guess at operations — the help output is generated from the provider's real surface, so it can never drift from the binary you have installed.

The transport column (rest, graphql, cli, file) is shown for transparency. It is information, not a choice: you never select a transport, and nothing you write should depend on one.

Discovery

Sources, in increasing order of authority:

Source	What it gives you
<Runtime Home>/RUNTIME-AGENT.md	The vendor-neutral contract for this installed binary
<Runtime Home>/manifest.json	Providers and operations this binary can run — offline, generated from the same registry as the CLI
<Runtime Home>/commands/*.txt	Copy-paste cheatsheets, one per tool, refreshed with every binary version
<Runtime Home>/specs/	The capability authoring contract, per provider
runtime <provider> --help	The live operation surface of the binary you are running
runtime capability list	Capabilities this install can resolve; empty is a correct state

ls ~/.engineering-runtime/commands/
cat ~/.engineering-runtime/commands/github_commands.txt
cat ~/.engineering-runtime/commands/runtime_env_variables.txt

Every runtime … line in those cheatsheets is validated against the binary that ships them, so they are safe to copy.

Exit behaviour

Verified against the release this site documents. Success is exit 0. Every failure below is exit 1, with the quoted text on stderr, and an audit record for governed operations.

Situation	Exit	Literal message (or prefix)
Operation succeeded	0	result on stdout
Cobra unknown command	1	unknown command "aws" for "runtime"
Capability has no ```runtime block	1	capability validate: <path> has no ```runtime block
Capability names an unpublished operation	1	capability is invalid: then workflow[0]: "does not exist" is not an operation of provider "github"
File path outside file_policy roots	1	files write <path> is outside every directory policy grants write authority to (<root>). …
Missing GitHub token	1	authentication failed: no token found in $RUNTIME_GITHUB_TOKEN; export it (e.g. in ~/.zshrc: export RUNTIME_GITHUB_TOKEN=ghp_xxx) and open a new shell
Policy denied a provider operation	1	policy denied <provider> <operation>: …
Capability step failed	1	capability execute: step N (…): <that step's error>; earlier steps already audited

Denials are audited exactly like successes. The audit log answers "was this attempted and refused", not only "what happened".

Checking without executing

runtime resolve github repo list acme
runtime resolve files write ./notes.txt hello
runtime resolve capability execute files/notes-roundtrip

runtime resolve confirms a full command line resolves to a real command or provider operation, with zero side effects — no auth, no policy evaluation, no execution, no I/O against a platform. See Core Commands.

Operational examples on this site were verified against Runtime 0.9.8. After bootstrap, the version-exact files in Runtime Home win.