CLI reference

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 draft	Draft the domain files you would otherwise hand-write. Every drafter can also print its prompt for any assistant (--print-prompt) and read the reply back (--from-file), so no API key is required.
sci-rag draft questions	Draft seed questions grounded in your own documents, and verify them.
sci-rag draft manifest	Read title, authors, year, and source off your documents. Rights stay yours.
sci-rag draft ontology	Redraft or refine the ontology against what your documents actually say.
sci-rag draft prompts	Reword a prompt for your field. Judge prompts are refused by name.

sci-rag ingest

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

$ 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.

$ 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.

$ 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.

$ sci-rag stats [OPTIONS]

sci-rag serve

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

$ 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

$ sci-rag mcp [OPTIONS]

sci-rag doctor

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

$ 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.

$ 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.

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

sci-rag db upgrade

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

$ sci-rag db upgrade [OPTIONS]

sci-rag graph

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

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

sci-rag graph extract

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

$ 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).

$ 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.

$ 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.

$ 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.

$ 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.

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

sci-rag eval retrieval

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

$ 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.

$ 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.

$ 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.

$ 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.

$ 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.

$ 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.

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

sci-rag corpus enrich

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

$ 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.

$ 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.

$ 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.

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

sci-rag campaign discover

Discover a deduplicated DOI list and save resumable state.

$ 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.

$ 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.

$ 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.

$ 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.

sci-rag draft

Draft the domain files you would otherwise hand-write. Every drafter can also print its prompt for any assistant (--print-prompt) and read the reply back (--from-file), so no API key is required.

$ sci-rag draft [OPTIONS] COMMAND [ARGS]...

sci-rag draft questions

Draft seed questions grounded in your own documents, and verify them.

$ sci-rag draft questions [OPTIONS]

Options

Option	Type	Default	Description
--count	integer	10	How many questions to ask for.
--folder	path	unset	Draft from documents in this folder instead of the ingested corpus.
--print-prompt	boolean	false	Print the rendered prompt and exit. Paste it into any assistant.
--from-file	path	unset	Read the model's reply from this file instead of calling a model.
--output	path	unset	Where to write the proposal. Defaults to .proposed.
--apply	boolean	false	Append the verified questions to the seed file.
--dry-run	boolean	false	Show what would be drafted without writing anything.
--repair, --no-repair	boolean	true	Ask the model once more to replace rows that failed grounding verification.

sci-rag draft manifest

Read title, authors, year, and source off your documents. Rights stay yours.

$ sci-rag draft manifest [OPTIONS]

Options

Option	Type	Default	Description
--folder	path	unset	Documents to describe. Defaults to /raw.
--print-prompt	boolean	false	Print the rendered prompt and exit. Paste it into any assistant.
--from-file	path	unset	Read the model's reply from this file instead of calling a model.
--output	path	unset	Where to write the proposal. Defaults to .proposed.
--manifest	path	unset	The manifest being drafted. Defaults to /corpus.jsonl.
--apply	boolean	false	Write the manifest itself instead of proposing one.
--dry-run	boolean	false	Show what would be drafted without writing anything.
--batch-size	integer	unset	Documents per model call. Defaults to 12.

sci-rag draft ontology

Redraft or refine the ontology against what your documents actually say.

$ sci-rag draft ontology [OPTIONS]

Options

Option	Type	Default	Description
--from-corpus	boolean	false	Redraft the ontology from real passages. The default when documents exist.
--refine	boolean	false	Show the model your ontology and ask only what it would add and remove.
--cold	boolean	false	Draft from the description alone, without reading any document.
--folder	path	unset	Draft from documents in this folder instead of the ingested corpus.
--print-prompt	boolean	false	Print the rendered prompt and exit. Paste it into any assistant.
--from-file	path	unset	Read the model's reply from this file instead of calling a model.
--output	path	unset	Where to write the proposal. Defaults to .proposed.
--apply	boolean	false	Write domain.yaml itself instead of proposing a file.
--dry-run	boolean	false	Show what would change without writing anything.

sci-rag draft prompts

Reword a prompt for your field. Judge prompts are refused by name.

$ sci-rag draft prompts [OPTIONS] NAME

Arguments

Name	Type	Default	Description
NAME	text	required	Which prompt to reword: entity_extraction or answer.

Options

Option	Type	Default	Description
--print-prompt	boolean	false	Print the rendered prompt and exit. Paste it into any assistant.
--from-file	path	unset	Read the model's reply from this file instead of calling a model.
--output	path	unset	Where to write the proposal. Defaults to .md.proposed.
--apply	boolean	false	Write the prompt file itself instead of proposing one.
--dry-run	boolean	false	Show the rewrite without writing anything.

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.