Configuration

Research Scan reads scholarly APIs, and one of them requires a key. configure asks for each credential, shows what is already set, writes the file with restrictive permissions, and finishes by running doctor.

research-scan configure          # `setup` is an alias for the same command

Keys are read without echo. Re-running is safe: every variable shows its current value masked to the last four characters, Enter keeps it, typing replaces it. Anything already in the file that configure does not ask about — comments included — is left exactly as it was.

What it asks for

Only OPENALEX_API_KEY is required. The others raise a rate limit, and the tool tells you which you are missing rather than failing quietly.

NCBI_API_KEY does not add a source. PubMed is routed for biomed but is not built — no retrieval adapter exists — so a biomed scan runs on OpenAlex and Semantic Scholar and records PubMed as unavailable in manifest.json whether or not you set the key. Setting it changes the rate limit on NCBI requests, and today the only one is doctor’s endpoint probe. It is documented because the package reads it, not because it adds results.

In a script or a container

If stdin is not a terminal, configure prints the file it would write and exits 2 rather than hanging — the behaviour you want in a Dockerfile or a provisioning script.

research-scan configure < /dev/null

stdin is not a terminal, so there is nothing to prompt. Write ~/.config/research-scan/.env:

  OPENALEX_API_KEY=   # required — the primary source; free key at openalex.org
  OPENALEX_MAILTO=    # optional — your email; raises OpenAlex to 5 req/s, Crossref polite
  S2_API_KEY=         # optional — arrives by email — skip it and re-run configure later
  NCBI_API_KEY=       # optional — biomedical topics only

Then run: research-scan doctor

Where configuration lives

configure writes ~/.config/research-scan/.env with mode 0600 inside a 0700 directory, using an atomic write.

Precedence runs in one direction: the process environment beats ~/.config/research-scan/.env, which beats a repo-local ./.env. So exporting a variable for a single command always wins, without editing a file.

Credentials are read in exactly one place in the codebase, which is what lets the tool redact every secret before anything is logged or cached. See the configuration reference for the full variable list.

Verify

research-scan doctor

configure exits with doctor’s exit code, so a successful configure that ends in a failing check still tells you so.