CLI command reference

All commands work with wikihistory as a backward-compatible alias (e.g., wikihistory analyze).

refract init

Onboarding — runs a quick analysis and shows what Refract can do.

refract init

Fetches recent revisions of "Earth," runs the section differ, and prints next steps: analyze, explore, claim, snapshot, monitor, mcp. No flags needed — a zero-config first experience.

refract analyze

Analyze full edit history of a page.

refract analyze [page] [options]

| Flag | Default | Description | |---|---|---|---| | page | required (positional) | Page title | | -d, --depth <d> | detailed | Analysis depth: brief, detailed, forensic. See depth levels. | | --from <revId> | — | Start revision ID | | --to <revId> | — | End revision ID | | --since <ts> | — | Filter revisions after this ISO timestamp | | -c, --cache | off | Cache revisions in SQLite (~/.wikihistory/refract.db) | | --pages-file <path> | — | Batch file of page titles (one per line) | | --api <url> | en.wikipedia.org | MediaWiki API base URL | | --cache-dir <path> | ~/.wikihistory | Cache directory path | | -r, --report | off | Output ObservationReport instead of raw events | | --config <path> | — | JSON file with analyzer config overrides | | --similarity <n> | 0.8 | Sentence matching threshold (0–1) | | --revert-patterns <path> | — | File of revert regex patterns | | --cluster-window <min> | 60 | Edit cluster window in minutes | | --spike-factor <n> | 3 | Talk activity spike multiplier | | --talk-window <days> | 7/3 | Talk correlation window as "before/after" in days | | --section-rename <mode> | similarity | Section rename detection: exact|similarity|none |

refract claim

Track a specific claim across revisions.

refract claim <page> [options]

refract snapshot

Reconstruct page state at a point in time.

refract snapshot <page> [options]

Displays section list, plain text content, and metadata (revision ID, editor, size, edit comment). Content is truncated at 2000 characters.

refract cron

One-shot re-observation for cron scheduling.

refract cron <pages-file> [options]

refract diff

Cross-wiki comparison (2+ wikis).

refract diff <topic> [options]

refract eval

Run the evaluation harness.

refract eval [options]

refract classify

Classify a single observation boundary using an inference provider.

refract classify <boundary> --input '<json>'

Each boundary's default is the mechanical heuristic. Pass an API key or set REFRACT_INFERENCE_API_KEY to call a model instead. Works with any OpenAI-compatible provider — DeepSeek, Ollama, Anthropic, Together, Anyscale, or local servers.

# OpenAI
refract classify revert --input '{"comment":"reverted vandalism"}'

# DeepSeek
refract classify revert --input '{"comment":"..."}' \
  --endpoint https://api.deepseek.com/v1/chat/completions \
  --model deepseek-chat

# Local Ollama
refract classify revert --input '{"comment":"..."}' \
  --endpoint http://localhost:11434/v1/chat/completions \
  --model llama3

The output includes source: "model" or "default" for auditability.

refract export

Export analysis as structured data.

refract export <page> [options]

| Flag | Default | Description | |---|---|---|---| | page | required (positional) | Page title | | -f, --format <fmt> | json | Output format: json, csv, ndjson, html, parquet | | --bundle | off | Export as signed evidence bundle (SHA-256). See bundle format. | | --manifest | off | Export as replay manifest with all hashes. See manifest format. | | -r, --report | off | Output ObservationReport instead of raw events | | --similarity <n> | 0.8 | Sentence matching threshold (0–1) | | --api <url> | en.wikipedia.org | MediaWiki API base URL |

refract explore

Start a local web explorer with timeline, evidence table, and diff viewer.

refract explore <page> [options]

| Flag | Default | Description | |---|---|---|---| | page | required (positional) | Page title | | -p, --port <n> | 8899 | Server port | | --no-open | off | Don't open browser automatically | | -r, --report | off | Output ObservationReport instead of raw events | | --similarity <n> | 0.8 | Sentence matching threshold (0–1) | | --config <path> | — | JSON file with analyzer config overrides | | --api <url> | en.wikipedia.org | MediaWiki API base URL |

refract visualize

Export evidence graph as a diagram.

refract visualize <page> [options]

refract watch

Live polling daemon for new edits.

refract watch <page> [options]

refract mcp

Start MCP server for AI agent integration.

refract mcp

refract stream

Live stream of Wikipedia edits via EventStreams. Connects to Wikimedia's real-time edit feed and prints events as they happen.

refract stream [page] [options]

Filters out bot edits and non-main-namespace changes automatically. Press Ctrl+C to stop.

# Watch all edits on English Wikipedia
refract stream

# Watch a specific page
refract stream "COVID-19"

# Watch German Wikipedia
refract stream "COVID-19" --wiki dewiki

The stream provides revision metadata (ID, user, comment, timestamp) but not full revision content. Use refract analyze for full content analysis.

Global options

These options apply to most commands: