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¶
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¶
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¶
Rejects malformed or beyond-budget syntax first, then aggregates admitted documents' semantic problems in stable order:
versionis missing or unsupported (exactlyv1in v0.9.9)- the workflow has no steps
- a step sets both
providerandbinary, or neither - a step names an unregistered provider
- a step's
argsdo not resolve to a real operation of that provider - a
binarystep names a binary absent fromallowed_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:
- Re-validates the capability
- Checks every
required: trueinput was supplied - Substitutes
${name}placeholders - 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:
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);statusand, when unsuccessful, a typedreason;counts(completed,not_required,failed,not_executed). operations: for capabilities that use outputs and verification, one entry perexpectstep. Each has averify_stepand anoutcome:SATISFIED: no change was needed;APPLIED: created, then verified;RECONCILED: corrected drift, then verified;FAILED;NOT_EXECUTED.
steps: one entry for every declared step, withindex,id,needsandstep_status. A step may also carryoutputs, anobservation, a separateverificationand a typedreason.
step_status is one of:
success;denied;failure;not_required: itswhengate 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,
executereportsevidence_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 aspolicy_denied(exit 3). - Plan.
capability planexits 3 when any step would be denied. - Other commands. Direct operations and
command runkeep 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:
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.