# CLI reference Every research-scan command, from its own --help output. Every transcript below was captured from `research-scan` 0.5.2, 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](/getting-started/installation/#there-is-no-one-shot-scan-command). ## `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 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 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 Stderr log level. [default: INFO] │ │ --help Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` Sample output for all three modes is on [Checking your setup](/getting-started/doctor/). ### `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 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 Path to a brief.md, or a question. [required] │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮ │ --slug Run name. Default: derived from BRIEF. │ │ --from Window start, YYYY-MM. │ │ --to Window end, YYYY-MM. Default: today. │ │ --top Papers to emit. [default: 10] │ │ --foundational Out-of-window slots within --top. │ │ [default: 2] │ │ --domain Routing domain. [default: general] │ │ --profile 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 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 Run directory. Default: │ │ the newest. │ │ --per-query Hits per query per │ │ source. │ │ --max-candidates Hard pool cap. │ │ --sources 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 [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 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 Run directory. Default: the newest. │ │ --seeds Max seeds to expand from. │ │ --max-new Cap on in-window additions. │ │ --max-outside-window Cap on out-of-window additions. │ │ --round [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 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 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 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 Run directory. Default: the newest. │ │ --max-in-window Cap on in-window rows. │ │ --max-outside-window Cap on out-of-window rows. │ │ --json Machine-readable stdout. │ │ --quiet Silence the stderr log. │ │ --log-level 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 Run directory. Default: the newest. │ │ --strict Require a 95 title match, not 90. │ │ --json Machine-readable stdout. │ │ --quiet Silence the stderr log. │ │ --log-level 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 Run directory. Default: the newest. │ │ --top Papers to emit. │ │ --foundational Of --top, slots for out-of-window classics. │ │ --contradicting 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 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. ```bash research-scan mcp ``` The 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](/integrations/mcp-clients/) cover. Run `research-scan mcp --help` for the remaining transport options, and read the main repo's [`SECURITY.md`](https://github.com/Synectic-Research/research-scan/blob/main/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 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 Golden topic name, e.g. defaults-savings. [required] │ │ --run Run directory. Default: the newest. │ │ --golden Golden directory. Default: eval/golden. │ │ --judge Judge output to merge in. │ │ --stage `full` scores emit + rerank; `candidates` scores retrieval alone. │ │ [default: full] │ │ --json Machine-readable stdout. │ │ --quiet Silence the stderr log. │ │ --log-level Stderr log level. [default: INFO] │ │ --help Show this message and exit. │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` The golden set lives in the main repo under `eval/golden/`. See [Measurements](/evaluation/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. |