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.
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.
Output placement (v0.11.0)¶
Released v0.10.0 silently ignores a trailing --output json. v0.11.0 changes
this:
- It honors
--outputafter a REST or GraphQL operation and inresolve, for exampleengrt github label get owner/repo bug --output json. - It never scans after
command runor agh-backed operation, so native flags such asgh's own--jsonreach the tool unchanged. - If
--outputis 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.