Skip to content

engrt capability

engrt capability list
engrt capability authoring-context
engrt capability validate <path|name>
engrt capability plan     <path|name> [--input key=value ...]
engrt capability execute  <path|name> [--input key=value ...]

For the file format, see the Capability Authoring Reference. For workflow guidance, see Validate & Execute. The installed contract is <Runtime Home>/RUNTIME-AGENT.md; the providers list is <Runtime Home>/manifest.json.


engrt capability authoring-context

engrt --output json capability authoring-context

Reports everything a human or AI author needs before writing: Runtime version and Home, installed agent/manifest/spec paths and digests, config and policy provenance, configured sources, the exact authoring_source, provider operations, allowed and installed binaries, auth-provider enablement, and File Engine write readiness.

authoring_ready becomes true only when the selected source exists and policy grants writes to it. Runtime never chooses the first configured source or the Home compatibility cache. The command is read-only: it does not authenticate, fetch or clone a repository, run a command, contact a network, mutate a file, or write audit evidence.


engrt capability list

engrt capability list
engrt --output json capability list

Lists every capability this install can resolve: name, winning source, digest of the exact bytes, one-line summary, and declared inputs. --output is the global flag, so it goes before capability.

A fresh contracts-only Home with no configured source returns success and an empty list. That is a correct state — Runtime ships none and fetches none. Text output names capabilities.sources and ENGRT_CAPABILITIES_DIR. JSON is a plain empty array.

<Runtime Home>/capabilities is searched last and labelled a non-authoritative cache. It is never the definition.


Addressing a capability

Both commands accept a path or a name:

Argument Resolution
An existing file path Used exactly as given
Anything else Resolved by name across ordered capabilities.sources, then the implicit cache, tried with and without a .md suffix
# by path — works against any file, anywhere
engrt capability validate ./capabilities/files/notes-roundtrip.md

# by name — works from any working directory
engrt capability validate files/notes-roundtrip

$ENGRT_CAPABILITIES_DIR, when set, names one authoritative capabilities-dir source. Configured capabilities.sources may add an ordered set, with capabilities.authoring_source selecting one when several compete. With neither configured, <Runtime Home>/capabilities is the non-authoritative fallback cache.

An unresolvable argument is passed through unchanged, so the error names what you actually typed rather than some rewritten form of it.


engrt capability validate

engrt capability validate files/notes-roundtrip

Rejects malformed or beyond-budget syntax first, then aggregates admitted documents' semantic problems in stable order:

  • version is missing or unsupported (exactly v1 in v0.9.9)
  • the workflow has no steps
  • a step sets both provider and binary, or neither
  • a step names an unregistered provider
  • a step's args do not resolve to a real operation of that provider
  • a binary step names a binary absent from allowed_binaries
  • an unrecognized key, named with its line number

Validation resolves provider steps against the provider's real operation surface, so a capability naming an operation this Runtime version does not have fails validation rather than mid-execution. ${...} placeholders are probe-substituted first, so unresolved inputs don't confuse operation matching.

What validation does not promise

A capability that validates is well-formed and only references things this Runtime version can run. It can still fail at execution — missing credentials, a denied policy rule, a network error. Validation is a structural guarantee, not a success guarantee.


v0.10.0 additions

v0.10.0 accepts optional capability SemVer and explicit step dependencies. Version and dependency rules describe compatibility and limits. engrt capability plan shows each explicit id and canonical needs list in text and JSON. Step evidence includes the same IDs without arguments or input values in those new fields. Execution remains sequential and globally fail-fast. Released v0.9.9 rejects the new syntax.


Local discovery in v0.10.0

These commands ship in v0.10.0; v0.9.9 does not provide them.

engrt capability search "repository health"
engrt --output json capability inspect github/github-repo-health

