# Configuration

Set up API credentials for Research Scan, and understand where configuration lives and which source wins.

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`](/getting-started/doctor/).

```bash
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

| Variable | Needed for |
|---|---|
| `OPENALEX_API_KEY` | OpenAlex, the primary source. **Required**; `doctor` exits 3 without it. |
| `OPENALEX_MAILTO` | Strongly recommended. Raises OpenAlex to 5 req/s and joins the Crossref polite pool. |
| `S2_API_KEY` | Recommended. Semantic Scholar search and citation-graph expansion work without it, throttled to roughly a third of the rate; `doctor` warns. |
| `NCBI_API_KEY` | Optional. PubMed only: 10 req/s instead of 3. |

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.

```bash
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.

| Path | What it is |
|---|---|
| `~/.config/research-scan/.env` | The credential store. |
| `~/.cache/research-scan/http.sqlite` | The 7-day HTTP cache. |
| `./.env` | A repo-local override, if you keep one. |

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](/reference/configuration/) for the full variable list.

## Verify

```bash
research-scan doctor
```

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