Skip to content

CLI Reference

The binary is invoked as engrt. 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; engrt 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              configuration and native-auth readiness 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|register|sync           optional control plane — off by default
│
├── github <operation> ...       ┐ provider commands, generated from the
├── files  <operation> ...       │ provider registry
└── gcp project describe ...     ┘ v0.9.9

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, register, sync — the optional control-plane client
github The GitHub provider's operations
files The files provider's operations
gcp The curated GCP project read

Global flags

--output cli|json

Global, and available on every command. In v0.9.9, cli is the default human presentation; json is the canonical machine/agent contract. Human formatting is not a stable parsing API.

engrt github repo list
engrt --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. CLI 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. Deprecated 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.

Compatibility with v0.9.8 and the maintained native-payload CI workflow is preserved: text is a deprecated alias for cli; raw means sanitized execution payload without the Runtime presentation envelope, never untouched provider bytes. New scripts should read .data or .result.stdout from JSON.

All engines sanitize results before renderer selection. Structured sensitive fields (including temp_clone_token, accessToken, clientSecret and temporaryCredentials) become [REDACTED]; null stays null. Nested objects and arrays are covered. Benign fields such as token_count, max_tokens, password_policy and credential_type remain visible. Opaque text has known credential-shape/assignment protection, not arbitrary-secret detection. Audit and execution evidence retain minimized safe observations, not response bodies. See command results for exact rules/limits.

github repo view selects useful fields through optional provider metadata. Other structured objects/lists get generic previews without provider-specific renderer changes. JSON keeps the complete admitted sanitized result.

Human output has independent presentation limits:

Display Limit
Direct operation or entire capability execution 16 KiB, including truncation notice
Text/File read or command stdout/stderr preview 4 KiB, 60 lines, 240 Unicode code points per line
Object fields / list rows / table columns 12 / 20 / 8
Structured scalar/cell 120 Unicode code points; narrower provider widths apply
Heading or field label / count label 24 / 40 Unicode code points
Typed File edit preview 20 files, 20 diff lines per shown file
Capability steps First 19 and last, within the total byte budget

…, omitted counts and JSON guidance identify abbreviated content. Provider metadata obeys these limits; inapplicable metadata falls back to generic output. Curated projections point to JSON when they omit or shorten content. Tiny complete projections need no notice. Explicit JSON null renders null; HTTP 204/no body produces no invented output. CLI truncation does not change the execution truncation flag, status, exit code or canonical JSON.

Overall Runtime status includes required evidence recording. If a provider operation completed but recording failed, CLI shows Status: failure, Execution: succeeded and Evidence: failed. It explains the failure without printing internal error chains. Curated results appear directly under the summary; opaque command stdout uses Output: and stderr uses Stderr:. Do not repeat completed work to repair evidence.

JSON remains the canonical machine-readable truth: inspect .error_code, .error, .result.execution and .result.http alongside the overall .status. Detailed diagnostics are sanitized. There is no new verbose/debug flag or JSON state field. Capability output also preserves individual step outcomes; a run can fail to record evidence after all its steps completed successfully.

Captured excerpt from a local HTTP fixture whose request succeeded but whose audit-log permissions prevented evidence recording:

Status:          failure
Execution:       succeeded
Evidence:        failed
Message:         Operation completed, but Runtime could not record required execution evidence.
Diagnostics:     Use --output=json; do not repeat completed work to repair evidence.

Repository:      example/repo
Visibility:      private
Default branch:  main

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.

engrt --output json github pr list --repo cli/cli --json number,title    # both flags work

Output placement (v0.11.0)

Released v0.10.0 silently ignores a trailing --output json. v0.11.0 changes this:

  • It honors --output after a REST or GraphQL operation and in resolve, for example engrt github label get owner/repo bug --output json.
  • It never scans after command run or a gh-backed operation, so native flags such as gh's own --json reach the tool unchanged.
  • If --output is given both before and after with different values, the command refuses.

Root and provider help are grouped by purpose: Runtime, provider operations, capabilities, governed command execution, governance and evidence, utilities.

--help

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

engrt <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
engrt <provider> --help The live operation surface of the binary you are running
engrt capability list Capabilities this install can resolve; empty is a correct state
ls ~/.engrt/commands/
cat ~/.engrt/commands/github_commands.txt
cat ~/.engrt/commands/engrt_env_variables.txt

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

Exit behaviour

v0.11.0 capability exits

From v0.11.0, capability commands use exits 0–4; see capability results. Everything else keeps the behaviour below.

Success is exit 0; failures are exit 1. In Runtime v0.9.9, rendered CLI execution failures appear once in the human summary. Startup and unrendered errors use stderr; JSON returns one structured failure. Governed operations attempt to record evidence, and failure to record it is itself a Runtime failure.

Situation Exit Literal message (or prefix)
Operation succeeded 0 result on stdout
Cobra unknown command 1 unknown command "aws" for "engrt"
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 CLI refusal before dispatch; JSON retains the detailed grant error
No GitHub source available (auth status) 1 for the failing operation auth_unavailable: github authentication: no ENGRT session; use explicit auth login github (auth_store_unavailable where no OS secure store exists)
Policy denied a provider operation 1 Policy denied this operation. …; Refusal: policy (<rule>); Hint:; Execution: not dispatched
Compiled safety refused an operation (v0.13.0) 1 (capability step: 3) Compiled safety refused this operation; no policy document can allow it.; Refusal: compiled_safety (<invariant>)
Malformed request (v0.13.0) 1 The request was refused before dispatch.; Refusal: argument_invalid (provider_request\|request_validation)
Capability step failed 1 CLI identifies the stopped step and preserves earlier results; JSON retains the step error
Required execution evidence failed 1 Evidence: failed; actual execution observations remain visible

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

Checking without executing

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

engrt 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.

v0.10.0 adds local capability search and inspect. These commands are unavailable in released v0.9.9.

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