`runtime capability`¶

runtime capability list
runtime capability authoring-context
runtime capability validate <path|name>
runtime capability plan     <path|name> [--input key=value ...]
runtime 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.

`runtime capability authoring-context`¶

runtime --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.

`runtime capability list`¶

runtime capability list
runtime --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 RUNTIME_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
runtime capability validate ./capabilities/files/notes-roundtrip.md

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

$RUNTIME_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.

`runtime capability validate`¶

runtime capability validate files/notes-roundtrip

Reports every problem it finds, not just the first:

version is missing
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.

`runtime capability plan`¶

runtime capability plan files/notes-roundtrip \
  --input path=./notes.txt --input message=hello
runtime --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.

`runtime capability execute`¶

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

runtime 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: true input 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:

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

Substitution is literal text replacement. An input you declare but do not supply stays in the arguments as the literal string ${name} — which is why the shipped examples mark everything required: true.

JSON output¶

runtime --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.

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.

Examples¶

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

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

# validate everything in a directory
find ~/work/capabilities -name '*.md' \
  -exec runtime 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
`runtime files read ./a.txt`	`provider: files`, `args: [read, ./a.txt]`
`runtime github repo view cli/cli`	`provider: github`, `args: [repo, view, cli/cli]`
`runtime command run gh repo list --limit 10`	`binary: gh`, `args: [repo, list, --limit, "10"]`

So start by asking the runtime what it can do:

runtime files --help
runtime github --help

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

runtime capability¶

runtime capability authoring-context¶

runtime capability list¶