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

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 [e-mail]
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	—	Data source name
--supports ID_OR_DOI	—	Upstream claim_id or DOI (repeatable)
--contradicts ID_OR_DOI	—	Claim_id this finding contests (repeatable)
--generated-by TEXT	agent	Agent identifier
--artifact-hash TEXT	—	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	—	Filter by status: open, contested, retracted
--source TEXT	—	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 [e-mail]

---

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, or orphan_signer.