Skip to content

Core Commands

version, bootstrap, config validate, 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 files were seeded, refreshed and pruned on that run.

# a throwaway home, for testing
export ENGINEERING_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:

  • Locations — config, policy, context and capabilities paths, plus the active context name
  • 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
  • Runtime Providers — each provider, its auth provider, and its operation count broken down by transport
  • Policy warnings — every rule that can never match

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 context

Runtime Context is the execution state — where an operation runs. Full reference: Runtime Context.

runtime context show
runtime context show --output json
runtime context use staging

context show displays the active context's name, its full target (environment, github, cloud and kubernetes fields), and every context name available to switch to.

context use <name> requires that <name> already exists under contexts.<name> in context.yaml. There is no context create verb — the file is hand-edited, like config.yaml and policy-config.yaml.

Switching context never re-authenticates: Auth Engine identity and Runtime Context 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

This is the read side only. There is no write-side CLI verb, because nothing outside the runtime lifecycle is allowed to write an audit record.

Record fields

Field Meaning
executor OS username ($USER, then $USERNAME, else unknown)
consumer human | ci | ai — from ENGINEERING_RUNTIME_CONSUMER, defaulting to ci when CI is set
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 "${ENGINEERING_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

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 use staging
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.