Skip to content

engrt command run

engrt command run [--] <binary> [args...]

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

  1. A provider chose it. engrt github pr list dispatches to the GitHub provider, which decided that operation is best served by gh. The provider supplies the binary and arguments.
  2. 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:

engrt config validate

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

command_policy:
  denied_binaries: [rm, sudo, chmod, curl, wget, ssh]

Refused outright, independent of allowed_binaries.

3. Subcommand rules

command_policy:
  rules:
    terraform:
      denied: ["destroy"]
    git:
      denied: ["push --force", "reset --hard"]
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:

command_policy:
  rules:
    vault:
      environment:
        - VAULT_ADDR
        - VAULT_TOKEN

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_TOKEN exists, Runtime validates it and brokers it to gh as GH_TOKEN and GITHUB_TOKEN.
  • Otherwise, Runtime validates the existing native session with gh auth status and 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:

engrt --output json command run gh repo list --limit 5 \
  --json nameWithOwner,visibility,url

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]; null stays null. Benign names such as token_count or password_policy stay 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_dispatched only before command start; otherwise started.
  • completion: not_started, exited, signaled, timeout, canceled or wait_failed.
  • effect: none, reported succeeded, or unknown after a command failure.
  • duration_ms, optional signal, and an optional engine error_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.

engrt command run git push --force
engrt audit tail -n 1 --output json

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:

workflow:
  - binary: gh
    args: [repo, list, --limit, "10", --json, nameWithOwner]

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.