Search reads the existing configured local inventory. Every distinct query term must match the relative path/name, title, provider/binary names or input names/descriptions. Matching is case-insensitive and literal. Ranking gives each term 8 points for name/path, 4 for title, 2 for provider/binary and 1 for inputs; each field group contributes once. Ties use source precedence, then relative name. Quote multiword queries; limits are 1,024 UTF-8 bytes and 16 terms.

Inspect selects an existing path first, otherwise the same first-source-wins name as execute. It reports the selected and shadowed sources, title, grammar, optional capability SemVer, required input names, providers/binaries and step count. Legacy version metadata remains absent. Invalid first sources do not fall through to later copies. Definition checks cover grammar, inputs, workflow shape and registered provider operations; installation, execution policy and source trust are not established.

Both commands support text and JSON. Neither authenticates, fetches, executes, changes capability sources/provider state nor writes execution evidence. Normal Runtime Home bootstrap/contract refresh can still occur.

Scans stop at 10,000 candidate files, 1 MiB per file, 64 MiB total read, 100,000 directory entries or 32 nested directories. README files are excluded and directory symlinks are not followed. Search returns the top 100 matches and reports matches_omitted when more matched. Display fields are bounded to 512 code points; shadow lists show 16 sources plus an omitted count. Truncation and recognized-secret redaction are explicit metadata flags. Keep secrets out of metadata; sanitization is not universal secret detection.

A complete no-match search returns an empty list and exit 0. Unreadable or invalid selected files make search incomplete; exhausted scan limits and cancellation return complete: false, reason counts and exit 1. Any returned search matches are partial. Named inspect reads only its winning definition; unrelated malformed files do not invalidate it. Missing/unreadable/invalid requested definitions still fail. Inspect completeness describes that requested capability, not catalog-wide validation. Fix search failures before treating results as a complete inventory. The top-100 output cap alone does not make a full scan incomplete. Arguments, input values and raw parser diagnostics are not reported.


engrt capability plan

engrt capability plan files/notes-roundtrip \
  --input path=./notes.txt --input message=hello
engrt --output json capability plan files/notes-roundtrip \
  --input path=./notes.txt --input message=hello

Plan re-validates the file, checks required inputs, substitutes values, and resolves every step's real provider operation, native context, File Engine grant, compiled safety floor, declarative policy, and direct-binary pin/digest. It reports all denials and exits non-zero if an input is missing or any step is denied.

Planning performs no authentication, process or network execution, mutation, or audit write. File-write payloads and GitHub content values are omitted from the report. Identity allow-list evaluation is explicitly deferred until the separately authorized execution resolves an identity. A successful plan is review evidence, not permission to execute.


engrt capability execute

engrt capability execute files/notes-roundtrip \
  --input path=./notes.txt --input message=hello

engrt capability execute files/estate-config-update \
  --input root=./repos --input old_branch=master \
  --input new_branch=main --input owner=@platform --dry-run

Execution:

  1. Re-validates the capability
  2. Checks every required: true input was supplied
  3. Substitutes ${name} placeholders
  4. Runs each step in order, stopping at the first failure

--dry-run is a capability-wide typed preview. Before step one, Runtime checks the preview contract of every step. Structured File Engine edits are converted to their registered preview form; read-only provider and CLI operations may run normally; a mutating REST, CLI, or legacy File operation without a preview contract refuses the entire workflow. Runtime never guesses that appending a string such as --dry-run makes an arbitrary command safe.

All executed steps in one capability call share a safe run_id in audit. A durable start frame binds the exact source and SHA-256 of the byte snapshot Runtime parsed; every step repeats that identity with step/total, actor, session and execute/preview mode; a terminal frame records the overall result. Structured edit records add batch counts and content-free per-file status/before/after digests. Capabilities are still not transactions: without global preview, an earlier successful step remains executed when a later step fails.

--input key=value

Repeatable, one per input:

engrt capability execute github/repo-health --input repository=cli/cli

From v0.11.0, give each --input exactly once. A repeated key, or an --input without =, refuses as invalid_input (exit 2) before anything is resolved. v0.10.0 silently kept the last value of a repeated key.

