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

# CLI Reference

> The Mareforma command-line interface: identity setup, claim management, validator enrollment, epistemic health, export, and bundle verification.

| Command                    | Purpose                                    |
| -------------------------- | ------------------------------------------ |
| `mareforma bootstrap`      | Generate Ed25519 signing key               |
| `mareforma validator add`  | Enroll a validator (`--type human\|llm`)   |
| `mareforma validator list` | List enrolled validators                   |
| `mareforma claim add`      | Assert a scientific claim                  |
| `mareforma claim list`     | List claims                                |
| `mareforma claim show`     | Show one claim                             |
| `mareforma claim update`   | Update a claim                             |
| `mareforma claim validate` | Promote REPLICATED → ESTABLISHED           |
| `mareforma status`         | Epistemic health dashboard                 |
| `mareforma export`         | Write `ontology.jsonld` (or signed bundle) |
| `mareforma verify`         | Verify a signed bundle                     |
| `mareforma restore`        | Rebuild graph.db from claims.toml          |

## Overview

```bash theme={"dark"}
mareforma [COMMAND] [OPTIONS]
```

Available commands: `bootstrap`, `validator`, `claim`, `status`, `export`, `verify`.

***

## bootstrap

Generate an Ed25519 signing key for this user. Run once after installing mareforma.

```bash theme={"dark"}
mareforma bootstrap [OPTIONS]
```

The key is written to `~/.config/mareforma/key` (XDG-compliant) with mode `0600`. After bootstrap, every claim written via `mareforma.open()` is signed with this key and the signature envelope is persisted to the row's `signature_bundle` column.

**Options**

| Option            | Default                   | Description                                                                                                                                                                            |
| ----------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--key-path PATH` | `~/.config/mareforma/key` | Override the default key path                                                                                                                                                          |
| `--overwrite`     | `False`                   | Replace an existing key. **Destructive**: strands every claim signed by the prior key (verification breaks) AND every claim not yet submitted to Rekor becomes permanently un-loggable |

Safe rotation: back up the old key, run `graph.refresh_unsigned()` to drain the pending queue, then rotate.

**Examples**

```bash theme={"dark"}
mareforma bootstrap
# → Generated signing key at /home/you/.config/mareforma/key
# → Public key id: ed25519:abc123...
```

***

## validator

Manage the per-project validators table: who may promote claims to `ESTABLISHED`.

```bash theme={"dark"}
mareforma validator [SUBCOMMAND]
```

The first key opened against a fresh `graph.db` auto-enrolls as the root validator (silent self-signed enrollment, with a `UserWarning` so an operator who opened the project with the wrong key has a chance to notice).

### validator add

Enroll a new validator on the current project. The currently loaded signing key signs the enrollment and becomes the parent of the new validator. The signer must already be enrolled.

```bash theme={"dark"}
mareforma validator add --pubkey PATH_OR_PEM --identity LABEL [--type human|llm]
```

**Options**

| Option              | Description                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `--pubkey TEXT`     | PEM-encoded public key. Pass a file path or paste the PEM text. File reads capped at 64 KB                                                 |
| `--identity TEXT`   | Display label (email, lab name, etc.). 256-char cap; control characters and Unicode display-spoofing forms are rejected                    |
| `--type human\|llm` | Self-declared validator type. Default `human`. `llm` validators may sign validation envelopes but cannot promote a claim past `REPLICATED` |

**Examples**

```bash theme={"dark"}
mareforma validator add --pubkey ./alice.pub.pem --identity alice@lab.example
mareforma validator add --pubkey ./bot.pub.pem --identity reviewer-bot --type llm
```

### validator list

List enrolled validators in the order they were added.

```bash theme={"dark"}
mareforma validator list [OPTIONS]
```

**Options**

| Option   | Description         |
| -------- | ------------------- |
| `--json` | Emit JSON to stdout |

***

## claim

Manage scientific claims.

```bash theme={"dark"}
mareforma claim [SUBCOMMAND]
```

### claim add

Assert a new scientific claim.

```bash theme={"dark"}
mareforma claim add TEXT [OPTIONS]
```

**Arguments**

| Argument | Description                            |
| -------- | -------------------------------------- |
| `TEXT`   | The claim text. Falsifiable assertion. |

**Options**

| Option                    | Default    | Description                                                                                                                                  |
| ------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--classification`        | `INFERRED` | `INFERRED` \| `ANALYTICAL` \| `DERIVED`                                                                                                      |
| `--status`                | `open`     | `open` \| `contested` \| `retracted`                                                                                                         |
| `--source TEXT`           | none       | Data source name                                                                                                                             |
| `--supports ID_OR_DOI`    | none       | Upstream claim\_id or DOI (repeatable)                                                                                                       |
| `--contradicts ID_OR_DOI` | none       | Claim\_id this finding contests (repeatable)                                                                                                 |
| `--generated-by TEXT`     | `agent`    | Agent identifier                                                                                                                             |
| `--artifact-hash TEXT`    | none       | SHA-256 hex digest of the output bytes backing the claim. Bound into the signed payload; converging peers must match when both supply a hash |

