Skip to content

Command Reference

Generated from the CLI definitions by scripts/gen_cli_reference.py. Do not edit by hand.

Commands marked needs a clone use cards, registry or scripts that are not part of the pip package; from a pip install they print how to clone the repository and exit with code 2. All other commands work after pip install protocolith.

Global option: --version prints the installed version.

protocolith new (alias: new-track)

Create a draft track scaffold. Prompts interactively when run in a terminal.

  • --source-url SOURCE_URL
  • --protocol-id PROTOCOL_ID
  • --domain DOMAIN
  • --track-type TRACK_TYPE
  • --execution-mode EXECUTION_MODE (choices: MANUAL_NO_AI, AUTOMATED_AI_ASSISTED; default: MANUAL_NO_AI)
  • --out OUT
  • --source-name SOURCE_NAME (default: Public source under review)
  • --audience AUDIENCE (default: public evidence operators)
  • --dry-run — List the files that would be created and write nothing.

protocolith demo

Needs a clone of the repository.

Run a small public demo helper.

  • name (one of: grok-source-audit, eea-source-audit, eea-manual-probe, validate-all)
  • --report REPORT
  • --demo-root DEMO_ROOT — Local-only root for demo source clones and reports. (default: ~/protocolith_runs/protocolith_demo)
  • --grok-repo-dir GROK_REPO_DIR — Existing local clone for xai-org/grok-prompts. Defaults to a local-only demo clone.

protocolith validate-all

Needs a clone of the repository.

Validate all public evidence cards and the registry.

  • --cards-dir CARDS_DIR (default: docs/evidence_cards)
  • --registry REGISTRY (default: docs/registry/evidence_index.json)
  • --families-dir FAMILIES_DIR — Directory containing optional *_FAMILY_LEDGER.json files. (default: docs/track_families)
  • --frontiers-dir FRONTIERS_DIR — Directory containing optional *_FRONTIER.json files. (default: docs/track_families)
  • --trees-dir TREES_DIR — Directory containing optional protocol v3 *_TREE.json files. (default: docs/track_families)

protocolith validate-family

Validate one R&D family ledger JSON file.

  • path

protocolith validate-frontier

Validate one R&D family frontier JSON file.

  • path
  • --base-dir BASE_DIR — Optional base directory for context capsule and tombstone path checks.

protocolith validate-tree

Validate one protocol v3 R&D tree overlay JSON file.

  • path

protocolith run-root

Create a local-only run root with standard raw/log/hash/report folders.

  • --protocol-id PROTOCOL_ID
  • --source-url SOURCE_URL
  • --operator OPERATOR (default: local operator)
  • --root ROOT — Local-only parent directory. Defaults to ~/protocolith_runs. (default: ~/protocolith_runs)

protocolith run-root deviation

protocolith run-root deviation add

  • --run-dir RUN_DIR (required)
  • --step STEP (required)
  • --planned PLANNED (required)
  • --happened HAPPENED (required)
  • --reason REASON (required)
  • --who WHO (required)

protocolith run-root deviation list

  • --run-dir RUN_DIR (required)

protocolith run-root rights

protocolith run-root rights answer

  • --run-dir RUN_DIR (required)
  • --question-id QUESTION_ID (required)
  • --answer ANSWER (required)
  • --who WHO (required)

protocolith doctor

Check Python, git and repo layout for cross-platform workflows.

protocolith inspect

Print selected JSON fields from cards, registry or artifacts.

protocolith inspect card

  • path
  • --keys KEYS — Top-level JSON keys to print (default: a short card summary). (one or more values; default: evidence_id, record_type, result_status, reproduction_level, verification_level, protocol_id, official_source_url, access_date, claim_boundary)

protocolith inspect registry

  • --registry REGISTRY (default: docs/registry/evidence_index.json)
  • --keys KEYS (one or more values; default: registry_name, card_count)

protocolith inspect json

  • path
  • --keys KEYS (required; one or more values)

protocolith hash

Print SHA-256 hashes for local files.

  • paths (one or more values)
  • --out OUT — Optional file to write hash lines.

protocolith validate-card

Validate one evidence card JSON file.

  • path

protocolith rerun

Needs a clone of the repository.

Run frozen public-data reruns with cross-platform commands.

protocolith rerun nasa-d103

  • --operator OPERATOR (default: local operator)
  • --root ROOT (default: ~/protocolith_runs)
  • --run-dir RUN_DIR
  • --baseline BASELINE

