engrt command run¶
Arguments after <binary> reach it verbatim. Runtime's own flags (-o/--output)
and an optional -- go before <binary>; a -- directly after <binary> is
refused (v0.13.0), because no admitted tool accepts it before its subcommand.
engrt command run --help prints this command's help.
The Command Engine runs reviewed native CLI operations behind one governed execution boundary. For an admitted semantic mode it preserves the native CLI's authentication, context and output behaviour while Runtime supplies policy, bounded execution and audit.
engrt command run gh repo list --limit 5
engrt command run kubectl get pods
engrt command run gcloud --project=acme-staging compute instances list
engrt command run terraform -chdir=/path/to/project plan
Commands run in a private, empty working directory — never your current
directory — so repository hooks and local plugins have nothing to load, and a
target-sensitive tool must be told its target on the command line, for example
engrt command run git -C "$PWD" pull --ff-only origin main. See
What the process receives.
Two ways the Command Engine is reached¶
- A provider chose it.
engrt github pr listdispatches to the GitHub provider, which decided that operation is best served bygh. The provider supplies the binary and arguments. - Directly, via
command run— the governed native CLI path for modes a provider does not expose.
Both paths are gated by the same policy. When a provider picks the CLI
transport, allowed_binaries and command_policy are evaluated on top of
the provider's own rule. A provider can only reach binaries the installation
already permits, and cannot launder a denied binary through an operation.
Prefer a provider operation¶
command run is an escape hatch, not the default style. When a provider
already exposes what you need, use it:
engrt github repo list # preferred
engrt command run gh repo list # works, but bypasses the curated surface
A provider operation is a stable contract — the transport can change beneath it
without breaking you. A command run invocation is pinned to one tool's exact
CLI.
Allowed binaries¶
Only binaries in allowed_binaries may execute at all. The compiled default
policy permits 21 (git, gh, terraform, pulumi, packer, gcloud,
gsutil, bq, aws, az, kubectl, oc, helm, kustomize, flux,
istioctl, argocd, docker, podman, vault, sops). Being on the list
does not mean every invocation is admitted — v0.9.9 refuses several of these
binaries or modes; see
Command Engine Binaries.
Check what your install actually allows — new entries in a release do not reach an existing policy file:
That report also tells you which allowed binaries are actually installed.
Governance layers¶
1. Binary allow-list¶
A binary not in allowed_binaries can never run.
2. Hard-denied binaries¶
Refused outright, independent of allowed_binaries.
3. Subcommand rules¶
| List | Matching |
|---|---|
denied |
A contiguous run of argument tokens anywhere in the command |
allowed |
Prefix match; when present, only matching prefixes may run |
Denials always win. Because denied matches anywhere, leading flags cannot
bypass a rule.
Compiled destructive floor (v0.13.0)¶
Independently of any policy document —
even one that allows them — destructive forms are refused by
compiled-safety-profile/v4 with Refusal: compiled_safety (destructive-effect):
| Tool | Refused forms |
|---|---|
git |
push --force, -f, --force-with-lease, --force-if-includes, +refspec, --mirror, --delete, -d, :ref, --prune — including unique abbreviations Git accepts (--delet, --force-w) and ambiguous ones such as --forc, which Git rejects anyway; reflog expire/delete/drop unless --dry-run; gc --prune=<date> other than never; prune unless --dry-run; filter-branch, filter-repo; update-ref -d/--stdin; reset --hard (and --har); clean unless it is a dry run (-n) — for clean, prune and reflog the last of --dry-run/--no-dry-run wins, as in Git; global -c alias.*, -c remote.*.push= with a +… or :<ref> refspec, -c remote.*.mirror, and --config-env (attached or as a separate argument) for any of those names (its value comes from the environment). Aliases and push refspecs set in repository or user config files are not visible to the catalog |
gh |
repo delete; api with DELETE, force=true or a destructive GraphQL mutation |
| others | terraform destroy, pulumi destroy, kubectl delete namespace, oc delete project, helm uninstall, flux delete\|uninstall, destructive gcloud, gsutil, bq, docker, podman, vault, argocd, istioctl runs. IaC apply is not affected |
engrt command run terraform destroy -auto-approve # compiled_safety (destructive-effect)
engrt command run git -C /tmp/wd push origin +main # compiled_safety (destructive-effect)
Do these deliberately outside Runtime if they are really intended. The catalog is finite; it is not a sandbox.
Full syntax is on the Policy page.
4. Semantic context support¶
An installed binary that passes policy still needs a known context contract. Runtime classifies an invocation as context-aware, explicitly context-free, or unsupported. When behaviour differs by subcommand, Runtime admits an exact semantic mode instead of trusting the whole binary. Unknown flags and command families refuse before any probe.
gh repo list (gh.repo.list) is the only admitted direct gh mode. gh pr
list, gh auth, extensions, and every other direct gh mode are
context-unsupported. Provider operations such as engrt github pr list are
unaffected because the GitHub provider owns their semantics.
5. The compiled floor¶
Some refusals are compiled into the binary, and a policy that explicitly allows the operation does not override them.
The one you are most likely to meet is credential export: an operation
whose output is a secret. The default output shows a short status; the full
reason is in the JSON error field. With GCP authentication enabled:
$ engrt command run gcloud auth print-access-token
...
Status: denied
Execution: not dispatched
Message: Compiled safety refused this operation; no policy document can allow it.
Refusal: compiled_safety (secret-export-operation,unpinned-side-effect)
Reason: secret-export-operation: `gcloud auth print-access-token` is a credential-export operation: its output is an
access token. …
Hint: no setting can allow this; do it deliberately outside Runtime if it is really intended
$ engrt --output json command run gcloud auth print-access-token | jq -r .error
compiled safety profile (compiled-safety-profile/v4) denied: secret-export-operation: `gcloud auth print-access-token` is a credential-export operation: its output is an access token. An approved tool may use a credential internally — that is the whole native-credential model — but it may not turn one into Runtime output; unpinned-side-effect: ...
If authentication.gcp.enabled is false, gcloud commands stop earlier with
error_code: auth_disabled instead.
The distinction is where the bytes go, not whether a secret is involved.
kubectl get secret -o yaml exports secret values, so it is refused before
dispatch. Also denied: reading a secret out of a manager (gcloud secrets
versions access, aws secretsmanager get-secret-value, az keyvault secret
show, vault kv get), printing a session token (oc whoami -t, gh auth
token), decrypting to stdout (sops -d), git credential fill, and the
Terraform state/output rendering described in the
Policy page.
The second floor denial is tool reconfiguration: an operation that changes the tool rather than the system you are operating on.
$ engrt --output json command run gcloud components install gke-gcloud-auth-plugin | jq -r .error
compiled safety profile (compiled-safety-profile/v4) denied: tool-lifecycle-mutation: `gcloud components install` changes gcloud itself, not the system you are operating on: it adds executables to the SDK install root, which policy pinned and digested. Runtime pins the artifact and reads where your tool is pointed; an operation that rewrites either one is not the operation policy thought it was approving. Do it deliberately in your own shell, outside Runtime; unpinned-side-effect: ...
Also denied: gcloud config set, gcloud auth login, kubectl config
use-context, kubectl config set-credentials, oc login / oc logout,
git config --global, helm plugin install, docker login, vault login,
argocd login, terraform login, gh extension install, gh alias set,
aws configure set and az account set.
Reading is untouched. kubectl config view, kubectl config
current-context, gcloud config get-value project, gcloud auth list and
git config --get all run. Do reconfiguration in your own shell. The two
Runtime already owns are audited verbs: engrt auth logout gcp and engrt
auth logout openshift.
Evaluation order¶
Policy is evaluated before the Command Engine runs, against the final arguments:
context resolution → artifact pinning → compiled floor → allow-list →
denied_binaries → subcommand rules → auth → execute
Selectors are resolved into the argument list before the policy check, so the command policy judged is the command that runs — nothing is added afterwards. The binary is resolved to one exact file before the decision, so the artifact policy reviewed is the artifact that executes.
What the process receives¶
The Command Engine builds an environment rather than passing on its own. A variable reaches a tool only when the tool's built-in contract declares it and your policy permits it for that binary:
Omit environment and the tool's own contract decides. An empty list means
no variable at all. The list can only narrow the contract. Loader variables
(LD_PRELOAD, NODE_OPTIONS, GIT_SSH_COMMAND) are refused for everyone.
| Input | What the process gets |
|---|---|
| Working directory | A private, empty per-operation directory — never the directory you ran engrt from. Name the target on the command line (git -C DIR, terraform -chdir=DIR, --project, --namespace). A command that depends on the current repository or Terraform project is not supported through command run in this release |
HOME |
An isolated per-operation home, removed afterwards — except for tools whose contract declares they need the real one because their credentials live there (kubectl, oc, gcloud, git, and the rest of the native-credential set) |
PATH, stdin, pager, editor |
A fixed minimal PATH; stdin closed, so a tool that decides to prompt fails instead of hanging; no pager and no editor |
Repository hooks, .terraform/ provider plugins and local provisioners have
nothing to load from the empty directory. Git hooks are switched off, helm
plugins point at an empty directory, and the Cloud SDK update check is disabled.
Credential helpers — git's, docker's, and the user.exec plugin in your
kubeconfig — are kept, because they are how native authentication works. A
helper outside the minimal PATH must be admitted with
admitted_helpers.
Upgrading from 0.5.x
A command that quietly relied on an ambient variable will now fail. Add the
name to that binary's environment list if its contract declares it.
These controls are defence in depth. Runtime is not a general-purpose or hostile-code sandbox.
Authentication¶
Auth is resolved from config.yaml's command_providers map:
command_providers:
gh: github
gcloud: gcp
gsutil: gcp
bq: gcp
kubectl: kubernetes
oc: openshift
helm: kubernetes
flux: kubernetes
istioctl: kubernetes
A binary with no entry skips the Auth Engine entirely. There is no silent
fallback to a default provider — omission means "manages its own credentials"
(terraform's provider blocks, Docker's registry logins) or "no Auth Engine
provider exists for that platform yet" (aws, az, vault). A mapping alone
does not make a binary supported: in v0.9.9 the mapped gsutil, bq, helm,
flux and istioctl invocations still refuse.
v0.12.0
From v0.12.0, raw command run gh no longer receives an ENGRT token bridge; it
uses independently configured native gh authority. See
Governed authority. The paths below
describe the released pre-0.12 behavior.
For gh.repo.list, Runtime uses one of two platform-native paths:
- If the configured
ENGRT_GITHUB_TOKENexists, Runtime validates it and brokers it to gh asGH_TOKENandGITHUB_TOKEN. - Otherwise, Runtime validates the existing native session with
gh auth statusand gh reads the same home, config directory, host and credential store as a local invocation.
Runtime never runs gh auth login. For GCP, Kubernetes and OpenShift sources,
see GCP, Kubernetes and OpenShift.
Where an operation lands¶
Runtime keeps no context of its own. Where an operation lands comes from the tool that will run it, or from the arguments you passed. See Where operations run.
Selectors already on your command are authoritative. When one is missing, Runtime reads it from the tool's own state and resolves it into the argument list before policy evaluates the command:
| Binary | Resolved when absent | Read from |
|---|---|---|
gcloud |
--project=<project> |
gcloud's own active configuration |
kubectl, oc |
--context=<name> and -n <namespace> |
the current kubeconfig context |
gh repo list |
explicit owner, otherwise authenticated account and host | gh arguments, GH_HOST and native auth configuration |
Nothing is added when the flag is already present. Conflicting repeated
selectors refuse. Registered context-free binaries receive their arguments
unchanged; an unsupported binary or mode is refused rather than treated as
context-free by omission. helm, flux and istioctl receive no namespace
injection.
Binding strength limits what may change¶
| Strength | Meaning | Reads | Changes |
|---|---|---|---|
strong |
the target cannot be reinterpreted by the tool afterwards | ✅ | ✅ |
context_free |
the operation carries its own coordinates | ✅ | ✅ |
selector_bound |
Runtime pinned the selectors, but the tool re-reads a mutable mapping to interpret them | ✅ | ❌ |
So today kubectl get pods runs while kubectl delete pod web-1 is refused
with unpinned-side-effect (kubectl delete namespace is already caught by the
default policy rule): a change approved against selectors the
tool re-resolves afterwards could land somewhere policy never saw. The explicit
in-cluster Kubernetes source is strongly bound but still read-only in v0.9.9.
Output modes¶
Default cli shows Runtime status, native exit code, truncation notices and
sanitized stdout/stderr. Each stream preview is at most 4 KiB, 60 lines and 240
Unicode code points per line, within a 16 KiB display budget. Omissions are
visible and direct you to JSON. Human formatting is not a parsing API.
Use Runtime JSON for automation. When the CLI explicitly declares JSON, the
parsed value is available at .data; stdout and stderr stay separate under
.result:
raw is deprecated compatibility for one direct provider or Command Engine
operation (not a multi-step capability); it returns the sanitized native
payload, never original provider bytes. text is a deprecated alias for cli.
Output sanitization¶
Results pass a shared sanitization step before becoming Runtime output, audit or evidence:
- Field names ending in token, secret, credential(s), and exact names such as
password, authorization, private_key, api_key, access_key and cookie are
sensitive (case-insensitive;
_,-, spaces and dots ignored; nested maps and arrays included). Non-null values become[REDACTED];nullstaysnull. Benign names such astoken_countorpassword_policystay visible. - Known granted credential values are removed wherever they reappear, including after JSON decoding.
- Opaque text recognizes known credential shapes and obvious assignments
(
Authorization: Bearer ...,access_token=...,password=...). - Invalid or over-budget representations are withheld without erasing the
actual execution observations; the failure code is
output_sanitization_failed.
Unlabeled, split or encoded secrets cannot be universally detected. Sanitization is defence in depth, not data-loss prevention — admission rules and credential store protection remain necessary.
Native JSON selectors (v0.9.9)¶
Runtime's global --output json chooses the outer envelope. The native tool
needs its own explicit selector to produce typed .data:
| Tool | Recognized native forms |
|---|---|
gh |
--json fields, --json=fields, without jq/template transformations |
gcloud |
--format=json, --format json |
kubectl, helm |
-o json, -o=json, -ojson, --output json, --output=json |
terraform |
output -json, show -json, before an operand; optional global -chdir=DIR comes first |
aws |
--output json, --output=json for modeled service responses |
az |
--output json, --output=json, -o json, -o=json, -ojson |
Repeated output selectors, unknown flags, help or transformation modes remain
text/plain — for example gh --jq/--template, kubectl watch/raw, Terraform
plan -json, and gcloud format expressions such as json(name). The installed
<Runtime Home>/specs/execution-result-contract.md is the exact contract.
This is output classification, not permission to execute. Helm, AWS and
Azure paths refused by context admission remain refused, and the Terraform
credential-export floor still refuses output/show rendering (see
migration guidance).
Declared JSON must be one valid, nonempty UTF-8 JSON value. Invalid or truncated
output fails with invalid_json_output after dispatch, which is not a safe
retry. Valid JSON null is retained as .data: null; absent data is different.
Failure results and exit codes¶
Runtime exits 0 on success and 1 on execution failure, denial, timeout,
handled cancellation or evidence-recording failure. The child's exit code is
retained at .result.exit_code; -1 means no numeric child exit was observed
(failed start or a signal).
JSON failures are one object with status (failure or policy denied),
error and error_code. Partial sanitized stdout and stderr remain under
.result. The .result.execution fields distinguish:
dispatch:not_dispatchedonly before command start; otherwisestarted.completion:not_started,exited,signaled,timeout,canceledorwait_failed.effect:none, reportedsucceeded, orunknownafter a command failure.duration_ms, optionalsignal, and an optional engineerror_code.
error_code |
Meaning |
|---|---|
execution_rejected |
Refused before dispatch |
process_not_started |
The binary could not be started |
process_exit_nonzero |
The tool ran and exited non-zero |
process_signaled |
The tool was terminated by a signal |
process_timeout |
The timeout elapsed |
process_canceled |
The caller or a signal canceled the operation |
process_wait_failed |
Runtime could not observe completion |
invalid_json_output |
Declared JSON was empty, malformed or truncated |
output_sanitization_failed |
The result could not be safely sanitized; execution observations are preserved |
evidence_finalization_failed |
The operation's evidence record could not be completed |
An evidence failure retains the observed command result: overall failure can
coexist with child exit 0. Runtime never reruns the operation to repair
evidence. The complete field reference is installed at
<Runtime Home>/specs/execution-result-contract.md.
Cancellation and recovery¶
Commands default to a 5-minute timeout and 1 MiB per output stream, with truncation stated. On supported Unix systems, SIGINT/SIGTERM or caller cancellation terminates the owned process group, with at most 100 ms graceful termination before kill.
A timeout, signal, nonzero exit, sanitization failure or evidence failure cannot
prove that an API effect did not land. Inspect the target with an authorized
read before deciding whether to retry. not_dispatched describes the
requested operation; a preparatory native probe may already have run.
Termination does not undo external effects. See
Troubleshooting.
Auditing¶
Every invocation — allowed, denied, or failed — is recorded.
The transport field is empty for command run records, which is how you tell
a direct invocation apart from a provider operation that chose the CLI.
Deliberately excluded¶
ansible and ansible-playbook are not on the allow-list. Their ad-hoc
and playbook modules are arbitrary remote command execution — the same risk
category as ssh — and the dangerous part is an opaque payload argument that a
denied: rule cannot meaningfully cap.
In capabilities¶
A binary: step is the same escape hatch inside a capability:
The binary and semantic mode must pass all admission gates or validation fails.
engrt itself is not an allowed binary — a capability cannot invoke
another capability. See
Composing capabilities.
Restricted gcloud diagnostics (v0.9.9)¶
gcloud info admits only the exact --format=value(basic.version) or
--format=json(basic.version) projection. Unbounded diagnostics and arbitrary
format/transform flags refuse before dispatch because SDK configuration can
contain credentials. gcloud version remains a separate admitted control.
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.