**Examples**

```bash theme={"dark"}
# Basic claim
mareforma claim add "Target T is elevated in condition C"

# With classification, source, and artifact hash
mareforma claim add "Target T is elevated in condition C (n=620)" \
  --classification ANALYTICAL \
  --source dataset_alpha \
  --generated-by "agent/model-a/lab_a" \
  --artifact-hash "$(sha256sum figure_3.png | cut -d' ' -f1)"

# Building on prior findings
mareforma claim add "The mechanism is likely M" \
  --classification DERIVED \
  --supports 3f8a1b2c-...
```

***

### claim list

List claims, optionally filtered.

```bash theme={"dark"}
mareforma claim list [OPTIONS]
```

**Options**

| Option          | Default | Description                                        |
| --------------- | ------- | -------------------------------------------------- |
| `--status TEXT` | none    | Filter by status: `open`, `contested`, `retracted` |
| `--source TEXT` | none    | Filter by source name                              |
| `--json`        | `False` | Emit JSON to stdout                                |

**Examples**

```bash theme={"dark"}
mareforma claim list
mareforma claim list --status open
mareforma claim list --json | jq '.[].support_level'
```

***

### claim show

Show full details for one claim.

```bash theme={"dark"}
mareforma claim show CLAIM_ID [OPTIONS]
```

**Options**

| Option   | Description         |
| -------- | ------------------- |
| `--json` | Emit JSON to stdout |

***

### claim update

Update editable fields on an existing claim.

```bash theme={"dark"}
mareforma claim update CLAIM_ID [OPTIONS]
```

**Options**

| Option                    | Description                                          |
| ------------------------- | ---------------------------------------------------- |
| `--status TEXT`           | New status: `open`, `contested`, `retracted`         |
| `--text TEXT`             | New claim text (rejected on signed claims)           |
| `--supports ID_OR_DOI`    | Replace supports list (rejected on signed claims)    |
| `--contradicts ID_OR_DOI` | Replace contradicts list (rejected on signed claims) |

Signed claims (those with a non-NULL `signature_bundle`) refuse mutation of `text` / `supports` / `contradicts`; these are part of the signed payload and silent mutation would invalidate the signature. To revise a signed claim, retract it (`--status retracted`) and assert a new one citing the old via `--contradicts <old_claim_id>`. `status` remains editable since it is not part of the signed payload.

***

### claim validate

Promote a `REPLICATED` claim to `ESTABLISHED`. Identity-gated.

```bash theme={"dark"}
mareforma claim validate CLAIM_ID [OPTIONS]
```

Requires a loaded signing key (`mareforma bootstrap` first) AND that key must be enrolled in the project's `validators` table. The validation event itself is signed: a DSSE-style envelope binding `(claim_id, validator_keyid, validated_at)` is persisted to the row's `validation_signature` column.

**Options**