In v0.9.9, substitution is single-pass: input values remain opaque and keep their argv boundaries. ${name} must be declared; unknown supplied keys, malformed references and missing/empty required values refuse before any step. An omitted optional input becomes empty, not ${name}. Use $$ for a literal dollar, including $${NAME} or $${{ github.ref }} for downstream templates. See exact limits and literal rules.

Plan and execute each load their own bounded immutable byte snapshot. Execution does not reread it between steps. Evidence adds optional capability_invocation_digest / capability_invocation_key_id for the compiled workflow and mode, distinct from source SHA-256 and unique run ID. Existing v1 evidence without those fields remains readable; they confer no retry authority.

JSON output

engrt --output json capability execute files/notes-roundtrip \
  --input path=./notes.txt --input message=hello

A machine-readable result covering every step. --output is a global flag, so it goes before capability.

v0.9.9 compatibility change: on failure, steps includes both earlier outcomes and the failing step, with its unsuccessful status, error and bounded partial result. Later steps are absent and do not run. Do not count returned entries as successful steps; inspect their status. The top-level error identifies where execution stopped, and Runtime exits 1 (not the native child's exit code). Existing successful step fields remain available.

Command-step results add start/completion/effect observations; malformed or truncated declared JSON is a post-start failure, while valid JSON null remains .data: null. See Command results and cancellation. Neither earlier steps nor partial effects from the failing step are rolled back. Cancellation stops the current command and prevents later dispatch; its evidence is unknown when completion cannot be established. Never replay a capability merely because it exited nonzero. An evidence-write error stays visible without overwriting the actual command result or rerunning it.

Capability results (v0.11.0)

Requires v0.11.0

This describes v0.11.0. Released v0.10.0 exits 1 for every unsuccessful capability run.

The three commands return different JSON results and share one set of exit codes.

Command JSON result Runs anything?
capability validate {path, valid, problems} No
capability plan {path, digest, all_allowed, steps}; each step shows its resolved operation, allowed and decision No: no auth, network, mutation or evidence
capability execute The execution envelope below Yes

Only execute has a run. Its envelope keeps every v0.10.0 field and adds:

  • Run fields: run_id; capability (name, path, version, digest); status and, when unsuccessful, a typed reason; counts (completed, not_required, failed, not_executed).
  • operations: for capabilities that use outputs and verification, one entry per expect step. Each has a verify_step and an outcome:
    • SATISFIED: no change was needed;
    • APPLIED: created, then verified;
    • RECONCILED: corrected drift, then verified;
    • FAILED;
    • NOT_EXECUTED.
  • steps: one entry for every declared step, with index, id, needs and step_status. A step may also carry outputs, an observation, a separate verification and a typed reason.

step_status is one of:

  • success;
  • denied;
  • failure;
  • not_required: its when gate did not hold;
  • not_executed: the run stopped earlier.

step_status is not the operation status

A step that dispatched an operation also keeps that operation's v0.10.0 status. The two can intentionally differ: a successful read whose expectation does not match has operation status: success, step_status: failure and verification.status: failed. Automation should read step_status for the step and the top-level status/reason for the run.

Exit Meaning
0 Success, including a rerun where every operation was already SATISFIED
1 Failure after dispatch: provider_failure, ambiguous_effect, evidence_incomplete, output_contract_violation, conflict, canceled
2 Invalid: invalid_input, unsupported_operation_shape, or invalid usage (a wrong argument count, an unknown flag, a malformed or repeated --input)
3 Refused before dispatch: policy_denied, auth_unavailable, version_mismatch, refused_before_dispatch
4 Verification failed or unavailable: execution happened, but live state was not proven

Precedence rules:

  • Evidence wins. If any required evidence cannot be written, execute reports evidence_incomplete (exit 1). The step keeps its own status, reason and verification as detail.
  • Verification reads. A verification read that was dispatched and failed is verification_unavailable (exit 4). One refused before dispatch keeps its refusal, such as policy_denied (exit 3).
  • Plan. capability plan exits 3 when any step would be denied.
  • Other commands. Direct operations and command run keep exit 0/1.

Capability commands accept --output json before or after their arguments, for example engrt capability execute <name> --input k=v --output json. A trailing --output json is also honored after REST/GraphQL operations and in resolve.


A capability gets no special powers

Every step dispatches through the same Bootstrap → Context → Policy → Auth → Execution → Audit lifecycle as any other command. A capability contributes no execution logic of its own.

Concretely:

  • Each step keeps its own pre-dispatch intent/completion and readable record, including the transport its provider chose. Capability start/completion frames group those effects; they do not replace or weaken per-step evidence.
  • A step denied by policy is denied inside a capability too.
  • Auth is validated per step; there is no session established across a workflow.
  • Execution stops at the first failing step; earlier steps have already run and are already audited. Capabilities are not transactional.

Execution output

Runtime v0.9.9 defaults to cli: capability name, each step's status and concise safe results. Human execution output shares a 16 KiB budget across all steps, with at most the first 19 and last step previewed. Omissions are visible; JSON retains every executed step and complete admitted safe values. Failures retain previous steps and the failing step; later steps do not run. Provider/tool sanitization happens before the capability receives a result, using the same boundary as direct execution.

Overall failure can mean required evidence recording failed after an operation completed. CLI shows execution and evidence separately, without changing any step's status. A step evidence failure stops the run; later steps do not execute. If all steps succeeded but aggregate evidence failed, CLI reports completed steps and failed evidence. Earlier effects are never rolled back automatically.

Use engrt --output json capability execute ... for automation/agents and inspect each step's status, error_code, structured data and execution metadata. CLI formatting is not a parsing API. Deprecated text aliases cli; raw is unavailable for a multi-step capability. See output modes.

Examples

# auth-free — good first smoke test
engrt capability validate capabilities/files/notes-roundtrip.md
engrt capability execute capabilities/files/notes-roundtrip.md \
  --input path=./notes.txt --input message=hello

# from a configured team source, by name
engrt capability execute github/repo-health --input repository=cli/cli

# validate everything in a directory
find ~/work/capabilities -name '*.md' \
  -exec engrt capability validate {} \;

Finding operations to use

A step's args are exactly the words you would type on the command line, split into a list:

On the command line In a capability
engrt files read ./a.txt provider: files, args: [read, ./a.txt]
engrt github repo view cli/cli provider: github, args: [repo, view, cli/cli]
engrt command run gh repo list --limit 10 binary: gh, args: [repo, list, --limit, "10"]

So start by asking the runtime what it can do:

engrt files --help
engrt github --help

When a capability declares capability_version, audit lineage records that exact SemVer as capability_version on capability start/completion, every step intent/completion and ordinary audit records, including preview and failed runs. It comes from the same loaded snapshot as capability_digest; it is an author label, not proof of immutable publication. Missing declarations remain omitted for legacy capabilities. Source and compiled invocation digests keep their existing meanings; declaring a version does not select historical content.

Use engrt --output json audit tail to read capability_version directly from ordinary audit records. Human engrt audit tail also displays the declared revision as capability_version=...; legacy records add no default value.

A well-formed declaration targeting a newer Runtime remains discoverable with compatible: false; compatible definitions report compatible: true. This is separate from valid and scan complete. Search does not hide such matches, and complete empty searches or unrelated valid inspection still exit 0. Invalid syntax/unreadable files still make search incomplete. Named inspect reads only the winning definition and reports its bounded shadows; unrelated malformed files do not invalidate it. A missing, unreadable or invalid requested capability still fails, as do traversal/read limits and cancellation. Inspect completeness is about the requested capability, not validation of the entire catalog. Validation, planning and execution still refuse unmet ranges before effects; discovery grants no permission.

Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.