Skip to content

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.

engrt version

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.

engrt bootstrap
engrt bootstrap --output json

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
# v0.9.9: repair missing/changed assets without deleting state
engrt bootstrap

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.

engrt 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 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 concise allowed_binaries drift summary pointing at engrt 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.


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.

engrt config diff policy
engrt --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".


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.

engrt context show
engrt context show --output json
engrt 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.

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:

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

tail -f "${ENGRT_HOME:-$HOME/.engrt}/logs/audit.log"

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

jq 'select(.policy_decision == "deny")' \
  ~/.engrt/logs/audit.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.