| Option                | Description                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--validated-by TEXT` | Cosmetic display label of the reviewer. The authoritative identity is the keyid embedded in the signed envelope |

**Examples**

```bash theme={"dark"}
mareforma claim validate abc123
mareforma claim validate abc123 --validated-by reviewer@example.org
```

***

## status

Show the epistemic health dashboard.

```bash theme={"dark"}
mareforma status [OPTIONS]
```

**Traffic light**

| Color     | Condition                                    |
| --------- | -------------------------------------------- |
| 🔴 RED    | No claims recorded                           |
| 🟡 YELLOW | Claims exist but all are PRELIMINARY         |
| 🟢 GREEN  | At least one REPLICATED or ESTABLISHED claim |

**Options**

| Option   | Description         |
| -------- | ------------------- |
| `--json` | Emit JSON to stdout |

***

## export

Export all claims as a JSON-LD document, optionally as a SCITT-style signed bundle.

```bash theme={"dark"}
mareforma export [OPTIONS]
```

**Plain JSON-LD** (default). Writes `ontology.jsonld` in the mareforma-native vocabulary (`@type=mare:Graph`, media type `application/x-mareforma-graph+json`). The export is NOT PROV-O-conformant. Earlier versions name-dropped PROV-O without populating the full graph; the current export uses an honest mareforma-native vocabulary instead. Each claim node carries every `SIGNED_FIELDS` member so a bundle verifier can re-derive `canonical_payload` from a node alone.

**Signed bundle** (`--bundle`). Wraps the JSON-LD export in an in-toto Statement v1 envelope and signs it with the local Ed25519 key. The bundle includes one subject entry per claim (`urn:mareforma:claim:<uuid>`) with a SHA-256 of the claim's `canonical_payload`, plus a bundle-level DSSE signature. Requires a bootstrapped XDG key.

**Options**

| Option          | Default                                                            | Description                                                                   |
| --------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `--output PATH` | `./ontology.jsonld` (or `./mareforma-bundle.json` with `--bundle`) | Output file path                                                              |
| `--json`        | `False`                                                            | Print JSON-LD to stdout instead of writing a file (no effect with `--bundle`) |
| `--bundle`      | `False`                                                            | Produce a SCITT-style signed bundle (in-toto Statement v1 + DSSE)             |

**Examples**

```bash theme={"dark"}
# Plain JSON-LD
mareforma export
mareforma export --output /tmp/my_claims.jsonld
mareforma export --json | jq '.["@graph"][] | select(.["@type"] == "mare:Claim")'

# Signed bundle
mareforma export --bundle
mareforma export --bundle --output /tmp/release.bundle.json
```

The JSON-LD output uses `mare:` and `schema:` vocabularies. Each claim is a `mare:Claim` node with `claimText`, `classification`, `supportLevel`, `generatedBy`, `supports`, `contradicts`, `sourceName`, and `artifactHash` fields.

***

## verify

Verify a SCITT-style signed bundle against the local signing key. Checks the bundle's DSSE signature AND every per-claim subject digest.

```bash theme={"dark"}
mareforma verify BUNDLE_PATH
```

**Arguments**

| Argument      | Description                                                               |
| ------------- | ------------------------------------------------------------------------- |
| `BUNDLE_PATH` | Path to a `mareforma-bundle.json` produced by `mareforma export --bundle` |

Exits `0` on success ("verified: N claim subjects match"), `1` on any verification failure. `BundleVerificationError` names the first failing check so callers can route between "corrupt" and "cross-version skew" (e.g. a bundle whose `predicateType` is `epistemic-graph:v2` will be refused by a `v1` verifier).

**Examples**

```bash theme={"dark"}
mareforma export --bundle
mareforma verify mareforma-bundle.json
# → Bundle verified: 12 claim subject(s) match.
```

***

## restore

Rebuild `graph.db` from `claims.toml` for catastrophic-loss recovery. Refuses to run if the project's `graph.db` already contains claims: fresh-only, not merge. Every signature is verified before any row is inserted; fail-all-or-nothing.

```bash theme={"dark"}
mareforma restore [CLAIMS_TOML_PATH]
```

**Arguments**

| Argument           | Description                                                     |
| ------------------ | --------------------------------------------------------------- |
| `CLAIMS_TOML_PATH` | Optional. Path to the source TOML. Defaults to `./claims.toml`. |

**Examples**

```bash theme={"dark"}
# Standard case — claims.toml in the project root:
mareforma restore

