CLI command reference
refract analyze
Analyze full edit history of a page. (wikihistory analyze also works.)
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 (~/.refract/cache.db) |
| --pages-file <path> | — | Batch file of page titles (one per line) |
| --api <url> | en.wikipedia.org | MediaWiki API base URL |
| --cache-dir <path> | ~/.refract | 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. (wikihistory claim also works.)
refract claim <page> [options]
| Flag | Default | Description |
|---|---|---|
page |
required (positional) | Page title |
-t, --text <text> |
required | Claim text to track |
-c, --cache |
off | Cache revisions in SQLite |
--api <url> |
en.wikipedia.org |
MediaWiki API base URL |
refract cron
One-shot re-observation for cron scheduling. (wikihistory cron also works.)
refract cron <pages-file> [options]
| Flag | Default | Description |
|---|---|---|
pages-file |
required (positional) | Batch file of page titles (one per line) |
-i, --interval <hrs> |
from last observation | Lookback window in hours |
--notify-slack |
off | Send Slack notification on changes |
--notify-email |
off | Send email notification on changes |
--notify-webhook <u> |
— | Send generic webhook POST on changes |
--api <url> |
en.wikipedia.org |
MediaWiki API base URL |
refract diff
Cross-wiki comparison (2+ wikis). (wikihistory diff also works.)
refract diff <topic> [options]
| Flag | Default | Description |
|---|---|---|
topic |
required (positional) | Page title to compare across wikis |
--wiki-a <url> |
required | First wiki API URL |
--wiki-b <url> |
required | Second wiki API URL |
--wiki-c <url> |
optional | Third wiki API URL |
-d, --depth <d> |
detailed |
Analysis depth. See depth levels |
refract eval
Run the evaluation harness. (wikihistory eval also works.)
refract eval [options]
| Flag | Default | Description |
|---|---|---|
--page <title> |
— | Run only for a specific page |
--ground-truth <path|builtin> |
— | Validate against ground truth labels |
refract classify
Classify a single observation boundary using an inference provider. (wikihistory classify also works.)
refract classify <boundary> --input '<json>'
| Boundary | What it decides | Default | Model question |
|---|---|---|---|
revert |
Is this edit comment a revert? | 6 regex patterns | "Does this comment indicate a revert?" |
sentence_similarity |
Are these two sentences the same claim? | Word-overlap ratio (0.8) | "Are these the same claim?" |
heuristic |
What kind of edit is this? | Size thresholds + comment patterns | "Classify this edit by type" |
template_signal |
What policy signal does this template represent? | Name-to-type lookup | "What signal does this template represent?" |
activity_spike |
Is this day's talk activity meaningful? | 3x moving average | "Is this a meaningful spike?" |
| Flag | Default | Description |
|---|---|---|
--input <json> |
— | Input data as JSON string |
--api-key <key> |
env REFRACT_INFERENCE_API_KEY |
API key for inference provider |
--endpoint <url> |
env REFRACT_INFERENCE_ENDPOINT |
OpenAI-compatible endpoint (OpenAI, DeepSeek, Ollama, etc.) |
--model <name> |
gpt-4o-mini |
Model name |
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. (wikihistory export also works.)
refract export <page> [options]
| Flag | Default | Description |
|---|---|---|---|
| page | required (positional) | Page title |
| -f, --format <fmt> | json | Output format: json, csv, ndjson, html |
| --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. (wikihistory explore also works.)
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. (wikihistory visualize also works.)
refract visualize <page> [options]
| Flag | Default | Description |
|---|---|---|
page |
required (positional) | Page title |
-f, --format <fmt> |
mermaid |
Output format: mermaid, dot |
--all |
off | Show all event types (default: claim events only) |
--api <url> |
en.wikipedia.org |
MediaWiki API base URL |
refract watch
Live polling daemon for new edits. (wikihistory watch also works.)
refract watch <page> [options]
| Flag | Default | Description |
|---|---|---|
page |
required (positional) | Page title |
-s, --section <name> |
— | Watch a specific section only |
-i, --interval <ms> |
60000 |
Poll interval in milliseconds |
--api <url> |
en.wikipedia.org |
MediaWiki API base URL |
refract mcp
Start MCP server for AI agent integration. (wikihistory mcp also works.)
refract mcp
Global options
These options apply to most commands:
| Flag | Description |
|---|---|
--api <url> |
MediaWiki API base URL (default: en.wikipedia.org) |
--cache-dir <path> |
Cache directory path (default: ~/.refract) |
--api-key <token> |
API key for bearer token auth |
--api-user <user> |
Username for basic auth |
--api-password <pass> |
Password for basic auth |