---
title: CLI reference
description: Every Sci RAG Kit command, argument, option, type, and default, generated from the live Typer application.
---

# CLI reference

<!-- Generated by scripts/render_cli_docs.py; do not edit by hand. -->

This page is generated from `src/sci_rag/cli/main.py`. Run
`make docs-reference` after changing the Typer command surface.
All commands run from inside the repository so relative settings,
migrations, `domain/`, and data paths resolve predictably.

## Command map

| Command | Purpose |
|---|---|
| `sci-rag ingest` | Ingest documents: parse, chunk, embed, and store them. |
| `sci-rag retrieve` | Inspect retrieval: see what each layer contributed and what won. |
| `sci-rag answer` | Generate a grounded answer with numbered citations. |
| `sci-rag stats` | What is in the knowledge base right now. |
| `sci-rag serve` | Serve the REST API (/v1, docs at /docs) and the MCP server (/mcp). |
| `sci-rag mcp` | Run the MCP server over stdio (for local agents like Claude Code). Add it to an agent with, for example: claude mcp add sci-rag -- uv run --directory /path/to/your/repo sci-rag mcp |
| `sci-rag doctor` | Diagnose the environment: config, domain, database, corpus, credentials. |
| `sci-rag init` | Specialize this checkout for your own domain. Asks about your project, credentials, ontology, corpus, and stack, then rewrites the configuration files in place. Everything it writes is a file you are meant to keep editing afterwards; nothing is generated code. |
| `sci-rag db` | Database schema management. |
| `sci-rag db upgrade` | Create or upgrade the database schema (runs the Alembic migrations). |
| `sci-rag graph` | Build the knowledge graph: extract entities, then detect communities. |
| `sci-rag graph extract` | Extract entities and relationships from ingested chunks (needs an LLM). |
| `sci-rag graph communities` | Cluster the graph and write LLM summaries (rebuilds all communities). |
| `sci-rag graph citations` | Build corpus-local citation pointers from cached Crossref metadata. |
| `sci-rag graph resolve-entities` | Resolve duplicate graph entities conservatively and audit every merge. |
| `sci-rag graph gc` | Garbage-collect the graph: evidence-less entities, dangling relationships, communities whose members no longer resolve. |
| `sci-rag eval` | Measure your RAG honestly: retrieval metrics, layer ablations, judged answers. |
| `sci-rag eval retrieval` | Score retrieval against your seed questions (and per-layer ablations). |
| `sci-rag eval answers` | Generate answers for every seed question and grade them with the blind judge. |
| `sci-rag eval diff` | Compare two eval runs: per-question rank moves and paired metric deltas. Deltas are B minus A. Run it after any retrieval-affecting change to see whether the improvement is real or inside the noise. |
| `sci-rag eval calibrate` | Compare human labels against the judge's scores: Cohen's kappa per dimension. Appends a calibration section to the report's markdown (report.md) and writes calibration.json next to it, so the kappa travels with the eval numbers it qualifies. |
| `sci-rag embed` | Embedding maintenance: find and re-embed rows left behind by a model upgrade. |
| `sci-rag embed reindex` | Re-embed chunks and community summaries stamped with a retired embedder version. A dimension change is refused outright: that is a schema migration plus a full re-ingest, never a reindex. |
| `sci-rag corpus` | Corpus lifecycle: delete documents cleanly, snapshot what you have. |
| `sci-rag corpus enrich` | Add Crossref citation, journal, and retraction metadata to the corpus. |
| `sci-rag corpus delete` | Delete documents and every graph trace of their evidence. Chunks cascade, entity evidence arrays are scrubbed, relationships evidenced by the documents go, and communities that aggregated that evidence are dropped (rebuild them with `sci-rag graph communities`). Run `sci-rag graph gc` afterwards to sweep entities left with no evidence at all. |
| `sci-rag corpus snapshot` | Write a named corpus fingerprint manifest under data/snapshots/. Records counts, per-document content hashes, embedding versions, the git commit, and a single corpus digest. Reference it from eval runs with --snapshot NAME so reported numbers stay tied to exactly the corpus that produced them. |
| `sci-rag campaign` | Discover, build, and screen legal, resumable scientific-document campaigns. |
| `sci-rag campaign discover` | Discover a deduplicated DOI list and save resumable state. |
| `sci-rag campaign build` | Resolve rights, download direct OA PDFs, and write an ingest manifest. |
| `sci-rag campaign screen` | Screen discovered abstracts and queue uncertain rows for human review. |
| `sci-rag campaign review` | Walk pending screening rows and append explicit human decisions. |

## `sci-rag ingest`

Ingest documents: parse, chunk, embed, and store them.

