CLI Reference - Mareforma

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

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.

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

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.

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.

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

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.

mareforma validator list [OPTIONS]

Options

Option	Description
`--json`	Emit JSON to stdout

claim

Manage scientific claims.

mareforma claim [SUBCOMMAND]

claim add

Assert a new scientific claim.

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

# 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.

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

mareforma claim list
mareforma claim list --status open
mareforma claim list --json | jq '.[].support_level'

claim show

Show full details for one claim.

mareforma claim show CLAIM_ID [OPTIONS]

Options

Option	Description
`--json`	Emit JSON to stdout

claim update

Update editable fields on an existing claim.

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.

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

mareforma claim validate abc123
mareforma claim validate abc123 --validated-by reviewer@example.org

status

Show the epistemic health dashboard.

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.

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

# 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.

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

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.

mareforma restore [CLAIMS_TOML_PATH]

Arguments

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

Examples

# 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).

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

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.

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

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.

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

mareforma narrative -o report.md
# Writes # Literature Summary + per-source sections; ⚠ contradiction flags inline.

​Overview

​bootstrap

​validator

​validator add

​validator list

​claim

​claim add

​claim list

​claim show

​claim update

​claim validate

​status

​export

​verify

​restore

​ingest

​ask

​narrative

Overview

bootstrap

validator

validator add

validator list

claim

claim add

claim list

claim show

claim update

claim validate

status

export

verify

restore

ingest

ask

narrative