# Cascade CLI Reference

**Version:** 1.3
**Date:** 2026-04-08
**Status:** Current
**Organization:** Cascade Agentic Labs LLC

---

## Table of Contents

1. [Overview](#1-overview)
2. [Commands](#2-commands)
   - [cascade convert](#cascade-convert)
   - [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 agent](#cascade-agent)
3. [Exit Codes](#3-exit-codes)

---

## 1. Overview

The `cascade` CLI is the primary developer tool for working with Cascade Protocol data. It handles conversion from external health record formats, Pod management, and conflict resolution. All operations are local — no network calls are made during conversion or Pod operations.

---

## 2. Commands

### cascade convert

Convert an external health record format to Cascade Protocol Turtle.

#### C-CDA conversion

```
cascade convert --from c-cda <file.xml|file.zip> [--source-system <name>]
```

Converts a C-CDA R2.1 XML document or an IHE XDM ZIP bundle to Cascade Protocol Turtle, writing to stdout.

**Arguments**

| Argument | Required | Description |
|----------|----------|-------------|
| `<file>` | Yes | Path to a `.xml` C-CDA document or `.zip` IHE XDM bundle |
| `--from c-cda` | Yes | Specifies the input format |
| `--source-system <name>` | No | Tags all output records with this system name for later reconciliation |
| `--extract-narratives` | No | Extract unstructured clinical narrative sections and flag them for LLM extraction (`cascade:requiresLLMExtraction = "true"`) |

**Supported input formats**

| Format | Description |
|--------|-------------|
| C-CDA R2.1 XML | Continuity of Care Document and other C-CDA document types. Supports `--extract-narratives` to flag unstructured sections for AI extraction. |
| IHE XDM ZIP | Cross-Enterprise Document Media Interchange bundles (e.g., MyChart download ZIPs containing multiple C-CDA documents). Supports `--extract-narratives` to extract narrative sections from all contained documents. |

**Supported EHR systems**

The converter auto-detects the source EHR from the `<custodian>` element in the C-CDA header. The following systems are recognized and handled with vendor-specific normalization:

| Vendor | Detection |
|--------|-----------|
| Epic MyChart | Detected from custodian name |
| Cerner PowerChart | Detected from custodian name |

Records from unrecognized systems are still converted using standard C-CDA parsing; auto-detection only affects vendor-specific normalization quirks.

**Preserved terminology codes**

The converter preserves all standard terminology codes present in the source document. The following code systems are recognized and passed through to the output Turtle:

- **CVX** — Vaccine codes (immunizations)
- **LOINC** — Lab result codes and vital sign codes
- **SNOMED CT** — Condition and procedure codes
- **RxNorm** — Medication codes
- **ICD-10-CM** — Diagnosis codes
- **Reference ranges** — Lab result reference intervals from the source document

**RxNorm ingredient lookup:** When a C-CDA medication entry omits `displayName` (common in Epic exports), the converter falls back to a bundled RxNorm ingredient lookup using the entry's RxNorm code. This ensures all medication records have a drug name.

**Output**

Cascade Protocol Turtle is written to stdout. Redirect to a file or pipe directly into `cascade pod import`:

```bash
# Write to a file
cascade convert --from c-cda epic-export.zip > pod/epic.ttl

# Pipe directly into a Pod
cascade convert --from c-cda epic-export.xml | cascade pod import ./my-pod -
```

**Example**

```bash
cascade convert --from c-cda MyChart-export.zip \
  --source-system "epic-mychart" \
  > pod/source-epic.ttl
```

---

### cascade pod import

Import a Cascade Turtle file into a Pod, splitting records by type and updating the Pod's type index.

```
cascade pod import <pod-dir> <file.ttl> [--reconcile-existing] [--source-system <name>] [--dry-run]
```

**Arguments**

| Argument | Required | Description |
|----------|----------|-------------|
| `<pod-dir>` | Yes | Path to an initialized Pod directory |
| `<file.ttl>` | Yes | Path to a Cascade Protocol Turtle file, or `-` to read from stdin |
| `--reconcile-existing` | No | Load existing Pod records as a deduplication baseline before processing the new import |
| `--source-system <name>` | No | Override the source system tag for all imported records |
| `--dry-run` | No | Preview what would be written without making any changes |

**The `--reconcile-existing` flag**

By default, `cascade pod import` appends records from the input file to the Pod, deduplicating only within the incoming batch. This means importing the same export a second time would add duplicate records.

When `--reconcile-existing` is passed, the command first loads all records already present in the Pod and includes them in the deduplication pass. Any record in the incoming file whose [deterministic ID](./deterministic-ids.md) matches an existing Pod record is treated as a duplicate and skipped.

This makes imports idempotent: running the same import command twice produces the same Pod state.

```bash
# First import — no existing records to reconcile against
cascade pod import ./my-pod pod/source-epic.ttl --source-system "epic"

# Second import from a different source — reconcile against Epic records
cascade pod import ./my-pod pod/source-cerner.ttl \
  --source-system "cerner" \
  --reconcile-existing
```

Deduplication is based on content-hashed deterministic URIs (see [Deterministic IDs](./deterministic-ids.md)). Records with identical clinical content but different source provenance are detected as duplicates regardless of which EHR system produced them.

When a conflict cannot be resolved automatically (e.g., two sources disagree on a field value), the record is written to `settings/pending-conflicts.ttl` for manual resolution. Use `cascade pod conflicts` and `cascade pod resolve` to manage these.

---

### cascade pod conflicts

List unresolved conflicts in a Pod.

```
cascade pod conflicts <pod-dir> [--format text|json]
```

Reads `<pod-dir>/settings/pending-conflicts.ttl` and prints a summary of all unresolved conflicts.

**Arguments**

| Argument | Required | Description |
|----------|----------|-------------|
| `<pod-dir>` | Yes | Path to a Pod directory |
| `--format text\|json` | No | Output format. Defaults to `text` |

**Exit codes**

| Code | Meaning |
|------|---------|
| `0` | No unresolved conflicts |
| `1` | One or more unresolved conflicts exist |

The non-zero exit code on conflicts makes this command suitable for use in CI pipelines:

```bash
cascade pod conflicts ./my-pod || echo "Conflicts need resolution before proceeding"
```

**Text output example**

```
2 unresolved conflicts

conflict-1 (ImmunizationRecord)
  source-a: date = 2019-08-15, cvx = 140
  source-b: date = 2019-09-02, cvx = 140
  Conflict field: date

conflict-2 (Medication)
  source-a: dosage = 10mg
  source-b: dosage = 20mg
  Conflict field: dosage
```

**JSON output example**

```bash
cascade pod conflicts ./my-pod --format json
```

```json
{
  "count": 2,
  "conflicts": [
    {
      "id": "conflict-1",
      "type": "ImmunizationRecord",
      "field": "date",
      "sourceA": { "system": "epic", "value": "2019-08-15" },
      "sourceB": { "system": "cerner", "value": "2019-09-02" }
    }
  ]
}
```

---

### cascade pod resolve

Record a manual resolution for a conflict.

```
cascade pod resolve <pod-dir> --conflict <id> --keep source-a|source-b
```

Writes a resolution entry to `<pod-dir>/settings/user-resolutions.ttl` and removes the conflict from `settings/pending-conflicts.ttl`.

**Arguments**

| Argument | Required | Description |
|----------|----------|-------------|
| `<pod-dir>` | Yes | Path to a Pod directory |
| `--conflict <id>` | Yes | The conflict ID from `cascade pod conflicts` output |
| `--keep source-a\|source-b` | Yes | Which source's value to keep |

**Example**

```bash
# List conflicts to find IDs
cascade pod conflicts ./my-pod

# Keep the Epic value for conflict-1
cascade pod resolve ./my-pod --conflict conflict-1 --keep source-a

# Verify the conflict is cleared
cascade pod conflicts ./my-pod
echo "Exit code: $?"   # 0 = no remaining conflicts
```

Resolutions are stored in `settings/user-resolutions.ttl` as Cascade Protocol RDF triples. This file serves as an audit trail of all manual decisions made during the import process.

---

### cascade pod extract

Run AI extraction on clinical documents flagged for LLM processing.

```
cascade pod extract <pod-dir> [--agent-url <url>] [--dry-run] [--section <section>]
```

Reads `<pod-dir>/clinical/documents.ttl` for `clinical:ClinicalDocument` nodes that carry `cascade:requiresLLMExtraction = "true"`. For each matching document, the narrative block is POSTed to a running `cascade agent serve` instance. Extracted records are then routed to one of three destinations based on the confidence score returned by the agent.

**Prerequisites**

A local extraction model must be downloaded (run `cascade agent login --provider local` to download). The command will auto-start `cascade agent serve` if no agent is already running at the specified URL, and stop it after extraction completes. If an agent is already running, it is reused.

**Arguments**

| Argument | Required | Description |
|----------|----------|-------------|
| `<pod-dir>` | Yes | Path to an initialized Pod directory |
| `--agent-url <url>` | No | Base URL of the running agent server. Defaults to `http://127.0.0.1:8765` |
| `--dry-run` | No | Preview which documents would be submitted and how they would be routed, without writing any output files |
| `--section <section>` | No | Limit extraction to a specific C-CDA section name (e.g., `medications`, `problems`) |

**Confidence routing**

| Confidence | Destination | Meaning |
|------------|-------------|---------|
| >= 0.85 | `clinical/ai-extracted.ttl` | Auto-accepted; merged into the Pod as trusted records |
| 0.50 – 0.84 | `analysis/review-queue.json` | Queued for human review via `cascade agent review` |
| < 0.50 | `analysis/discarded-extractions.ttl` | Discarded; retained for audit but not surfaced in the Pod |
| Error | `analysis/extraction-errors.json` | Failed blocks with error type, char count, and message for debugging |

**Idempotent re-runs.** Running `cascade pod extract` multiple times on the same Pod is safe. Already-extracted blocks are tracked in `analysis/extraction-done.json` and skipped on subsequent runs. Only blocks that previously failed are retried.

**Automatic chunking.** Narrative blocks exceeding 24,000 characters are automatically split at paragraph or line boundaries before being sent to the extraction model. This prevents context-window overflow on large sections such as lab result tables.

**Adaptive timeout.** The per-block timeout scales with text size (base 60s + 20ms per character, up to 5 minutes) instead of using a fixed 60-second limit.

**Typical workflow**

```bash
# 1. Import records — documents requiring LLM extraction are flagged automatically
cascade pod import ./my-pod records.xml

# 2. Extract structured data (agent starts automatically)
cascade pod extract ./my-pod

# 3. Review low-confidence extractions interactively
cascade agent review --pod ./my-pod
```

**Example**

```bash
# Extract only the medications section, preview output without writing
cascade pod extract ./my-pod --section medications --dry-run

# Full extraction against a custom agent URL
cascade pod extract ./my-pod --agent-url http://127.0.0.1:9000
```

---

### cascade agent

Natural language interface and document intelligence server for Cascade operations.

#### cascade agent (REPL)

```
cascade agent [-p <provider>] [-m <model>] [prompt]
```

Starts an interactive REPL for Cascade operations using natural language. Accepts an optional one-shot `prompt` argument to run a single query and exit without entering the interactive loop.

**Arguments**

| Argument | Required | Description |
|----------|----------|-------------|
| `-p, --provider <name>` | No | Override the active provider for this session |
| `-m, --model <model>` | No | Override the active model for this session |
| `[prompt]` | No | Run a single natural language query and exit (one-shot mode) |

**Package:** `@the-cascade-protocol/agent` (included as a dependency of `@the-cascade-protocol/cli`)

---

#### cascade agent serve

Start the document intelligence HTTP server.

```
cascade agent serve [--port <number>] [--web-review]
```

Starts a local HTTP server on port 8765 that exposes a document extraction API. On first run, prompts to download the extraction model (Qwen3.5-4B, ~2.5 GB, or Qwen3.5-2B, ~1.5 GB). Model selection is configured via `cascade agent login --provider local`. Subsequent starts use the cached model. Note: `cascade pod extract` auto-starts this server when needed; manual invocation is only required for persistent or shared-access use.

**Endpoints**

| Endpoint | Description |
|----------|-------------|
| `POST /extract` | Submit a narrative block for structured data extraction. Returns extracted triples and a confidence score. |
| `GET /health` | Returns `200 OK` when the server is ready to accept requests. |

**Arguments**

| Argument | Required | Description |
|----------|----------|-------------|
| `--port <number>` | No | Port to listen on. Defaults to `8765` |
| `--web-review` | No | Also serve the browser-based review UI for the extraction queue |

**Example**

```bash
# Start the server on the default port
cascade agent serve

# Start on a custom port with the web review UI enabled
cascade agent serve --port 9000 --web-review
```

---

#### cascade agent review

Terminal review UI for low-confidence AI extractions.

```
cascade agent review [--pod <path>] [--output <path>]
```

Opens an interactive terminal interface for reviewing items in the extraction review queue (confidence 0.50–0.84). Each item shows the extracted data alongside the source narrative, allowing the reviewer to accept, edit, or discard each extraction.

**Arguments**

| Argument | Required | Description |
|----------|----------|-------------|
| `--pod <path>` | No | Path to the Pod whose `analysis/review-queue.json` should be loaded |
| `--output <path>` | No | Write accepted extractions to this Turtle file instead of the default `clinical/ai-extracted.ttl` |

---

#### cascade agent login

Configure provider credentials.

```
cascade agent login
```

Interactive prompt to enter and store credentials for a supported AI provider. Credentials are stored in the local CLI configuration and used by all subsequent `cascade agent` commands.

**Supported providers**

| Provider | Notes |
|----------|-------|
| Anthropic | Claude model family |
| OpenAI | GPT model family |
| Google | Gemini model family |
| Ollama | Locally served models |
| Local | Direct path to a local model file |

---

#### cascade agent provider

Show or set the active provider.

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

With no argument, prints the currently active provider. When `name` is supplied, sets that provider as the active default for all subsequent `cascade agent` commands.

---

#### cascade agent model

Show or set the model for the active provider.

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

With no argument, prints the currently active model. When `name` is supplied, sets that model as the active default for the current provider.

---

## 3. Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | One or more errors or unresolved conflicts (`cascade pod conflicts`) |
| `2` | Invalid arguments or usage error |

---

*See also:*
- [Multi-Source EHR Import Guide](./multi-source-import.md)
- [Deterministic IDs](./deterministic-ids.md)
- [Pod Structure Specification](../spec/pod-structure.md)