```console
$ sci-rag ingest [OPTIONS] [PATH]
```

### Arguments

| Name | Type | Default | Description |
|---|---|---|---|
| `PATH` | path | unset | Folder of documents to ingest (PDF, Markdown, or plain text). |

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--manifest, -m` | path | unset | A JSONL corpus manifest with per-document metadata. |
| `--source` | text | local | Source label recorded on documents ingested from a folder. |
| `--no-docling` | boolean | false | Skip Docling even if installed (use the pypdf fallback). |
| `--chunk-tokens` | integer | 800 | Target tokens per chunk. |
| `--overlap-tokens` | integer | 150 | Overlap tokens between chunks. |

## `sci-rag retrieve`

Inspect retrieval: see what each layer contributed and what won.

```console
$ sci-rag retrieve [OPTIONS] QUERY
```

### Arguments

| Name | Type | Default | Description |
|---|---|---|---|
| `QUERY` | text | required | The question to search for. |

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--profile` | text | deep | Retrieval profile: interactive, deep, or auto (router decides). |
| `--limit` | integer | 8 | How many fused results to return. |
| `--license` | text | unset | Comma-separated license allowlist (e.g. public,open_commercial). |
| `--source` | text | unset | Comma-separated source allowlist. |
| `--year-min` | integer | unset | Earliest publication year to include. |
| `--year-max` | integer | unset | Latest publication year to include. |
| `--author` | text | unset | Comma-separated author allowlist (exact strings). |
| `--journal` | text | unset | Comma-separated journal allowlist. |
| `--exclude-doi` | text | unset | Comma-separated DOIs to drop. |
| `--explain-routing` | boolean | false | Print what the auto router decides for this query (and why) before retrieving. |

## `sci-rag answer`

Generate a grounded answer with numbered citations.

```console
$ sci-rag answer [OPTIONS] QUERY
```

### Arguments

