Core Commands¶

version, bootstrap, config validate, config diff policy, context, audit tail and resolve.

`runtime version`¶

Prints the version of the installed binary.

runtime version

This is the version compared against <Runtime Home>/version to decide whether specs/ and commands/ need refreshing. See Runtime Home.

`runtime bootstrap`¶

Prepares the Runtime Home from assets embedded in the binary. Idempotent — safe to run any number of times.

runtime bootstrap
runtime bootstrap --output json

Bootstrap runs automatically before every command, so you rarely invoke it directly. runtime bootstrap exists so you can see what happened; it never unlocks anything.

--output json reports the home and capabilities paths, whether the home was just created, the version transition, and exactly which release-owned files were refreshed or pruned. The compatibility seeded_files field is always an empty array in 0.6.0; Bootstrap seeds no user-owned content.

# a throwaway home, for testing
export RUNTIME_HOME=/tmp/runtime-home
runtime bootstrap
ls -R /tmp/runtime-home

# force a refresh without a version change
rm ~/.engineering-runtime/version && runtime bootstrap

`runtime config validate`¶

One read-only report. Never modifies anything. This is the first command to run when something is not working.

runtime config validate

It reports:

Authorities and locations — selected config/policy origins, the compatibility capability-cache path, and native-tool context ownership
Auth Providers — each provider's enabled state, whether its CLI binary is installed, and its live auth status
Allowed binaries — an installed check for every entry in allowed_binaries, and when an env-selected community policy differs from this release's compiled default, a concise allowed_binaries drift summary pointing at runtime config diff policy
Runtime Providers — each provider, its auth provider, and its operation count broken down by transport
Policy warnings — every rule that can never match

A verified enterprise generation is reported as provenance on the Policy line and is never compared with vendor defaults. There is no suppression setting.

Policy warnings¶

The report closes with warnings for dead rules:

a providers.<name> rule naming an operation the provider does not expose
a block for an unregistered provider
a command_policy.rules.<binary> entry for a binary absent from allowed_binaries

Provider rules are checked against the provider's real operation surface — the same surface capability validate resolves against. Output is sorted, so the report is deterministic run to run.

This exists because a denial that matches nothing reads as governance while enforcing nothing. Check the warnings after every policy edit.

`runtime config diff policy`¶

Read-only. Prints the full allowed_binaries set difference between the effective $RUNTIME_POLICY_FILE community policy and the compiled default this binary ships.

runtime config diff policy
runtime --output json config diff policy

Version 1 compares allowed_binaries only — not command_policy, provider rules, config, or the operation-time context snapshot. A compiled-default install reports that the sets match. A verified enterprise generation is not compared.

Nothing is written. An absent default binary may be an old default or an intentional removal; the report says "differs", not "wrong".

`runtime context`¶

Runtime keeps no context of its own. These commands observe where your tools are pointed and explain a retired document; neither changes anything. Full reference: Where operations run.

runtime context show
runtime context show --output json
runtime context retire

context show reports, per tool, the effective target, how firmly it is held (binding), how Runtime learned it (learned), and the native command that changes it.

context retire is a dry run for upgraders: it parses a legacy <Runtime Home>/context.yaml, says which native tool owns each value, and prints an archive command. Runtime never moves, renames or deletes the file. While one is present, governed execution is blocked.

runtime context use was removed. Selecting a context is the owning tool's operation — kubectl config use-context, oc project, gcloud config set project — and Runtime does not run those on your behalf.

Where an operation runs never re-authenticates: Auth Engine identity and the effective target are resolved independently.

`runtime audit tail`¶

Every operation — success, failure, or denial — is recorded as one structured JSON line at <Runtime Home>/logs/audit.log.

runtime audit tail                 # most recent 10 (default)
runtime audit tail -n 20
runtime audit tail --lines 50
runtime audit tail --output json

tail, status, and verify are read-only. The only audit mutation verb is the narrow recovery control below; it cannot invent or replay an operation.

Record fields¶

Field	Meaning
`executor`	OS username (`$USER`, then `$USERNAME`, else `unknown`)
`consumer`	`human` \| `ci` \| `ai` — from `RUNTIME_CONSUMER`, defaulting to `ci` when `CI` is set
`execution_kind` / `invocation_id`	Direct command vs capability step and its unique invocation
`actor_name` / `actor_source` / `actor_assurance`	Readable actor label and its explicitly self-asserted assurance
`session_id`	Optional shell, CI, agent, or pod correlation ID
`capability_*`	Exact name/source/digest, run ID, execute/preview mode, and step/total when applicable
`runtime_context`	The active context at execution time
`command`	`"<provider> <operation>"`, e.g. `github repo list`
`transport`	`cli` \| `rest` \| `graphql` \| `file`. Empty for `command run` and the auth verbs
`policy_decision`	Allowed or denied
`status`	Outcome
`message`	Detail, including the denial reason
`duration_ms`	Elapsed time

The transport field is what lets a reader tell that github repo list went out over REST while github pr list shelled out to gh.

Following the log¶

audit tail is a snapshot, not a follow. For a live view, poll it or read the file directly:

watch -n 2 'runtime audit tail -n 5'

tail -f "${RUNTIME_HOME:-$HOME/.engineering-runtime}/logs/audit.log"

For grep/jq work at a scale audit tail is not meant for, read the raw log:

jq 'select(.policy_decision == "denied")' \
  ~/.engineering-runtime/logs/audit.log

audit tail --output json returns integrity plus records; text output prints a warning before records if the durable chain is broken. runtime audit status counts capability starts/completions and unresolved effects. After a crash, confirm no Runtime process still uses the Home, reconcile the target, then run runtime audit recover to mark unresolved intents outcome_unknown. Recovery is explicit so one parallel process never classifies another as crashed.

runtime audit status
runtime audit verify
runtime audit recover   # only after confirming the Home is quiescent

`runtime resolve`¶

Checks whether a full command line would resolve to a real command or provider operation. Zero side effects: no auth, no policy evaluation, no execution, no I/O against a platform.

runtime resolve files write ./notes.txt hello
runtime resolve github repo list acme
runtime resolve auth login github
runtime resolve context retire
runtime resolve audit tail -n 5
runtime resolve bootstrap

It walks the real command tree for static commands, and calls the same matching a provider uses internally for the operation itself — so a provider command gets its operation checked, not just its provider name.

This is the same guarantee capability validate gives a YAML step, applied to a raw CLI invocation. It is what validates every runtime … line in the shipped commands/*.txt cheatsheets, which is why those are safe to copy.

Use it to check a command line in a script or a generated suggestion before anything runs.

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

Core Commands¶

runtime version¶

runtime bootstrap¶

runtime config validate¶