protocolith rerun noaa-d131

  • --operator OPERATOR (default: local operator)
  • --root ROOT (default: ~/protocolith_runs)
  • --run-dir RUN_DIR
  • --baseline BASELINE

protocolith rerun report

Compare original vs rerun hashes; never modifies a card or claim.

  • --original ORIGINAL (required)
  • --rerun RERUN (required)
  • --outcome OUTCOME (choices: matches, differs, unknown; default: unknown)
  • --blocked
  • --note NOTE (default: ``)
  • --out OUT

protocolith drift

Needs a clone of the repository.

Compare fresh public-source probes against frozen baselines.

protocolith drift eea-source-audit

  • --baseline BASELINE
  • --report REPORT

protocolith probe

SourceProbe v1: metadata-only probe of one public URL (no legal conclusion).

  • url
  • --marker MARKER — Case-sensitive text to look for.
  • --out OUT — Write the JSON probe artifact here.
  • --json — Print the JSON artifact.

protocolith verify

Needs a clone of the repository.

Run VERIFY pack checklists with PASS/FAIL output.

  • pack (one of: ai-boundary, api-parity, eea-drift, nasa-rerun, noaa-rerun, source-probe-spec, starter-pack, static-registry-spec)
  • --operator OPERATOR — Operator handle for network rerun verify packs. (default: verify-operator)

protocolith freeze

Freeze a protocol from a JSON file.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • file
  • --supersedes SHA256 — Hash of the protocol version this replaces.

protocolith record

Record a run outcome from a JSON file.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • file

protocolith deviation

Record a deviation from a JSON file.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • file

protocolith verify-ledger

Verify the ledger (rules R1 to R11).

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • --expect-head SEQ:HASH — Also require the entry at SEQ to have this hash (detects a removed tail); else HEAD_MISMATCH, exit 1.

protocolith issue

Issue the evidence card of a record.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • seq
  • --out DIR — Card directory (default /cards).

protocolith log

List ledger entries, optionally filtered.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • --protocol ID — Only entries of this protocol_id.
  • --type TYPE — Only entries of this type. (choices: freeze, record, deviation, issue)
  • --status STATUS — Only records with this result status. (choices: BLOCKED_SOURCE, INSUFFICIENT_COVERAGE, NEGATIVE_RESULT_UNDER_PROTOCOL, PASSED_UNDER_PROTOCOL, REPRODUCED_OUTCOME, SOURCE_DRIFT)
  • --tail N — Keep only the last N matching entries.

protocolith show

Show one entry with its protocol context.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • seq

protocolith summary

Verdict, head, counts and a per-protocol table in one call.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • --protocol ID — Only this protocol_id.

protocolith init

Create the store with an empty ledger (safe to repeat).

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.

protocolith capture

Print a JSON fragment for the outcome object of a record: Python, platform, machine and protocolith version, and the relative path, size and sha256 of each --file (inside the current directory). Runs nothing and reads no environment values.

  • --json — Print errors as canonical JSON.
  • --file PATH — File to hash; repeat for several.
  • --env — Include the environment (implied when no --file is given).

protocolith schema

Print a JSON Schema (draft 2020-12) generated from the rules.

  • name — Which schema (default all). (one of: freeze, record, deviation, issue, entry, all)

protocolith head

Print the ledger head (last hash and seq).

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.

protocolith repair

Repair a crash-damaged ledger.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • --truncate-partial-tail — Remove the partial last line. (required)

protocolith atlas

Build a self-contained offline HTML atlas of experiments from a ledger and/or evidence card directories.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).
  • --json — Print the result as canonical JSON.
  • --cards DIR — Directory of evidence card JSON files, searched recursively; repeat for several. Without --store and --cards: a local ledger, else docs/evidence_cards.
  • --out FILE_OR_DIR — Output .html file or directory (default protocolith-atlas.html). (default: protocolith-atlas.html)
  • --title TEXT — Page title. (default: Protocolith atlas)
  • --i18n DIR — Directory of .json translation files; adds a language switcher.
  • --default-lang CODE — Initial language (default en). (default: en)
  • --max-rows N — Embed at most N records (the newest); counts stay complete.

protocolith mcp

Run the MCP server on stdio.

  • --store STORE — Store directory (env PROTOCOLITH_STORE, default .protocolith).