# Explicit source (e.g. recovered from a backup):
mareforma restore backups/state.toml
```

The output reports `validators_restored` and `claims_restored` counts. Failure exits `1` with a `RestoreError` message naming the failure mode: `graph_not_empty`, `toml_not_found`, `toml_malformed`, `enrollment_unverified`, `claim_unverified`, `mode_inconsistent`, `orphan_signer`, or `rekor_inclusion_invalid`.

Since v0.3.2, `claims.toml` includes a `[rekor_inclusions]` section. Pre-v0.3.2 files restore successfully with a `RekorSidecarSectionAbsentWarning`. Run `refresh_unsigned()` afterward to re-fetch inclusion proofs.

***

## ingest

Added in v0.3.3. Read a paper abstract from disk, extract claim drafts, and write them to the project's `literature_claims` table (separate from the signed `claims` table, since most drafts stay drafts pending review).

```bash theme={"dark"}
mareforma ingest <FILE> [--db PATH] [--llm] [--model MODEL]
```

**Arguments**

| Argument | Description                                                            |
| -------- | ---------------------------------------------------------------------- |
| `FILE`   | Path to a structured abstract file (TITLE: / DOI: / CLAIMS: sections). |

**Options**

| Option          | Default               | Description                                                                                                                |
| --------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `--db PATH`     | `.mareforma/graph.db` | Path to the graph DB. Honours the literal filename; non-conventional paths are NOT silently rewritten under `.mareforma/`. |
| `--llm`         | off                   | Use the Anthropic Claude API to extract claims from arbitrary text. Requires `pip install anthropic`.                      |
| `--model MODEL` | `claude-opus-4-7`     | Anthropic model name when `--llm` is set.                                                                                  |

**Default (structured) mode** parses files with explicit `TITLE:` / `DOI:` / `CLAIMS:` sections; each `CLAIMS:` line becomes one draft with an optional `(confidence: 0.NN)` marker. Zero external dependencies.

**Example**

```bash theme={"dark"}
mareforma ingest paper.md
# Ingested 3 claim(s) → written to .mareforma/graph.db

mareforma ingest preprint.txt --llm --model claude-opus-4-7
# Extracts claims from arbitrary text via Claude.
```

***

## ask

Added in v0.3.3. FTS5 BM25 search over ingested literature claims. Input is sanitised so hyphens, parens, and asterisks are treated as literals; embedded double quotes are escaped per the FTS5 spec.

```bash theme={"dark"}
mareforma ask "<QUESTION>" [--db PATH] [--limit N] [--json]
```

**Arguments**

| Argument   | Description             |
| ---------- | ----------------------- |
| `QUESTION` | Free-form search query. |

**Options**

| Option      | Default               | Description                                    |
| ----------- | --------------------- | ---------------------------------------------- |
| `--db PATH` | `.mareforma/graph.db` | Path to the graph DB.                          |
| `--limit N` | `5`                   | Maximum results.                               |
| `--json`    | off                   | Output raw JSON instead of the rendered table. |

**Example**

```bash theme={"dark"}
mareforma ask "BRCA1 mutations"
# Returns top-5 ranked literature_claims hits.

mareforma ask 'mutations of "BRCA1"' --json
# Embedded quotes are escaped; FTS5 syntax errors do not surface.
```

***

## narrative

Added in v0.3.3. Export all ingested literature claims as a Markdown narrative grouped by source document, with structural and polarity-heuristic contradictions flagged inline.

```bash theme={"dark"}
mareforma narrative [--db PATH] [--output FILE]
```

**Options**

| Option              | Default               | Description                      |
| ------------------- | --------------------- | -------------------------------- |
| `--db PATH`         | `.mareforma/graph.db` | Path to the graph DB.            |
| `--output, -o FILE` | stdout                | Write to file instead of stdout. |

**Example**

```bash theme={"dark"}
mareforma narrative -o report.md
# Writes # Literature Summary + per-source sections; ⚠ contradiction flags inline.
```