Core Commands¶
Released v0.14.0
GitHub, native-command and audit changes, recovery guidance and qualification limits are described in the v0.14.0 operations guide.
version, bootstrap, config validate, config diff policy, context, audit tail and
resolve.
HTTP execution results¶
Runtime v0.9.9 preserves HTTP observations in the same JSON envelope as other provider operations. These are read-only examples:
engrt --output json github api GET /repos/cli/cli
engrt --output json github graphql 'query { repository(owner:"cli", name:"cli") { nameWithOwner } }'
Both were exercised against GitHub with the released v0.9.9 binary. Inspect status,
error_code, data, result.execution and result.http; the latter carries
HTTP status, a safe request ID and an explicit pagination indicator. It does not
carry raw headers or credentials. Do not interpret result.exit_code as an HTTP
status—it is the legacy process field.
Runtime exits 0 on a validated success and 1 on failure. An HTTP 200
GraphQL response containing errors is still a failure; safe partial data remains
available. JSON null is present as data: null, while explicit no-content
responses omit data. One JSON result is printed on execution failure, without
an additional unstructured copy of the error on stderr.
No HTTP failure authorizes automatic retry. Timeout/cancellation after transmission can leave unknown effects; previous capability steps are not rolled back. GitHub HTTP limits and error codes cover redirect refusal, response bounds, redaction and incomplete inventories.
engrt version¶
Prints the version of the installed binary.
This is the version compared against <Runtime Home>/version to decide whether
specs/ and commands/ need refreshing. See
Runtime Home.
engrt bootstrap¶
Prepares the Runtime Home from assets embedded in the binary. Idempotent — safe to run any number of times.
Bootstrap runs automatically before every command, so you rarely invoke it
directly. engrt 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 ENGRT_HOME=/tmp/runtime-home
engrt bootstrap
ls -R /tmp/runtime-home
Runtime v0.9.9 checks content as well as version. Refresh is serialized;
interrupted publication retains a pending marker until the intended binary
successfully rebuilds its contracts. Do not delete .bootstrap.lock or
.bootstrap-pending.json to bypass a refusal. See
recovery and snapshot limits.
Linux/macOS bootstrap uses descriptor primitives. Windows support is not yet
available in v0.9.9.
Leading Runtime --output json, --output=json or -o json also governs early
bootstrap failures on pass-through provider and command run commands. A startup
refusal returns one JSON object (status: failure, error_code: execution_rejected,
and error) and exit 1, without an engine result or duplicate stderr. Runtime
does not scan output flags after the binary/provider operation. Invalid leading
Runtime output flags refuse before Home creation; CLI/raw startup diagnostics
remain on stderr. This changes error presentation, not bootstrap admission.
engrt config validate¶
Inspect configuration and runtime readiness. Config/policy documents are not edited. In v0.9.9, enabled auth checks write durable evidence and may refresh native CLI caches; the report is not effect-free.
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 actual identity/readiness proof or failure (kubeconfig readiness is not a live API-authentication check)
- 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 conciseallowed_binariesdrift summary pointing atengrt 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 fromallowed_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.
engrt config diff policy¶
Read-only. Prints the full allowed_binaries set difference between the
effective $ENGRT_POLICY_FILE community policy and the compiled default
this binary ships.
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".
engrt 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.
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.
engrt 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.
engrt audit tail¶
Every operation — success, failure, or denial — is recorded as one
structured JSON line at <Runtime Home>/logs/audit.log.
engrt audit tail # most recent 10 (default)
engrt audit tail -n 20
engrt audit tail --lines 50
engrt 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.
Retained integrity and historical completeness¶
Local verification establishes integrity of retained frames. Without an external
trusted terminal checkpoint, complete trailing-frame deletion cannot be detected.
Such trailing-frame removal requires no recomputation of remaining hashes.
Intact: true establishes internal consistency, not historical completeness.
The local journal is tamper-evident, not tamper-proof. External checkpointing is
post-v0.9.9 backlog work, not a release dependency or current feature.
Free-text delivery/control detail is sanitized centrally before hashing. Correlation identifiers are preserved; if sanitization would alter one, the control append refuses. Unsafe or oversized detail fails closed without partially mutating the journal.
Record fields¶
| Field | Meaning |
|---|---|
executor |
OS username ($USER, then $USERNAME, else unknown) |
consumer |
human | ci | ai | undeclared — from ENGRT_CONSUMER; when unset, ci if CI is set, ai under a known agent harness, otherwise undeclared (v0.13.0; never inferred human) |
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; actor_source: detected_environment (v0.13.0) marks a detected agent harness |
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 |
Adapter/binding class, not raw project/account/cluster selectors |
command |
Operation class, e.g. github repo list; v0.9.9 resolution failures retain only the provider class |
transport |
cli | rest | graphql | file. Empty for command run and the auth verbs |
policy_decision |
v0.9.9: coarse allow / deny when evaluated, not the argument-bearing reason |
refusal_class / refusal_rule |
v0.13.0, on refusals: which kind of check refused (policy, compiled_safety, context_unsupported, argument_invalid, auth) and its rule or invariant — never an argument value |
dispatch_attempted |
v0.13.0: false on every pre-dispatch refusal |
http_method / operation_path_template / graphql_operation_class / graphql_root_fields |
v0.13.0, REST/GraphQL: the request shape with owner, repository, ref, branch, path and IDs replaced by placeholders (e.g. /repos/{owner}/{repo}/git/refs/{ref}), and the schema names of GraphQL root fields (not aliases). A refusal before authentication records no provider principal — none was resolved |
status |
Outcome |
message |
v0.9.9: safe diagnostic class, not raw error/native invocation text |
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.
Step-result records (v0.11.0)¶
From v0.11.0, capabilities that use
outputs and verification
add one hash-chained capability_step_result record per evaluated step. A step
is evaluated when it ran, was gated out, or was stopped before dispatch. Each
record carries:
capability_step_status;capability_observation(PRESENT/ABSENT);capability_verification(passed/failed/unavailable);capability_outcome, on the step that closes its logical operation;capability_output_digests: declared output names with keyed digests, never raw values.
A step that ran shares its operation's invocation_id. The operation's own
record keeps transport truth, so a 404 read as ABSENT is still a 404 there.
engrt audit tail shows step_status, observation, verification and
outcome; the digests appear in --output json. Legacy capabilities add no
such records, and v0.10.0 can still verify a journal that contains them.
New file-edit records retain ordered outcomes, counts and before/after digests
but leave per-file path empty. Caller-visible results still contain details.
See stored audit privacy
for the two JSON guards, per-record bounds, retained metadata and historical-data
limits. Consumers must not parse raw arguments or denial reasons from these
new stored records; field shapes and producer schema remain unchanged.
Following the log¶
audit tail is a snapshot, not a follow. For a live view, poll it or read the
file directly:
For grep/jq work at a scale audit tail is not meant for, read the raw log:
audit tail --output json returns integrity plus records; text output prints
a warning before records if the durable chain is broken. engrt 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
engrt audit recover to mark unresolved intents outcome_unknown. Recovery
is explicit so one parallel process never classifies another as crashed.
An evidence_finalization_failed operation retains its actual result even when
its journal intent is still unresolved. This can include native exit 0, a
successful File write, or an installed Portal generation. Follow
incomplete evidence recovery
instead of repeating the operation. Recovery observes unknown operation outcomes;
it does not synthesize missing capability aggregate completions.
An append can fail during sync/close after a complete completion frame is written.
Inspect the verified journal after repairing storage: recovery adds unknown only
for intents with no completion, never duplicates a visible completion, and never
treats a recording error as permission to replay the operation.
engrt audit status
engrt audit verify
engrt audit recover # only after confirming the Home is quiescent
v0.9.9 audit verify exits 1 when the chain is broken or its final
line is incomplete, in both text and JSON. JSON retains one verification
object, not a second error envelope. A valid JSON object without the final LF
is still an incomplete journal line. Old unwrapped records are accepted only as
a pre-upgrade prefix, not as unchained insertions into newer evidence. See
audit storage safety
for permissions, lock contention, unchanged-history and recovery limits.
Status counts now come from one locked journal snapshot. Verification and append
preparation stream history; audit tail -n 20 retains only its most recent 20
ordinary records. Oversized lines or retained collections refuse explicitly.
See journal operating range
for measured scale and the distinction between read bounds and retention.
engrt 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.
engrt resolve files write ./notes.txt hello
engrt resolve github repo list acme
engrt resolve auth login github
engrt resolve context retire
engrt resolve audit tail -n 5
engrt 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 engrt … 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.
v0.10.0 also records the actual executing release as engrt_version,
with engrt_platform and engrt_go_version. When available, engrt_commit and
engrt_modified identify the VCS build. This audit version is an exact release;
the capability declaration’s engrt_version is a compatibility requirement.
Run/step intent, completion and ordinary records retain the same build identity.
Recovery preserves original provenance. Old records omit these fields and remain
unchanged; credentials and raw capability inputs are not added to audit.
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.