| Name | Type | Default | Description |
|---|---|---|---|
| `QUERY` | text | required | The question to answer. |

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--profile` | text | deep | Retrieval profile: interactive or deep. |
| `--limit` | integer | 8 | How many sources to give the model. |
| `--license` | text | unset | - |
| `--source` | text | unset | - |
| `--year-min` | integer | unset | Earliest publication year to include. |
| `--year-max` | integer | unset | Latest publication year to include. |
| `--author` | text | unset | Comma-separated author allowlist (exact strings). |
| `--journal` | text | unset | Comma-separated journal allowlist. |
| `--exclude-doi` | text | unset | Comma-separated DOIs to drop. |
| `--include-retracted` | boolean | false | Deliberately allow known retracted papers as answer evidence. |
| `--compression, --no-compression` | boolean | unset | Override contextual source compression (domain default when omitted). |

## `sci-rag stats`

What is in the knowledge base right now.

```console
$ sci-rag stats [OPTIONS]
```

## `sci-rag serve`

Serve the REST API (/v1, docs at /docs) and the MCP server (/mcp).

```console
$ sci-rag serve [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--host` | text | unset | Bind address (default from settings). |
| `--port` | integer | unset | Port (default from settings; Cloud Run sets PORT). |

## `sci-rag mcp`

Run the MCP server over stdio (for local agents like Claude Code). Add it to an agent with, for example: claude mcp add sci-rag -- uv run --directory /path/to/your/repo sci-rag mcp

```console
$ sci-rag mcp [OPTIONS]
```

## `sci-rag doctor`

Diagnose the environment: config, domain, database, corpus, credentials.

```console
$ sci-rag doctor [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--probe` | boolean | false | Also make one tiny live embedding and generation call. |

## `sci-rag init`

Specialize this checkout for your own domain. Asks about your project, credentials, ontology, corpus, and stack, then rewrites the configuration files in place. Everything it writes is a file you are meant to keep editing afterwards; nothing is generated code.

```console
$ sci-rag init [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--target` | path | . | The checkout to specialize. Defaults to the current directory. |
| `--defaults` | boolean | false | Take every default without asking. Useful in CI. |
| `--answers-file` | path | unset | A YAML file of answers, for reproducible generation. Unanswered questions take their default. |
| `--dry-run` | boolean | false | Show what would change without writing anything. |

## `sci-rag db`

Database schema management.

```console
$ sci-rag db [OPTIONS] COMMAND [ARGS]...
```

## `sci-rag db upgrade`

Create or upgrade the database schema (runs the Alembic migrations).

```console
$ sci-rag db upgrade [OPTIONS]
```

## `sci-rag graph`

Build the knowledge graph: extract entities, then detect communities.

```console
$ sci-rag graph [OPTIONS] COMMAND [ARGS]...
```

## `sci-rag graph extract`

Extract entities and relationships from ingested chunks (needs an LLM).

```console
$ sci-rag graph extract [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--batch-size` | integer | 10 | Chunks per extraction call. |
| `--all` | boolean | false | Re-read every chunk, not just unprocessed ones. |
| `--max-chunks` | integer | unset | Stop after this many chunks (for trials). |

## `sci-rag graph communities`

Cluster the graph and write LLM summaries (rebuilds all communities).

```console
$ sci-rag graph communities [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--min-size` | integer | 3 | Smallest cluster worth summarizing. |

## `sci-rag graph citations`

Build corpus-local citation pointers from cached Crossref metadata.

```console
$ sci-rag graph citations [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--dry-run, --apply` | boolean | true | Preview by default; --apply reconciles cached Crossref references. |

## `sci-rag graph resolve-entities`

Resolve duplicate graph entities conservatively and audit every merge.

```console
$ sci-rag graph resolve-entities [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--dry-run, --apply` | boolean | true | Preview merges by default; --apply writes tombstones and audit receipts. |
| `--no-llm` | boolean | false | Skip borderline pairs instead of asking the configured LLM. |
| `--threshold` | float range | 0.92 | Minimum same-type similarity for an automatic fuzzy merge. |
| `--llm-threshold` | float range | 0.8 | Minimum similarity for a borderline pair to be reviewed by the LLM. |

## `sci-rag graph gc`

Garbage-collect the graph: evidence-less entities, dangling relationships, communities whose members no longer resolve.

```console
$ sci-rag graph gc [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--dry-run, --apply` | boolean | true | --dry-run (default) reports what would go; --apply removes it. |

## `sci-rag eval`

Measure your RAG honestly: retrieval metrics, layer ablations, judged answers.

```console
$ sci-rag eval [OPTIONS] COMMAND [ARGS]...
```

## `sci-rag eval retrieval`

Score retrieval against your seed questions (and per-layer ablations).

```console
$ sci-rag eval retrieval [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--questions` | path | unset | Seed questions JSONL. |
| `--limit` | integer | 10 | Results retrieved per question. |
| `--ablation` | boolean | false | Run every layer-ablation config, not just full_deep. |
| `--condition` | text | unset | Label an established corpus condition (currently: resolved_entities). |
| `--snapshot` | text | unset | Record this corpus snapshot name in the report. |

## `sci-rag eval answers`

Generate answers for every seed question and grade them with the blind judge.

```console
$ sci-rag eval answers [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--questions` | path | unset | Seed questions JSONL. |
| `--profile` | text | deep | Retrieval profile for answer generation. |
| `--limit` | integer | 8 | Sources per answer. |
| `--judge-model` | text | unset | Judge model spec, 'model' or 'provider:model'. Overrides SCI_RAG_JUDGE_MODEL. |
| `--snapshot` | text | unset | Record this corpus snapshot name in the report. |
| `--compressed` | boolean | false | Enable contextual source compression for this answers-eval condition. |

## `sci-rag eval diff`

Compare two eval runs: per-question rank moves and paired metric deltas. Deltas are B minus A. Run it after any retrieval-affecting change to see whether the improvement is real or inside the noise.

```console
$ sci-rag eval diff [OPTIONS] REPORT_A REPORT_B
```

### Arguments

| Name | Type | Default | Description |
|---|---|---|---|
| `REPORT_A` | path | required | Baseline report.json (or its run directory). |
| `REPORT_B` | path | required | Comparison report.json (or its run directory). |

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--config` | text | unset | Diff only this ablation config (default: every common config). |
| `--output` | path | unset | Also write the markdown diff to this path. |

## `sci-rag eval calibrate`

Compare human labels against the judge's scores: Cohen's kappa per dimension. Appends a calibration section to the report's markdown (report.md) and writes calibration.json next to it, so the kappa travels with the eval numbers it qualifies.

```console
$ sci-rag eval calibrate [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--labels` | path | required | Human labels (labels.jsonl). |
| `--report` | path | unset | Answers report.json (or its run directory) to calibrate against. Defaults to the newest answers run under eval_results/. |
| `--output` | path | unset | Also write the calibration markdown to this path. |

## `sci-rag embed`

Embedding maintenance: find and re-embed rows left behind by a model upgrade.

```console
$ sci-rag embed [OPTIONS] COMMAND [ARGS]...
```

## `sci-rag embed reindex`

Re-embed chunks and community summaries stamped with a retired embedder version. A dimension change is refused outright: that is a schema migration plus a full re-ingest, never a reindex.

```console
$ sci-rag embed reindex [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--dry-run, --apply` | boolean | true | --dry-run (default) reports what is stale; --apply re-embeds it. |
| `--batch-size` | integer | 32 | Rows re-embedded per batch (one commit per batch). |

## `sci-rag corpus`

Corpus lifecycle: delete documents cleanly, snapshot what you have.

```console
$ sci-rag corpus [OPTIONS] COMMAND [ARGS]...
```

## `sci-rag corpus enrich`

Add Crossref citation, journal, and retraction metadata to the corpus.

```console
$ sci-rag corpus enrich [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--mailto` | text | required | Contact email sent to Crossref's polite API pool. |
| `--dry-run` | boolean | false | List eligible DOI records without network calls or writes. |
| `--limit` | integer range | unset | Process at most this many documents. |

## `sci-rag corpus delete`

Delete documents and every graph trace of their evidence. Chunks cascade, entity evidence arrays are scrubbed, relationships evidenced by the documents go, and communities that aggregated that evidence are dropped (rebuild them with `sci-rag graph communities`). Run `sci-rag graph gc` afterwards to sweep entities left with no evidence at all.

```console
$ sci-rag corpus delete [OPTIONS] DOCUMENT_IDS...
```

### Arguments

| Name | Type | Default | Description |
|---|---|---|---|
| `DOCUMENT_IDS` | text, repeatable | required | Document id(s) to delete. |

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--yes, -y` | boolean | false | Skip the confirmation prompt. |

## `sci-rag corpus snapshot`

Write a named corpus fingerprint manifest under data/snapshots/. Records counts, per-document content hashes, embedding versions, the git commit, and a single corpus digest. Reference it from eval runs with --snapshot NAME so reported numbers stay tied to exactly the corpus that produced them.

```console
$ sci-rag corpus snapshot [OPTIONS] [NAME]
```

### Arguments

| Name | Type | Default | Description |
|---|---|---|---|
| `NAME` | text | unset | Snapshot name (default: UTC timestamp). |

## `sci-rag campaign`

Discover, build, and screen legal, resumable scientific-document campaigns.

```console
$ sci-rag campaign [OPTIONS] COMMAND [ARGS]...
```

## `sci-rag campaign discover`

Discover a deduplicated DOI list and save resumable state.

```console
$ sci-rag campaign discover [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--topic` | text | unset | Search topic for OpenAlex discovery. |
| `--doi-file` | file | unset | Text file with one DOI or DOI URL per line. |
| `--name` | text | unset | Campaign directory name (derived from the input when omitted). |
| `--mailto` | text | required | Contact email sent to OpenAlex and Crossref. |
| `--max-results` | integer range | 100 | Maximum total candidates for a topic campaign. |
| `--campaign-root` | directory | data/campaigns | Parent directory for campaign state. |

## `sci-rag campaign build`

Resolve rights, download direct OA PDFs, and write an ingest manifest.

```console
$ sci-rag campaign build [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--topic` | text | unset | Search topic for OpenAlex discovery. |
| `--doi-file` | file | unset | Text file with one DOI or DOI URL per line. |
| `--name` | text | unset | Campaign directory name (derived from the input when omitted). |
| `--mailto` | text | required | Contact email sent to OpenAlex, Crossref, and Unpaywall. |
| `--dry-run` | boolean | false | Resolve and report rights without downloading PDFs or writing a manifest. |
| `--max-results` | integer range | 100 | Maximum total candidates for a topic campaign. |
| `--max-pdf-mb` | integer range | 25 | Reject a PDF larger than this many MiB. |
| `--campaign-root` | directory | data/campaigns | Parent directory for campaign state, PDFs, and manifest. |

## `sci-rag campaign screen`

Screen discovered abstracts and queue uncertain rows for human review.

```console
$ sci-rag campaign screen [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--name` | text | required | Campaign directory name to screen. |
| `--criteria-file` | file | required | Plain-text inclusion and exclusion criteria. |
| `--confidence-threshold` | float range | 0.8 | Model confidence below this value requires human review. |
| `--batch-size` | integer range | 20 | Maximum abstracts in one model request. |
| `--campaign-root` | directory | data/campaigns | Parent directory containing campaign state. |

## `sci-rag campaign review`

Walk pending screening rows and append explicit human decisions.

```console
$ sci-rag campaign review [OPTIONS]
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `--name` | text | required | Campaign directory name to review. |
| `--campaign-root` | directory | data/campaigns | Parent directory containing campaign state. |

## Shell help is authoritative too

Run `uv run sci-rag COMMAND --help` for the same current command tree
in the terminal. The generated page is a browsing aid; Click remains
the parser that decides whether a concrete invocation is valid.
