# Cascade CLI command reference

<!-- generated by scripts/generate-cli-reference.py from docs/guides/cli-capabilities.json; do not edit by hand -->

Every command, flag and MCP tool of `@the-cascade-protocol/cli` **0.27.0**, generated from that release's `cascade --json capabilities` output. The CLI builds that document from its own command and MCP tool registrations, so nothing here is written by hand, and a command is listed here only if the CLI registers it.

- Machine-readable original: [cli-capabilities.json](/docs/guides/cli-capabilities.json). Agents should read it (or run `cascade capabilities`) rather than this page.
- Worked examples and background: [CLI guide](/docs/guides/cli-reference.md).

## Contents

- [Global options](#global-options)
- [Commands](#commands) (45)
  - [cascade validate](#cascade-validate)
  - [cascade convert](#cascade-convert)
  - [cascade reconcile](#cascade-reconcile)
  - [cascade pod](#cascade-pod)
  - [cascade pod init](#cascade-pod-init)
  - [cascade pod query](#cascade-pod-query)
  - [cascade pod export](#cascade-pod-export)
  - [cascade pod info](#cascade-pod-info)
  - [cascade pod profile](#cascade-pod-profile)
  - [cascade pod profile set-name](#cascade-pod-profile-set-name)
  - [cascade pod import](#cascade-pod-import)
  - [cascade pod conflicts](#cascade-pod-conflicts)
  - [cascade pod resolve](#cascade-pod-resolve)
  - [cascade pod extract](#cascade-pod-extract)
  - [cascade pod encrypt](#cascade-pod-encrypt)
  - [cascade pod decrypt](#cascade-pod-decrypt)
  - [cascade pod passphrase](#cascade-pod-passphrase)
  - [cascade pod passphrase set](#cascade-pod-passphrase-set)
  - [cascade pod amend](#cascade-pod-amend)
  - [cascade pod annotate](#cascade-pod-annotate)
  - [cascade pod add-record](#cascade-pod-add-record)
  - [cascade pod retract](#cascade-pod-retract)
  - [cascade pod erase](#cascade-pod-erase)
  - [cascade pod doctor](#cascade-pod-doctor)
  - [cascade pod reconcile](#cascade-pod-reconcile)
  - [cascade sources](#cascade-sources)
  - [cascade sources coverage](#cascade-sources-coverage)
  - [cascade conformance](#cascade-conformance)
  - [cascade conformance run](#cascade-conformance-run)
  - [cascade serve](#cascade-serve)
  - [cascade capabilities](#cascade-capabilities)
  - [cascade advisory](#cascade-advisory)
  - [cascade advisory validate](#cascade-advisory-validate)
  - [cascade advisory apply](#cascade-advisory-apply)
  - [cascade advisory list](#cascade-advisory-list)
  - [cascade advisory revert](#cascade-advisory-revert)
  - [cascade advisory feed](#cascade-advisory-feed)
  - [cascade advisory feed pull](#cascade-advisory-feed-pull)
  - [cascade advisory dry-run](#cascade-advisory-dry-run)
  - [cascade agent](#cascade-agent)
  - [cascade agent serve](#cascade-agent-serve)
  - [cascade agent review](#cascade-agent-review)
  - [cascade agent login](#cascade-agent-login)
  - [cascade agent provider](#cascade-agent-provider)
  - [cascade agent model](#cascade-agent-model)
- [MCP tools](#mcp-tools) (6)
  - [cascade_pod_read](#cascade_pod_read)
  - [cascade_pod_query](#cascade_pod_query)
  - [cascade_validate](#cascade_validate)
  - [cascade_convert](#cascade_convert)
  - [cascade_write](#cascade_write)
  - [cascade_capabilities](#cascade_capabilities)

## Global options

Declared on the root command, not on any subcommand, and accepted in any position: `cascade --json pod query <pod-dir> --all` and `cascade pod query <pod-dir> --all --json` are equivalent. They are listed here once and are NOT repeated in each command below.

| Option | Type | Description |
|---|---|---|
| `--version, -V` | boolean | output the version number |
| `--verbose` | boolean | Verbose output |
| `--json` | boolean | Output results as JSON (machine-readable) |

**Reading the parameter tables.** In tools[].parameters: "required": true means the ARGUMENT PARSER rejects the command without it, and the key is absent otherwise. Absent is not a promise that the command will run: several commands accept a parse-legal invocation and then refuse it, and every one of those states its real requirement in that command's "notes" — read notes before composing a call. "type": "boolean" is a flag that takes no value; "string[]" is a variadic argument. "default" appears only when a default is registered. mcpTools[].parameters state "required" explicitly on every entry.

**Security model.**

- `networkCalls`: none by default — no command contacts a network to validate, convert, query, import or write. Two exceptions, both only when you invoke them: `advisory feed pull` fetches the feed URL you pass it (any host you choose), and `pod extract` posts narrative text to the cascade-agent server at --agent-url (http://127.0.0.1:8765 by default, i.e. your machine). No telemetry, no analytics, no implicit calls.
- `dataStorage`: local filesystem only
- `provenance`: all agent-written data tagged with AIExtracted provenance
- `auditLog`: all MCP operations logged to provenance/audit-log.ttl

## Commands

### cascade validate

Validate Cascade data against SHACL shapes

```
cascade validate <file-or-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `file-or-dir` | string | yes |  | Turtle file or directory to validate |
| `--shapes` | string |  |  | Path to custom SHACL shapes directory |

Examples:

```
cascade validate record.ttl
cascade --json validate ./data/
```

### cascade convert

Convert between health data formats

```
cascade convert [file] [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `file` | string |  |  | Input file (reads from stdin if omitted) |
| `--from` | string | yes |  | Source format (fhir-genomics\|phenopacket\|vrs\|fhir\|clinvar\|c-cda\|vcf\|cascade) |
| `--to` | string | yes |  | Target format (turtle\|jsonld\|fhir\|cascade) |
| `--format` | string |  | `"turtle"` | Output serialization format (turtle\|jsonld) |
| `--source-system` | string |  |  | Tag all records with a source system name (adds cascade:sourceSystem for reconciliation) |
| `--passthrough` | string |  | `"full"` | Passthrough mode for unmapped FHIR types: full (store fhirJson, round-trip supported) or minimal (omit fhirJson, smaller output) |
| `--allow-vrs-hash-mismatch` | boolean |  |  | Accept a VRS Allele whose declared id does not match cascade-cli's simple canonical-form hash. Required for vrs-python-generated alleles (whose recursive-digest canonicalization the CLI does not reproduce). Default: false (strict reject). |
| `--manifest` | string |  |  | Write import manifest JSON alongside output (default: {input}-manifest.json). Only meaningful when --from fhir. |
| `--extract-narratives` | boolean |  |  | Extract narrative text blocks from C-CDA sections and write a JSON sidecar <file>.narratives.json. Only meaningful when --from c-cda. |

Examples:

```
cascade convert patient.json --from fhir --to turtle
cat data.json | cascade convert --from fhir --to turtle
```

### cascade reconcile

Reconcile Cascade RDF from multiple sources into a normalized record set

```
cascade reconcile <files...> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `files` | string[] | yes |  | Cascade Turtle files to reconcile (2 or more) |
| `--output` | string |  |  | Write merged Turtle output to file (default: stdout) |
| `--report` | string |  |  | Write JSON transformation report to file |
| `--trust` | string |  |  | Source trust scores: system1=0.9,system2=0.85 |
| `--lab-tolerance` | string |  | `"0.05"` | Lab value match tolerance as fraction (default: 0.05) |

Examples:

```
cascade reconcile system-a.ttl system-b.ttl --output merged.ttl --report report.json
cascade reconcile vm.ttl swedish.ttl --trust 0.9,0.7 --output merged.ttl
```

### cascade pod

Manage Cascade Pod structures

```
cascade pod <subcommand>
```

Subcommands: [`init`](#cascade-pod-init), [`query`](#cascade-pod-query), [`export`](#cascade-pod-export), [`info`](#cascade-pod-info), [`profile`](#cascade-pod-profile), [`import`](#cascade-pod-import), [`conflicts`](#cascade-pod-conflicts), [`resolve`](#cascade-pod-resolve), [`extract`](#cascade-pod-extract), [`encrypt`](#cascade-pod-encrypt), [`decrypt`](#cascade-pod-decrypt), [`passphrase`](#cascade-pod-passphrase), [`amend`](#cascade-pod-amend), [`annotate`](#cascade-pod-annotate), [`add-record`](#cascade-pod-add-record), [`retract`](#cascade-pod-retract), [`erase`](#cascade-pod-erase), [`doctor`](#cascade-pod-doctor), [`reconcile`](#cascade-pod-reconcile).

### cascade pod init

Initialize a new Cascade Pod

```
cascade pod init <directory> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `directory` | string | yes |  | Directory to initialize as a Cascade Pod |
| `--encrypt` | boolean |  |  | Encrypt pod resources at rest (AES-256-GCM, passphrase-wrapped). Passphrase is read from CASCADE_POD_PASSPHRASE or a hidden prompt. |
| `--owner-name` | string |  |  | Set the pod owner's display name (foaf:name) in profile/card.ttl. |

Examples:

```
cascade pod init ./my-pod
```

### cascade pod query

Query data within a pod

```
cascade pod query <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod |
| `--medications` | boolean |  |  | Query medications |
| `--conditions` | boolean |  |  | Query conditions |
| `--allergies` | boolean |  |  | Query allergies |
| `--lab-results` | boolean |  |  | Query lab results |
| `--immunizations` | boolean |  |  | Query immunizations |
| `--vital-signs` | boolean |  |  | Query vital signs |
| `--supplements` | boolean |  |  | Query supplements |
| `--insurance` | boolean |  |  | Query insurance / coverage plans |
| `--procedures` | boolean |  |  | Query procedures |
| `--encounters` | boolean |  |  | Query encounters |
| `--documents` | boolean |  |  | Query clinical documents |
| `--lab-reports` | boolean |  |  | Query laboratory reports (DiagnosticReport) |
| `--medication-administrations` | boolean |  |  | Query medication administrations |
| `--devices` | boolean |  |  | Query implanted devices |
| `--imaging` | boolean |  |  | Query imaging studies |
| `--claims` | boolean |  |  | Query insurance claims |
| `--benefits` | boolean |  |  | Query explanation of benefits |
| `--fhir-passthrough` | boolean |  |  | Query FHIR passthrough records (unmapped types) |
| `--all` | boolean |  |  | Query all data |
| `--neighbors` | string |  |  | Return the typed neighborhood of a record (traverses stored edges both directions) |
| `--hops` | string |  |  | Traversal depth for --neighbors (default 1, capped at 3) |
| `--edge` | string |  |  | Restrict --neighbors traversal to this edge predicate (repeatable; full IRI or prefix:local CURIE) |
| `--edges` | boolean |  |  | With --all, add a record-to-record edge projection to the output |
| `--exclude-data-type` | string |  |  | Leave out one data type: its file is never read, decrypted or parsed, by the record sweep, --edges or --neighbors (repeatable). A key is a data type (heart-rate, sleep, ...), wellness-samples (the retained-sample descriptors), or wellness: every file under wellness/ except supplements, plus wellness-samples, the cheap way to ask a clinical question. A key excludes its whole FILE: heart-rate and wellness also drop health:VitalSignReading records coded with a heart-rate LOINC code, clinical ones included; body-measurements and wellness drop VO2 max; wellness keeps supplements. An unknown key is a usage error that lists the keys |
| `--wellness-series` | boolean |  |  | Add the pod's stored daily wellness series (one reading per reading type, statistic and local day, chosen by source priority, each citing its record) and its per-source summary, under `wellnessDailySeries` (null when the pod holds none). Reads one small file and hashes (never parses) the files it was built from: a series they no longer match comes back with `stale: true` and the reasons. Alone, or beside any filter except --neighbors |
| `--include-bookkeeping` | boolean |  |  | Also return the pod's own bookkeeping subjects (cascade:PendingConflict, cascade:UserResolution, solid:TypeIndex, solid:TypeRegistration, pim:ConfigurationFile). These are notes ABOUT records, not records, and are excluded by default; ask for them when building a conflict queue |

Examples:

```
cascade pod query ./my-pod --medications --json
cascade pod query ./my-pod --encounters --conditions --json
cascade pod query ./my-pod --all --json
cascade pod query ./my-pod --all --exclude-data-type wellness --wellness-series --json
```

Output schema (`--json`):

```json
{
  "description": "JSON output structure for --json flag",
  "shape": "{ pod: string, dataTypes: { [type]: { count: number, file: string, records: Record[] } } }",
  "recordShape": "{ id: string, type: string, properties: { [prefixed-property]: string } }",
  "propertyPrefixes": {
    "health:": "wellness/device data — health:testName, health:resultValue, health:resultUnit, health:performedDate, health:testCode (LOINC URI), health:conditionName, health:conditionCategory (FHIR category: problem-list-item|encounter-diagnosis|social-history), health:snomedSemanticTag (semantic type from SNOMED display name: disorder|finding|situation|procedure|observable entity), health:status (active/inactive/resolved), health:onsetDate, health:medicationName, health:isActive (true/false string), health:rxNormCode",
    "clinical:": "EHR-imported clinical data — clinical:encounterDate, clinical:encounterType, clinical:procedureName, clinical:procedureDate, clinical:drugCode, clinical:clinicalIntent",
    "core:": "provenance — core:sourceSystem, core:dataProvenance, core:schemaVersion, core:reconciliationStatus, core:mergedSources"
  },
  "jqExamples": [
    "# Clinical conditions only (excludes social findings): cascade pod query <pod> --conditions --json | jq '[.dataTypes.conditions.records[] | select(.properties[\"health:status\"] == \"active\" and .properties[\"health:snomedSemanticTag\"] == \"disorder\") | .properties[\"health:conditionName\"]]'",
    "# All active conditions including findings: cascade pod query <pod> --conditions --json | jq '[.dataTypes.conditions.records[] | select(.properties[\"health:status\"] == \"active\") | {name: .properties[\"health:conditionName\"], type: .properties[\"health:snomedSemanticTag\"]}]'",
    "# HbA1c trend (most recent first): cascade pod query <pod> --lab-results --json | jq '[.dataTypes[\"lab-results\"].records[] | select(.properties[\"health:testName\"] | ascii_downcase | test(\"a1c\")) | {date: .properties[\"health:performedDate\"], value: .properties[\"health:resultValue\"], unit: .properties[\"health:resultUnit\"]}] | sort_by(.date) | reverse'",
    "# Active medications: cascade pod query <pod> --medications --json | jq '[.dataTypes.medications.records[] | select(.properties[\"health:isActive\"] == \"true\") | .properties[\"health:medicationName\"]]'",
    "# Medications with source provenance: cascade pod query <pod> --medications --json | jq '[.dataTypes.medications.records[] | {name: .properties[\"health:medicationName\"], active: .properties[\"health:isActive\"], sources: .properties[\"core:mergedSources\"]}]'"
  ],
  "shellQuotingNote": "Always pipe pod query output through jq rather than reading raw JSON (output can be very large). Use [\"key\"] bracket notation in jq filters to avoid shell quoting issues. If a filter is complex, write it to /tmp/filter.jq and run: cascade pod query <pod> --TYPE --json | jq -f /tmp/filter.jq"
}
```

### cascade pod export

Export pod data

```
cascade pod export <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod |
| `--format` | string |  | `"zip"` | Export format (zip\|directory) |
| `--output` | string |  |  | Output path for export |
| `--allow-encrypted` | boolean |  |  | Export an encrypted pod as ciphertext (the export is stamped with a note explaining it) |

Notes:

- Conditional refusal, enforced at run time: against an ENCRYPTED pod this exits 1 unless --allow-encrypted is passed, because the archive would otherwise contain ciphertext that looks like a working export. Decrypt the pod first, or pass the flag to export the sealed bytes deliberately — an export made that way carries a README explaining what the files are.

Examples:

```
cascade pod export ./my-pod
cascade pod export ./my-pod --format directory
```

### cascade pod info

Show pod metadata and statistics

```
cascade pod info <pod-dir>
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod |

Examples:

```
cascade pod info ./my-pod
cascade --json pod info ./my-pod
```

### cascade pod profile

Manage a pod owner's profile identity

```
cascade pod profile <subcommand>
```

Subcommands: [`set-name`](#cascade-pod-profile-set-name).

### cascade pod profile set-name

Set the pod owner's display name (foaf:name) in profile/card.ttl

```
cascade pod profile set-name <dir> <name>
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `dir` | string | yes |  | Path to the Cascade Pod |
| `name` | string | yes |  | Owner display name (e.g. "Jane Doe") |

### cascade pod import

Import FHIR JSON or Cascade Turtle files into a pod

```
cascade pod import <pod-dir> <files...> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `files` | string[] | yes |  | Files or folders to import (FHIR JSON, Cascade Turtle, C-CDA XML/zip, or a folder / Apple Health export) |
| `--source-system` | string |  |  | Tag all imported records with this system name |
| `--no-reconcile` | boolean |  |  | Skip reconciliation even when importing multiple files |
| `--reconcile-existing` | boolean |  | `true` | Include existing pod records in reconciliation pass (cross-batch dedup, on by default; disable with --no-reconcile-existing) |
| `--no-reconcile-existing` | boolean |  |  | Skip loading existing pod records (additive import only) |
| `--trust` | string |  |  | Trust scores e.g. hospital=0.95,clinic=0.85 |
| `--dry-run` | boolean |  |  | Preview the import without writing any files |
| `--report` | string |  |  | Write import report JSON to this file |
| `--passthrough` | string |  | `"full"` | Passthrough mode: full or minimal (default: full) |

Examples:

```
cascade pod import ./my-pod patient.json --source-system "Virginia Mason"
cascade pod import ./my-pod vm.json swedish.json --source-system "primary,specialist" --report report.json
cascade pod import ./my-pod records.ttl --no-reconcile
```

### cascade pod conflicts

List unresolved conflicts in a pod (--resolved for the decision log)

```
cascade pod conflicts <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `--format` | string |  | `"text"` | Output format: text or json |
| `--resolved` | boolean |  |  | List recorded decisions instead of the unanswered queue |

### cascade pod resolve

Record a conflict resolution decision in the pod (carried out by the next pod reconcile --apply)

```
cascade pod resolve <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `--conflict` | string | yes |  | Conflict ID to resolve (from cascade pod conflicts) |
| `--keep` | string | yes |  | Which source to keep: source-a, source-b, both |
| `--note` | string |  |  | Optional note about your decision |
| `--by` | string |  |  | Optional actor IRI (prov:wasAttributedTo) |

### cascade pod extract

Send narrative text from imported C-CDA records to cascade-agent for AI extraction

```
cascade pod extract <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  |  |
| `--agent-url` | string |  | `"http://127.0.0.1:8765"` | cascade-agent base URL |
| `--dry-run` | boolean |  |  | Show what would be extracted without calling the agent |
| `--section` | string |  |  | Only extract a specific section (medications\|conditions\|labResults\|...) |

### cascade pod encrypt

Encrypt an existing plaintext pod at rest (AES-256-GCM)

```
cascade pod encrypt <dir>
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `dir` | string | yes |  | Path to the Cascade Pod directory |

### cascade pod decrypt

Decrypt an encrypted pod back to plaintext at rest

```
cascade pod decrypt <dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `dir` | string | yes |  | Path to the Cascade Pod directory |
| `--force` | boolean |  |  | Proceed even when some files cannot be decrypted with this pod key. They are LEFT UNCHANGED and the encryption manifest is still removed. |

### cascade pod passphrase

Manage the passphrase that opens an encrypted pod

```
cascade pod passphrase <subcommand>
```

Subcommands: [`set`](#cascade-pod-passphrase-set).

### cascade pod passphrase set

Change the passphrase of an encrypted pod by re-wrapping its key. A copy of the pod made before the change still opens with the old passphrase.

```
cascade pod passphrase set <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the encrypted Cascade Pod directory |
| `--rotate-dek` | boolean |  |  | Also replace the data key: re-encrypt every file under a new key and keep only the new passphrase |

### cascade pod amend

Override one property value on a record via an append-only Amendment overlay

```
cascade pod amend <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `--record` | string | yes |  | IRI of the record to amend |
| `--property` | string | yes |  | Predicate CURIE being overridden, e.g. clinical:dosage |
| `--value` | string | yes |  | The new value that supersedes the original |
| `--reason` | string |  |  | Optional rationale for the amendment |
| `--by` | string |  |  | Optional actor IRI (prov:wasAttributedTo) |

### cascade pod annotate

Add a note or extra attribute to a record via an append-only Annotation overlay

```
cascade pod annotate <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `--record` | string | yes |  | IRI of the record to annotate |
| `--text` | string |  |  | Free-text note to attach to the record |
| `--property` | string |  |  | Predicate CURIE of an extra attribute (paired with --value) |
| `--value` | string |  |  | Value of the extra attribute named by --property |
| `--by` | string |  |  | Optional actor IRI (prov:wasAttributedTo) |

Notes:

- Enforced at run time, not by the parser: the annotation needs content. Pass --text, or --property together with --value. With neither, the command exits 1 with "Provide at least one of --text or --value (with --property)."

### cascade pod add-record

Add a new self-reported record to its canonical bucket file

```
cascade pod add-record <pod-dir> [propsJson] [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `propsJson` | string |  |  | JSON object of { "<curie>": "<value>" } properties |
| `--type` | string | yes |  | rdf:type CURIE of the new record, e.g. clinical:Medication |
| `--by` | string |  |  | Optional actor IRI (prov:wasAttributedTo) |

Notes:

- Enforced at run time, not by the parser: the record properties are mandatory. Pass them as the propsJson positional argument — a JSON object of { "<curie>": "<value>" } — or set CASCADE_RECORD_JSON, which is the better route for a large payload. With neither, the command exits 1 with "No properties provided."
- --type takes a CURIE whose prefix is one of cascade/core, health, clinical, coverage, checkup, pots, workbench, fhir, and whose class must map to a known bucket file (e.g. health:ConditionRecord, clinical:Medication). An unmapped type is refused rather than guessed.
- The record is written as cascade:SelfReported and workbench:Unverified, attributed to --by if given and otherwise to the pod owner's WebID.
- Property values are given as strings, and each is written as the datatype the bundled SHACL shapes declare for that property: a checkup:supplementIsActive of "true" becomes an xsd:boolean, a checkup:supplementStartDate an xsd:date, a checkup:patientCost an xsd:decimal. A property no shape declares stays a plain string literal. A value that cannot be its declared datatype (a boolean given as "maybe", a date given as "2026-02-30") is refused and nothing is written.

Examples:

```
cascade pod add-record ./my-pod '{"health:conditionName":"Iron deficiency","health:status":"active"}' --type health:ConditionRecord
CASCADE_RECORD_JSON='{"health:medicationName":"Aspirin"}' cascade pod add-record ./my-pod --type clinical:Medication
```

### cascade pod retract

Soft-delete / supersede a record via an append-only Retraction overlay

```
cascade pod retract <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `--record` | string | yes |  | IRI of the record to retract |
| `--reason` | string |  |  | Optional rationale (e.g. "entered in error") |
| `--superseded-by` | string |  |  | Optional IRI of the kept record when merging duplicates |
| `--by` | string |  |  | Optional actor IRI (prov:wasAttributedTo) |

### cascade pod erase

Hard-delete a record from its bucket file and write a Tombstone audit marker

```
cascade pod erase <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `--record` | string | yes |  | IRI of a record to erase (repeatable: several records are erased in one command, and the stored daily wellness series is rebuilt once, after the last) |
| `--confirm` | boolean |  |  | Required confirmation for the destructive hard delete |
| `--reason` | string |  |  | Optional rationale for the erasure |
| `--by` | string |  |  | Optional actor IRI (prov:wasAttributedTo) |

Notes:

- Destructive and not reversible: the record bytes are removed from the bucket file. --confirm is mandatory, and a Tombstone audit marker is written in the record's place.
- For a reversible removal that keeps history, use `pod retract`, which appends a Retraction overlay instead of deleting.

### cascade pod doctor

Diagnose a damaged Cascade Pod and, with --write, repair files whose only defect is a missing @prefix declaration. This is the recovery path when add-record, erase or import refuse a bucket that will not parse. Dry run by default; only ever PREPENDS declarations, never rewrites existing bytes; never invents a namespace.

```
cascade pod doctor <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `--write` | boolean |  |  | Apply the repairs. Without this nothing is modified. |

Examples:

```
cascade pod doctor ./my-pod
cascade pod doctor ./my-pod --write
cascade --json pod doctor ./my-pod
```

Output schema (`--json`):

```json
{
  "description": "JSON report structure for --json",
  "shape": "{ pod, encrypted, mode: \"dry-run\"|\"write\", scanned, healthy, repaired, repairable, refused, unreadable, findings: Finding[] }",
  "findingShape": "{ file, status: \"repairable\"|\"repaired\"|\"refused\"|\"unreadable\", damage, reason, nextStep?, missingPrefixes?, triples?, preservedBytes?, backup? }",
  "exitCodes": "0 = nothing wrong or everything repaired; 1 = damage remains (or no pod at that path); 2 = the pod could not be opened"
}
```

### cascade pod reconcile

Find (and with --apply, merge) duplicates a pod ALREADY holds. Dry run by default.

```
cascade pod reconcile <pod-dir> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod directory |
| `--apply` | boolean |  |  | Actually merge and write. Without this the command only reports what it would do. |
| `--undo` | boolean |  |  | Replay settings/tier0-merge-journal.json and put the silently merged records back. Reports by default; combine with --apply to write. |
| `--trust` | string |  |  | Trust scores, e.g. hospital=0.95,clinic=0.85 |
| `--report` | string |  |  | Write the full report as JSON to this file |

### cascade sources

Inspect the raw source documents a pod retained at import

```
cascade sources <subcommand>
```

Subcommands: [`coverage`](#cascade-sources-coverage).

### cascade sources coverage

Report which populated source fields the import did not carry into the pod

```
cascade sources coverage <pod-dir>
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `pod-dir` | string | yes |  | Path to the Cascade Pod |

### cascade conformance

Run conformance test suite

```
cascade conformance <subcommand>
```

Subcommands: [`run`](#cascade-conformance-run).

### cascade conformance run

Execute conformance tests

```
cascade conformance run [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `--suite` | string | yes |  | Path to test fixtures directory |
| `--command` | string |  |  | External command to test against |
| `--self` | boolean |  |  | Run self-conformance tests |

Notes:

- Enforced at run time, not by the parser: exactly one mode must be chosen. Without --self or --command the command exits 1 with "Either --command or --self must be specified".

Examples:

```
cascade conformance run --suite ./fixtures --self
```

### cascade serve

Start the local MCP (Model Context Protocol) server, exposing the cascade_* tools listed under mcpTools to an MCP client such as Claude Desktop or Claude Code. Serves over stdio by default, or SSE on a port. Requires --mcp.

```
cascade serve [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `--mcp` | boolean |  |  | Enable MCP (Model Context Protocol) mode |
| `--transport` | string |  | `"stdio"` | Transport type (stdio\|sse) |
| `--port` | string |  | `"3000"` | Port for SSE transport |
| `--pod` | string |  |  | Default Pod directory path |

Notes:

- Enforced at run time, not by the parser: --mcp is mandatory in practice. `cascade serve` on its own exits 1 with "The --mcp flag is required." There is no non-MCP server mode.

Examples:

```
cascade serve --mcp
cascade serve --mcp --transport sse --port 3000
```

### cascade capabilities

Show machine-readable tool descriptions

```
cascade capabilities
```

Examples:

```
cascade capabilities
```

### cascade advisory

Cascade Advisory Patch (CAP) — validate, apply, list, revert, feed, dry-run

```
cascade advisory <subcommand>
```

Subcommands: [`validate`](#cascade-advisory-validate), [`apply`](#cascade-advisory-apply), [`list`](#cascade-advisory-list), [`revert`](#cascade-advisory-revert), [`feed`](#cascade-advisory-feed), [`dry-run`](#cascade-advisory-dry-run).

### cascade advisory validate

Parse + profile-validate a CAP advisory (.ldpatch). No pod mutation.

```
cascade advisory validate <patch>
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `patch` | string | yes |  | Path to the .ldpatch advisory file |

### cascade advisory apply

Verify JWS, evaluate selector, apply CAP advisory to a pod

```
cascade advisory apply <patch> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `patch` | string | yes |  | Path to the .ldpatch advisory file |
| `--pod` | string | yes |  | Pod directory |
| `--signature` | string | yes |  | Path to the detached JWS file (header..signature) |
| `--key` | string |  |  | Trusted issuer Ed25519 public key as hex (32 bytes). Repeatable for key rotation. |

### cascade advisory list

List CAP advisories cached in a pod, optionally filtered by status

```
cascade advisory list [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `--pod` | string | yes |  | Pod directory |
| `--pending` | boolean |  |  | Show only pending advisories |
| `--applied` | boolean |  |  | Show only applied advisories |
| `--declined` | boolean |  |  | Show only declined advisories |

### cascade advisory revert

Roll back a previously-applied CAP advisory using its activity log

```
cascade advisory revert [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `--pod` | string | yes |  | Pod directory |
| `--advisory` | string | yes |  | Advisory IRI to revert |

### cascade advisory feed

Manage advisory feeds

```
cascade advisory feed <subcommand>
```

Subcommands: [`pull`](#cascade-advisory-feed-pull).

### cascade advisory feed pull

Pull an advisory feed and cache new entries

```
cascade advisory feed pull <url> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string | yes |  | Feed URL (typically <issuer>/feed.jsonld) |
| `--pod` | string | yes |  | Pod directory |

### cascade advisory dry-run

Apply a CAP advisory to a clone of the pod and print the would-be triples

```
cascade advisory dry-run <patch> [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `patch` | string | yes |  | Path to the .ldpatch advisory file |
| `--pod` | string | yes |  | Pod directory |

### cascade agent

Natural language interface for Cascade Protocol operations

```
cascade agent [prompt] [options]
```

Subcommands: [`serve`](#cascade-agent-serve), [`review`](#cascade-agent-review), [`login`](#cascade-agent-login), [`provider`](#cascade-agent-provider), [`model`](#cascade-agent-model).

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `prompt` | string |  |  | One-shot prompt (omit for interactive REPL) |
| `--provider, -p` | string |  |  | Provider to use for this run |
| `--model, -m` | string |  |  | Model override for this run |

### cascade agent serve

Start the document intelligence extraction server (POST /extract)

```
cascade agent serve [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `--port` | string |  | `"8765"` | Port to listen on |
| `--web-review` | boolean |  |  | Serve the web review UI |

### cascade agent review

Interactive terminal review of AI extraction queue

```
cascade agent review [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `--pod` | string |  |  | Path to the Cascade pod directory |
| `--output` | string |  |  | Path to write review results JSON |

### cascade agent login

Add or update credentials for a provider

```
cascade agent login [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `--provider, -p` | string |  |  | Provider to configure |

### cascade agent provider

Get or set the active provider

```
cascade agent provider [name]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | string |  |  |  |

### cascade agent model

Get or set the model for the active provider

```
cascade agent model [name] [options]
```

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `name` | string |  |  |  |
| `--provider, -p` | string |  |  | Provider to configure |

## MCP tools

Served by `cascade serve --mcp`. Each tool's parameters are read from its registered schema.

### cascade_pod_read

Read a Cascade Pod and return a JSON summary of all contents including patient profile, record counts, provenance sources, and data inventory.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `path` | string | no | Path to the Pod directory. Uses CASCADE_POD_PATH if omitted. |

Returns: JSON with patient profile, record counts, provenance sources.

CLI equivalent: `cascade pod info <pod-dir> --json`

### cascade_pod_query

Query records from a Cascade Pod by data type. Returns JSON array of matching records with their properties and provenance. A pod with wellness data is large: for a clinical question use excludeDataTypes: ["wellness"]; for a wellness question read wellnessSeries (one small file) rather than the wellness records.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `path` | string | no | Path to the Pod directory. Uses CASCADE_POD_PATH if omitted. |
| `dataType` | string | no | Data type to query, or "all" for everything. Optional when wellnessSeries is true. One of: `medications`, `conditions`, `allergies`, `lab-results`, `immunizations`, `vital-signs`, `supplements`, `insurance`, `patient-profile`, `heart-rate`, `blood-pressure`, `activity`, `sleep`, `all`. |
| `excludeDataTypes` | array | no | Data types whose files are never read (keys as for `pod query --exclude-data-type`). "wellness" = every wellness/ file plus the retained-sample descriptors; it also drops supplements, heart-rate vital signs (clinical ones included) and VO2 max, which share those files. |
| `wellnessSeries` | boolean | no | Add wellnessDailySeries: one reading per type, statistic and day, each citing its record, with stale and staleReasons (stale: true means rebuild with `pod reconcile --apply`). Null when the pod has none. |

Returns: JSON array of matching records with properties.

CLI equivalent: `cascade pod query <pod-dir> --medications --json`

### cascade_validate

Validate Cascade Protocol Turtle data against SHACL shapes. Accepts either a file/directory path or inline Turtle content.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `path` | string | no | Path to a Turtle file or directory to validate. |
| `content` | string | no | Inline Turtle content to validate (alternative to path). |

Returns: Validation results with pass/fail per constraint.

CLI equivalent: `cascade validate <file-or-dir> --json`

### cascade_convert

Convert between health data formats. Supports FHIR R4 JSON to Cascade Turtle/JSON-LD and vice versa.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `content` | string | yes | The content to convert (FHIR JSON string or Cascade Turtle string). |
| `from` | string | yes | Source format. One of: `fhir`, `cascade`. |
| `to` | string | yes | Target format. One of: `cascade`, `fhir`. |
| `format` | string | no | Output serialization format when converting to Cascade. Default: turtle. One of: `turtle`, `jsonld`. |

Returns: Converted output.

CLI equivalent: `cascade convert --from fhir --to cascade <file>`

### cascade_write

Write a health record to a Cascade Pod with AIExtracted provenance. The record is serialized as Turtle and appended to the appropriate file in the Pod.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `path` | string | no | Path to the Pod directory. Uses CASCADE_POD_PATH if omitted. |
| `dataType` | string | yes | Type of health record to write. One of: `medications`, `conditions`, `allergies`, `lab-results`, `immunizations`, `vital-signs`, `supplements`. |
| `record` | object | yes | JSON object with record fields (e.g., { "name": "Aspirin", "dose": "81 mg" }). |
| `provenance` | object | no | Provenance metadata for the written record. Fields: `agentId` string (optional) — Identifier of the AI agent writing the data.; `reason` string (optional) — Reason for creating this record.; `confidence` number (optional) — Agent confidence level (0.0-1.0).; `sourceRecords` array (optional) — URIs of source records used to derive this data.. |

Returns: Record URI, file path, provenance metadata.

### cascade_capabilities

Describe all available Cascade Protocol MCP tools, their parameters, and usage examples. Use this as the entry point for discovering what the server can do.

No parameters.

Returns: This capabilities document.

<!-- end of generated reference: 45 commands, 6 MCP tools -->