> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doppels.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Validate and Run Capabilities with the Doppels CLI
> Use doppels validate to check your manifests and doppels run to execute a Capability locally with full audit trail under .doppels/runs/.
Once you have Capabilities and Recipes in your project — whether you froze them with an agent or wrote them by hand — the `doppels` CLI is how you verify and execute them. `doppels validate` checks your manifests against the schema and catches problems before they surface at runtime. `doppels run` executes a Capability locally on your machine, producing a complete audit trail in `.doppels/runs/`. Every run is deterministic: same inputs, same steps, auditable result.
## Validate your manifests
Run `doppels validate` from your project root to check all manifests under the standard discovery paths. It validates against the JSON Schema contracts, checks that every Recipe's `provides` list references a real Capability, verifies expression syntax, confirms step order is consistent, checks that `approval` is set on every step, and confirms that `returns` covers all outputs declared by the Capability.
```shell theme={null}
doppels validate
```
When validation passes, you'll see a summary like:
```text theme={null}
✓ Recipe valid · 7 steps
```
When there are errors, the output includes the file path, line number, and a description of the problem — enough to go straight to the issue without searching.
Run `doppels validate` before every commit. It catches schema drift, broken Capability–Recipe references, and expression errors that would only appear at runtime otherwise.
## Run a Capability
Execute a Capability by name with `doppels run capability/`. Pass inputs as `--input key=value` pairs. You can repeat the flag for multiple inputs.
```shell theme={null}
doppels run capability/greet --input name=Ada --yes
```
The `--yes` flag skips approval prompts. Use it in CI pipelines or any context where you've already reviewed the steps and trust the execution. Without `--yes`, the CLI pauses at every step that has `approval: local` or `approval: always` set and waits for your confirmation before proceeding.
```shell theme={null}
# Without --yes: CLI pauses at approval steps
doppels run capability/greet --input name=Ada
# With multiple inputs
doppels run capability/release-pipeline \
--input version=1.4.0 \
--input environment=staging \
--yes
```
Use `--yes` in CI and omit it in local development when you want to step through approvals manually. Approval settings are declared in the Recipe itself — check `defaults.approval` and per-step `approval` fields to understand what will pause.
## Inspect run history
Every run is recorded under `.doppels/runs//` with inputs, step outputs, artifacts, and timestamps. Use the `runs` subcommands to browse and inspect that history.
**List all runs:**
```shell theme={null}
doppels runs list
```
**Show the summary for a specific run:**
```shell theme={null}
doppels runs show
```
**Stream the full logs for a run:**
```shell theme={null}
doppels runs logs
```
Each run record contains everything you need to understand what happened: which inputs were passed, what each step produced, any artifacts captured, and when each step started and finished.
## Describe a Capability
To see the public contract for a Capability without running it, use `doppels describe`:
```shell theme={null}
doppels describe capability/greet
```
This prints the Capability's inputs (names, types, required flags) and outputs (names and types) — the same information a caller needs to invoke it. Useful for inspecting a Capability you're about to run or for checking what a Recipe is expected to return.
## List all Capabilities
To see every Capability discovered in your current Space:
```shell theme={null}
doppels capabilities list
```
## Machine-readable output
Add `--json` to most commands to get structured output suitable for piping into other tools or scripts:
```shell theme={null}
doppels capabilities list --json
doppels runs list --json
doppels runs show --json
doppels describe capability/greet --json
```
## Full example session
The following walkthrough starts from the quickstart example included in the repository and exercises the full CLI workflow from validation through run inspection.
Create the standard directory layout in your project. This writes `capabilities/`, `recipes/`, and `.doppels/`.
```shell theme={null}
doppels spaces init
```
Check all discovered manifests before running anything. Fix any errors reported before moving on.
```shell theme={null}
doppels validate
```
Expected output when everything is clean:
```text theme={null}
✓ Recipe valid · 2 steps
```
Inspect the contract for the `greet` Capability to confirm the inputs and outputs before running.
```shell theme={null}
doppels describe capability/greet
```
Output:
```text theme={null}
Capability: greet v1.0.0
Inputs:
name string required
Outputs:
message string
```
Execute `greet` with a single input. The `--yes` flag skips any approval prompts.
```shell theme={null}
doppels run capability/greet --input name=Ada --yes
```
Output:
```text theme={null}
→ Validating Recipe
→ Running Steps on your Node
✓ Done · 0 tokens
```
Confirm the run was recorded.
```shell theme={null}
doppels runs list
```
Output:
```text theme={null}
RUN ID CAPABILITY STATUS STARTED
run_01jz... greet succeeded 2025-08-17T14:03:22Z
```
Pull up the full detail for that run, including the output value.
```shell theme={null}
doppels runs show run_01jz...
```
Stream the step-level logs for the run.
```shell theme={null}
doppels runs logs run_01jz...
```