`runtime capability`¶

runtime capability validate <path|name>
runtime capability execute  <path|name> [--input key=value ...]

For the file format, see the Capability Authoring Reference. For workflow guidance, see Validate & Execute.

Addressing a capability¶

Both commands accept a path or a name:

Argument	Resolution
An existing file path	Used exactly as given
Anything else	Resolved as a name inside the capabilities directory, 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

The capabilities directory is $RUNTIME_CAPABILITIES_DIR when set, otherwise <Runtime Home>/capabilities.

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 execute`¶

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

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

`--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's own audit record is what gets written — including the transport its provider chose.
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 shared team directory, by name
export RUNTIME_CAPABILITIES_DIR=~/work/capabilities
runtime capability execute github/repo-health --input repository=cli/cli

# validate everything in a directory
find "$RUNTIME_CAPABILITIES_DIR" -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 release upload …`	`binary: gh`, `args: [release, upload, …]`

So start by asking the runtime what it can do:

runtime files --help
runtime github --help

runtime capability¶