Configuration reference
Every environment variable, every path, and the precedence rule between them.
Research Scan reads configuration from the environment and from a .env file. One
module in the package does that reading, which is what allows every secret to be
redacted before anything is logged or cached.
Precedence
process environment > ~/.config/research-scan/.env > ./.envExporting a variable for a single command always wins, without editing a file.
Credentials
These are treated as secrets: masked in every output, redacted from logs and from the HTTP cache.
| Variable | Required | Needed for |
|---|---|---|
OPENALEX_API_KEY | Yes | OpenAlex, the primary source. doctor exits 3 without it. |
S2_API_KEY | No | Semantic Scholar. Search and citation-graph expansion work without it, throttled to roughly a third of the rate; doctor warns. |
NCBI_API_KEY | No | PubMed only: 10 req/s instead of 3. |
Public settings
Not secrets, and shown in full in diagnostic output.
| Variable | What it does |
|---|---|
OPENALEX_MAILTO | Your email. Raises OpenAlex to 5 req/s and joins the Crossref polite pool. Strongly recommended. |
RESEARCH_SCAN_RUN | The run directory to operate on, instead of the newest. |
RESEARCH_SCAN_MCP_DATA | Where the MCP adapter keeps run directories. Defaults to ~/.local/share/research-scan-mcp/runs/, one directory per scan id. |
OPENALEX_MAILTO is the one people skip and then wonder about rate limits. It
costs nothing and multiplies your throughput.
Paths
| Path | What it is |
|---|---|
~/.config/research-scan/.env | The credential store. Mode 0600, in a 0700 directory. |
~/.cache/research-scan/http.sqlite | The 7-day HTTP cache. |
./.env | A repo-local override, lowest precedence. |
research/scans/<YYYY-MM-DD>-<slug>/ | Run directories, relative to the working directory. |
~/.local/share/research-scan-mcp/runs/<scan_id>/ | Run directories under the MCP adapter. |
How the file is written
research-scan configure writes ~/.config/research-scan/.env through a
temporary file and an atomic replace, and merges rather than overwrites:
variables it does not ask about, and comments, survive untouched.
To write it by hand instead, .env.example in the main repo is the template.
Reading the current state
research-scan doctor --verboseShows every credential, masked to its last four characters, with the origin of
each value — user-config, local-env or the process environment — plus the
resolved paths. doctor --json carries the same under keys and paths.
The HTTP cache
Responses are cached for seven days in ~/.cache/research-scan/http.sqlite. Every
network-touching stage takes --no-cache to bypass it.
doctor always bypasses the cache: a readiness check that could pass on
yesterday’s cached response would not be a readiness check.
Deleting the file is safe. It will be recreated.
Last updated Aug 21, 2026