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. Everything else raises a rate limit or adds a source, and the tool tells you which you are missing rather than failing quietly.

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.