CLI Reference¶

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

Command tree¶

runtime
├── version                      print the binary version
├── bootstrap                    prepare / inspect the Runtime Home
├── config validate              one read-only health report
├── context show|use             view or switch Runtime Context
├── auth status|login|logout     validate platform credentials
├── audit tail                   read the audit log
├── resolve <command-line...>    check a command line resolves — zero side effects
├── capability validate|execute  run a Markdown workflow
├── command run <binary> ...     the Command Engine escape hatch
│
├── 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`, `context`, `audit tail`, `resolve`
`auth`	`status`, `login`, `logout`
`capability`	`validate`, `execute`
`command run`	The Command Engine
`github`	The GitHub provider's operations
`files`	The files provider's operations

Global flags¶

`--output text|json`¶

Global, and available on every command.

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

JSON output includes the provider, operation, transport, identity and result — the machine-readable surface for CI and AI consumers. Text is the default and is meant for humans.

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¶

Three sources, in increasing order of authority:

Source	What it gives you
`<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

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¶

Situation	Result
Operation succeeded	Exit 0, result on stdout, audit record written
Operation failed	Non-zero exit, error on stderr, audit record written
Policy denied	Non-zero exit, `policy denied …` message, audit record written
Auth invalid	Non-zero exit with the platform command to run yourself
Capability step failed	Execution stops at that step; earlier steps are 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.