> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# nora causal

> Per-folder causal graphs — settings, bootstrap, staged review, live approval.

Causal graphs in Nora are **per-folder**: attach a graph to a document folder, extract causal triples from those documents into a **staged** area, then approve them to **live**.

The `causal` CLI is the surface for the staged/live workflow. Graphs bootstrap from documents; you approve the good triples; only the approved (live) ones are used for verification and reasoning.

## Commands

| Command                         | Description                                    |
| ------------------------------- | ---------------------------------------------- |
| `causal get <folder>`           | Fetch the folder's full graph (LIVE + STAGED). |
| `causal settings show <folder>` | Print folder graph settings + stage stats.     |
| `causal settings set <folder>`  | Update graph settings.                         |
| `causal bootstrap <folder>`     | Extract causal triples into STAGED.            |
| `causal refresh <folder>`       | Recompute deltas into STAGED.                  |
| `causal approve <folder>`       | Promote STAGED rows to LIVE.                   |
| `causal reject <folder>`        | Drop STAGED rows without promoting.            |

Folder identifiers are the document folder tag (e.g. `billing`, `product-docs`).

## `causal get`

```bash theme={null}
nora causal get billing
```

Prints the whole graph:

* `live_nodes` and `live_edges` — used in verification and reasoning.
* `staged_nodes` and `staged_edges` — waiting for review.

Add `--json` for structured output.

Common quick check:

```bash theme={null}
nora causal get billing --json | jq '{live: .live_nodes | length, staged: .staged_nodes | length}'
```

## `causal settings show` / `set`

```bash theme={null}
nora causal settings show billing
```

Shows settings + stage counts.

```bash theme={null}
nora causal settings set billing \
  --connection documents_folder:billing \
  --retrieval-preset high-precision \
  --dedup-policy merge \
  --auto-restage true
```

Only flags passed change.

* `--connection <kind:id>` — link the graph to a specific data source (e.g. `documents_folder:billing`).
* `--retrieval-preset <preset-id>` — the preset extraction uses to pull context.
* `--dedup-policy <policy>` — how duplicates are handled (`merge`, `keep_newer`, `keep_older`, `keep_all`).
* `--auto-restage true|false` — automatically re-bootstrap when the linked source changes.

## `causal bootstrap`

```bash theme={null}
nora causal bootstrap billing --model gpt-4o
```

Extracts causal triples from every document in the folder into STAGED. Nothing goes to LIVE until you `approve`.

* `--model <m>` — model used for extraction. Defaults to workspace default.

Bootstrap is idempotent — re-running on an already-populated folder doesn't lose LIVE data. Re-extraction produces new STAGED rows; existing LIVE stays as-is.

For a fresh folder: bootstrap → review the STAGED area in the app → approve the good ones. For an existing folder: `refresh` is usually what you want.

## `causal refresh`

```bash theme={null}
nora causal refresh billing
```

Recomputes only the deltas — new documents added, existing documents changed since the last bootstrap. Cheaper than a full bootstrap.

Refresh output lands in STAGED. Existing LIVE stays intact.

Run on a schedule (or triggered by document changes) if `--auto-restage` isn't your fit.

## `causal approve` / `reject`

```bash theme={null}
# Approve all STAGED rows
nora causal approve billing

# Approve specific rows only
nora causal approve billing --ids node_1,edge_a,node_5

# Reject the rest
nora causal reject billing
```

* `--ids <id,…>` — the specific staged row IDs. Omit to act on all STAGED.

After `approve`:

* The rows move to LIVE.
* Verification starts using them immediately.
* STAGED still contains anything not touched by this command.

`reject` drops the rows without promoting. They can be re-created by the next bootstrap or refresh.

## Recipes

### Bootstrap a folder end-to-end from CLI

```bash theme={null}
folder="billing"

# 1. Configure
nora causal settings set $folder \
  --connection documents_folder:$folder \
  --retrieval-preset high-precision \
  --auto-restage true

# 2. Extract into STAGED
nora causal bootstrap $folder

# 3. Review (usually in the app), then bulk-approve everything staged
nora causal approve $folder

# 4. Verify a query uses the graph
nora retrieval search "some question" --filters '{"tag":"'$folder'"}' --include-subgraph
```

### CI: fail if STAGED is too large

Prevents unbounded backlog:

```bash theme={null}
threshold=200
staged=$(nora causal get billing --json | jq '.staged_nodes | length')
if [ "$staged" -gt "$threshold" ]; then
  echo "STAGED backlog too large ($staged > $threshold). Review needed."
  exit 1
fi
```

### Selective approve after human review

Suppose your review workflow marks approvals in an external system with the row IDs. Bulk-approve them:

```bash theme={null}
ids=$(cat approved-ids.txt | tr '\n' ',' | sed 's/,$//')
nora causal approve billing --ids "$ids"
```

### Snapshot the LIVE graph for audit

```bash theme={null}
nora causal get billing --json | jq '{live_nodes, live_edges}' > audit/billing-graph-$(date +%Y%m%d).json
```

## The STAGED / LIVE model

The two-stage model exists because causal extraction is best-effort — the model proposes, you dispose. Direct edits to LIVE aren't allowed from the CLI (use the app's graph canvas for those). But bulk approval/rejection is what the CLI is for.

If you want to hand-edit a live graph — add a specific edge, remove a wrong node — do it in the app. The CLI's role is bulk bootstrap/refresh/approve.

## Related

* [Causal graph overview](/build/causal-graph/overview) — concepts and use cases.
* [Verify agent answers](/build/causal-graph/verification) — how LIVE graphs are used.
* [`nora retrieval`](/cli/retrieval) — `--include-subgraph` expands search using the graph.