CLI reference
Every research-scan command, from its own --help output.
Every transcript below was captured from research-scan 0.5.1, published on PyPI
and run through uvx. Help boxes wrap to the terminal width; yours may wrap
differently.
There is no scan command. The pipeline is staged because it needs a model’s
judgement between stages — see Installation.
research-scan
Usage: research-scan [OPTIONS] COMMAND [ARGS]...
Verified evidence scans for a project brief. The agent reasons; this CLI retrieves.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --version Print the version and exit. ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮│ configure Set up credentials interactively, then prove they work. Alias: `setup`. ││ version Print the version, and what this install can actually do. ││ init Create a run directory and print the RunInfo the planning agent must respect. ││ retrieve Query every routed source, then dedup, filter, cap and write the screening batches. ││ expand Walk the citation graph out from every screened-relevant paper (§8.5). ││ shortlist Check that every candidate was screened, then order and cut for the reranker. ││ coverage Count how well each sub-criterion is covered, so the gap round has something to aim ││ at. ││ verify Check every ranked paper against the live record and record what did not match ││ (§10.5). ││ emit Apply the selection rules and render the deliverable (§10.4, §9.8). ││ eval Score a run against a curated golden topic, and merge an independent judge's scores ││ (§13). ││ doctor Invoke every source live (cache bypassed) and report readiness. Exit 3 if unusable. ││ completion Print the completion script for SHELL. Evaluate it, or write it where the shell ││ looks. ││ mcp Serve the scan pipeline as an MCP server. Four tools, the same ones the skill ││ drives. ││ schema Print the data contracts. `schema.py` is the source of truth for every file on disk. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯setup is a hidden alias for configure and does not appear in this list.
Setup
configure
Usage: research-scan configure [OPTIONS]
Set up credentials interactively, then prove they work. Alias: `setup`.
Writes ~/.config/research-scan/.env (0600, in a 0700 directory), merging into whatever is already there — comments and variables this command does not ask about are left alone. Safe to re-run: every variable shows its current state, Enter keeps it, typing replaces it. Ends by running `doctor`.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. [default: INFO] ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯doctor
Usage: research-scan doctor [OPTIONS]
Invoke every source live (cache bypassed) and report readiness. Exit 3 if unusable.
The default is a summary; `--verbose` is the per-check table with timings and paths. Whichever you pick, the checks and the exit code are the same.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --sources <str> Comma-separated subset of openalex,s2,crossref,arxiv,pubmed. Default: ││ all. ││ --verbose The full per-check table instead of the summary. ││ --json Machine-readable stdout. This is the CI/agent interface. ││ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. [default: INFO] ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯Sample output for all three modes is on Checking your setup.
version
Usage: research-scan version [OPTIONS]
Print the version, and what this install can actually do.
`--version` on the root stays the bare number for scripts that already parse it.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --json Machine-readable stdout. ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯completion
Usage: research-scan completion [OPTIONS] {SHELL}
Print the completion script for SHELL. Evaluate it, or write it where the shell looks.
bash eval "$(research-scan completion bash)" # add to ~/.bashrc zsh eval "$(research-scan completion zsh)" # add to ~/.zshrc fish research-scan completion fish > ~/.config/fish/completions/research-scan.fish
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮│ * SHELL <str> bash, zsh or fish. [required] │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯Pipeline stages
init
Usage: research-scan init [OPTIONS] {BRIEF}
Create a run directory and print the RunInfo the planning agent must respect.
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────╮│ * BRIEF <str> Path to a brief.md, or a question. [required] │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --slug <str> Run name. Default: derived from BRIEF. ││ --from <str> Window start, YYYY-MM. ││ --to <str> Window end, YYYY-MM. Default: today. ││ --top <int> Papers to emit. [default: 10] ││ --foundational <int> Out-of-window slots within --top. ││ [default: 2] ││ --domain <behavioral|cs|biomed|general> Routing domain. [default: general] ││ --profile <quick|standard|deep> quick (cheap) · standard · deep (widest). ││ Sets per-query depth, pool cap, ││ out-of-window total and whether the gap ││ round runs. ││ [default: standard] ││ --json Print RunInfo as JSON. ││ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. [default: INFO] ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯retrieve
Usage: research-scan retrieve [OPTIONS]
Query every routed source, then dedup, filter, cap and write the screening batches.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --run <str> Run directory. Default: ││ the newest. ││ --per-query <int> Hits per query per ││ source. ││ --max-candidates <int> Hard pool cap. ││ --sources <str> Comma-separated override ││ of the domain routing ││ map. ││ --include-preprints --no-include-preprints Keep preprints in the ││ pool. ││ [default: ││ include-preprints] ││ --include-all-types Keep paratext, errata ││ and datasets. ││ --round <int range> [1<=x<=2] 2 runs the gap round: ││ `queries.json.round2`, ││ appended. ││ [default: 1] ││ --json Machine-readable stdout. ││ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. ││ [default: INFO] ││ --no-cache Bypass the 7-day HTTP ││ cache. ││ --help Show this message and ││ exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯expand
Usage: research-scan expand [OPTIONS]
Walk the citation graph out from every screened-relevant paper (§8.5).
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --run <str> Run directory. Default: the newest. ││ --seeds <int> Max seeds to expand from. ││ --max-new <int> Cap on in-window additions. ││ --max-outside-window <int> Cap on out-of-window additions. ││ --round <int range> [1<=x<=2] 2 seeds the gap round from what the gap ││ queries found. ││ [default: 1] ││ --json Machine-readable stdout. ││ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. [default: INFO] ││ --no-cache Bypass the 7-day HTTP cache. ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯coverage
Usage: research-scan coverage [OPTIONS]
Count how well each sub-criterion is covered, so the gap round has something to aim at.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --run <str> Run directory. Default: the newest. ││ --gap-round Force the gap round whatever the profile and counts say. ││ --json Machine-readable stdout. ││ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. [default: INFO] ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯shortlist
Usage: research-scan shortlist [OPTIONS]
Check that every candidate was screened, then order and cut for the reranker.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --run <str> Run directory. Default: the newest. ││ --max-in-window <int> Cap on in-window rows. ││ --max-outside-window <int> Cap on out-of-window rows. ││ --json Machine-readable stdout. ││ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. [default: INFO] ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯verify
Usage: research-scan verify [OPTIONS]
Check every ranked paper against the live record and record what did not match (§10.5).
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --run <str> Run directory. Default: the newest. ││ --strict Require a 95 title match, not 90. ││ --json Machine-readable stdout. ││ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. [default: INFO] ││ --no-cache Bypass the 7-day HTTP cache. ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯emit
Usage: research-scan emit [OPTIONS]
Apply the selection rules and render the deliverable (§10.4, §9.8).
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --run <str> Run directory. Default: the newest. ││ --top <int> Papers to emit. ││ --foundational <int> Of --top, slots for out-of-window classics. ││ --contradicting <int> Slots reserved for counter-results, capped at half of ││ --top. 0 disables. ││ [default: 1] ││ --bib --no-bib Also write evidence.bib. [default: bib] ││ --json Machine-readable stdout. ││ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. [default: INFO] ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯Serving and inspection
mcp
Serves the scan pipeline as an MCP server — four tools, the same ones the skill drives.
research-scan mcpThe default transport is stdio: the server talks MCP on stdin and stdout and nothing else, which is what Claude Code, Claude Desktop and other local agent runners launch. No token is involved in this mode and none is read — the process is trusted because you started it. This is the mode the integration guides cover.
Run research-scan mcp --help for the remaining transport options, and read the
main repo’s
SECURITY.md
before serving beyond your own machine.
schema
Usage: research-scan schema [OPTIONS]
Print the data contracts. `schema.py` is the source of truth for every file on disk.
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ --name <str> One model, e.g. ScanSummary. Default: every model. ││ --md Render references/schemas.md instead of JSON. ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯eval
Usage: research-scan eval [OPTIONS]
Score a run against a curated golden topic, and merge an independent judge's scores (§13).
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮│ * --topic <str> Golden topic name, e.g. defaults-savings. [required] ││ --run <str> Run directory. Default: the newest. ││ --golden <str> Golden directory. Default: eval/golden. ││ --judge <str> Judge output to merge in. ││ --stage <str> `full` scores emit + rerank; `candidates` scores retrieval alone. ││ [default: full] ││ --json Machine-readable stdout. ││ --quiet Silence the stderr log. ││ --log-level <str> Stderr log level. [default: INFO] ││ --help Show this message and exit. │╰──────────────────────────────────────────────────────────────────────────────────────────────────╯The golden set lives in the main repo under eval/golden/. See
Measurements for what has been scored with it.
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
2 | A validation or usage failure. Every offending path is listed, not just the first. |
3 | A mandatory readiness check failed. |
Last updated Aug 21, 2026