CLI reference

In a uv project (the Quickstart install or a source checkout), run these as uv run bibr …. Tables are generated from the CLI parser; a blank default usually means the command resolves a value from configuration or hardware at runtime. Use bibr chew paper.pdf --dry-run to preview the resolved processing plan.

bibr chew

extract metadata from papers (PDF, DOCX, XML, HTML, ePub)

Flag	Default	Description
input		Input file(s) or directory of PDF, DOCX, JATS XML, HTML or ePub files (use '-' for stdin)
--manifest		JSONL manifest carrying per-file source identity and output identity
-o, --output		Output path: a file for one input file, a directory for a directory, a glob or several inputs (batch)
--memory		Memory management mode (default: auto-detected from system RAM, CUDA VRAM and the LLM backend)
--ocr		OCR backend (default: paddle, automatically tries Paddle runtimes before the explicit GLM fallback chain)
--ocr-url		URL of an external OCR server. Connects as paddle-http unless --ocr (or, without --ocr, OCR_BACKEND) names a GLM backend, then glm-http; --ocr gemini, openai or anthropic ignores the URL
--ocr-model		Model path or served model name for OCR (custom aliases require --ocr-profile)
--ocr-profile		OCR model family for a custom --ocr-model alias
--llm		LLM backend: cloud, or a managed local server — 'local' auto-picks vllm-mlx/Rapid-MLX (Apple Silicon), llama.cpp (Windows/small CUDA), vLLM, or external LM Studio/llmster. Default: LLM_BACKEND setting (cloud).
--llm-provider		Override LLM_PROVIDER setting (ignored for managed local backends (--llm vllm/vllm-mlx/rapid-mlx/local))
--llm-model		Override LLM_MODEL setting (ignored for managed local backends (--llm vllm/vllm-mlx/rapid-mlx/local))
--crossref	False	Enable Crossref/resolver reference enrichment for this run (off by default; overrides CROSSREF_ENRICH=false)
--no-crossref	False	Disable Crossref reference enrichment for this run (overrides CROSSREF_ENRICH=true)
--no-equations	False	Disable equation extraction
--no-llm	False	Skip downstream LLM extraction, reference parsing, citation linking, equations, and Crossref. Preserves document structure, plus the metadata a JATS or HTML input already carries and JATS references; PDF and DOCX output has no authors or references. OCR still uses the selected backend, including cloud vision providers.
--refs		Reference parser: 'ner' (default) uses the local encoder-CRF model through ONNX Runtime or the optional PyTorch runtime. 'llm' parses references with the configured LLM in batches. 'llm-chunked' parses region-aligned chunks of the reference list. 'ref-llm' uses a dedicated fine-tuned reference endpoint with NER recovery. Choose segmentation separately with --ref-seg. 'off' skips references and their citation links while keeping core metadata, sections, and equations. Overrides REF_PARSE_STRATEGY.
--ref-seg		Reference SEGMENTATION strategy (orthogonal to --refs, which selects parsing): 'geom' (default) the local geometry GBM, cascading to region anchors then LLM then CRF when geometry is absent/unconfident; the geometry tier uses a text-layer PDF; 'region' segments by layout-region anchors (LLM→CRF fallback), covering scanned PDFs with no text layer; 'llm' anchor-emit with region→CRF fallback; 'crf' the local ModernBERT-CRF segmenter. Sets REF_SEG_STRATEGY.
--consolidate		Merge accepted Crossref match data (bib_match) into the bib table. Bare flag = 'fill' (only fills missing fields); 'replace' also overwrites disagreeing ones, but only from a match carrying the reference's printed DOI. The fields taken per row are listed in extraction.diagnostics.consolidation. No-op when enrichment is off (the default; see --crossref) or when no matches were found. Place after the input path (e.g. bibr chew paper.pdf --consolidate), or use --consolidate=replace.
--figure-images	False	Include base64-encoded figure images in output (off by default)
--regions, --include-regions	False	Include the extraction.regions debug payload (per-region layout: bbox, font, content, etc.). Off by default — not consumed by standard downstream tools like Metacheck.
--region-meta	False	Include extraction.text_regions: per-sentence layout features (bbox, font size, region type; training/debug payload). Off by default.
--pages		Page range to process (e.g., '1-5', '3')
--device		Force compute device
--batch-size	0	Files per chunk in batch processing (default: auto-detected from memory mode)
--preset		Apply a preset before processing (does not modify .env)
--compact	False	Compact JSON output (no indentation, for piping to jq or storage)
--paper-id		Paper ID for single file processing
-v, --verbose	False	Enable verbose logging
--dry-run	False	Resolve and print the full run plan (input files, OCR/LLM config, reference strategies, enrichment, memory mode, models that would need downloading, output destinations) without processing anything. No network calls, no model loads. Prints a Blockers section and exits 1 when missing inputs, failing preflights or an -o that cannot be written would fail the real run.

bibr batch

Process a corpus — manifest text files (one path per line, '#' comments), directories (recursive) or files — writing /.json per paper and an append-only /outcomes.jsonl ledger (one verdict line per attempt; a local run writes a 'started' line first). Re-running the same command resumes: papers whose latest verdict is 'ok' are skipped, failed ones too unless --retry-failed, everything runs again with --force. A paper that was interrupted, or refused by the serve's token, runs again anyway, and so does one that crashed or hit a service outage, until it has failed that way three times. Without --serve-url the corpus runs through one warm local pipeline in chunks of --batch-size (the 'bibr chew' options apply); with --serve-url papers go to a bibr serve async job API with adaptive concurrency. 'bibr batch report ' summarizes a ledger.

Flag	Default	Description
inputs		Manifest file(s), directories, or files — or 'report '
--out		Output directory (exports, outcomes.jsonl, run_info.json)
--limit	0	Process at most N papers this run (after resume filtering)
--shuffle	False	Randomize the order (the seed is recorded in run_info.json)
--seed		Shuffle seed (implies --shuffle)
--deadline		Stop submitting new papers after this time: ISO-8601 (2026-09-03T06:00:00Z; a naive timestamp is local time) or epoch seconds
--retry-failed	False	Also re-run papers whose latest verdict is 'failed' (without it, an interruption or a rejected token runs again anyway, and a crash or a service outage until the paper has failed that way three times)
--force	False	Re-run every paper, ignoring the ledger
--dry-run	False	Print the plan (inputs, resume counts, executor settings, output paths) without processing anything
--report	False	Only print the ledger report for --out (same as 'bibr batch report ')
--json	False	Print the report as JSON instead of a table
--no-tables	False	Do not write /tables/: the corpus as one Parquet file per table, rebuilt from every successful paper at the end of each run
-v, --verbose	False	Enable verbose logging
--memory		Memory management mode (default: auto-detected from system RAM, CUDA VRAM and the LLM backend)
--ocr		OCR backend (default: paddle, automatically tries Paddle runtimes before the explicit GLM fallback chain)
--ocr-url		URL of an external OCR server. Connects as paddle-http unless --ocr (or, without --ocr, OCR_BACKEND) names a GLM backend, then glm-http; --ocr gemini, openai or anthropic ignores the URL
--ocr-model		Model path or served model name for OCR (custom aliases require --ocr-profile)
--ocr-profile		OCR model family for a custom --ocr-model alias
--llm		LLM backend: cloud, or a managed local server — 'local' auto-picks vllm-mlx/Rapid-MLX (Apple Silicon), llama.cpp (Windows/small CUDA), vLLM, or external LM Studio/llmster. Default: LLM_BACKEND setting (cloud).
--llm-provider		Override LLM_PROVIDER setting (ignored for managed local backends (--llm vllm/vllm-mlx/rapid-mlx/local))
--llm-model		Override LLM_MODEL setting (ignored for managed local backends (--llm vllm/vllm-mlx/rapid-mlx/local))
--crossref	False	Enable Crossref/resolver reference enrichment for this run (off by default; overrides CROSSREF_ENRICH=false)
--no-crossref	False	Disable Crossref reference enrichment for this run (overrides CROSSREF_ENRICH=true)
--no-equations	False	Disable equation extraction
--no-llm	False	Skip downstream LLM extraction, reference parsing, citation linking, equations, and Crossref. Preserves document structure, plus the metadata a JATS or HTML input already carries and JATS references; PDF and DOCX output has no authors or references. OCR still uses the selected backend, including cloud vision providers.
--refs		Reference parser: 'ner' (default) uses the local encoder-CRF model through ONNX Runtime or the optional PyTorch runtime. 'llm' parses references with the configured LLM in batches. 'llm-chunked' parses region-aligned chunks of the reference list. 'ref-llm' uses a dedicated fine-tuned reference endpoint with NER recovery. Choose segmentation separately with --ref-seg. 'off' skips references and their citation links while keeping core metadata, sections, and equations. Overrides REF_PARSE_STRATEGY.
--ref-seg		Reference SEGMENTATION strategy (orthogonal to --refs, which selects parsing): 'geom' (default) the local geometry GBM, cascading to region anchors then LLM then CRF when geometry is absent/unconfident; the geometry tier uses a text-layer PDF; 'region' segments by layout-region anchors (LLM→CRF fallback), covering scanned PDFs with no text layer; 'llm' anchor-emit with region→CRF fallback; 'crf' the local ModernBERT-CRF segmenter. Sets REF_SEG_STRATEGY.
--consolidate		Merge accepted Crossref match data (bib_match) into the bib table. Bare flag = 'fill' (only fills missing fields); 'replace' also overwrites disagreeing ones, but only from a match carrying the reference's printed DOI. The fields taken per row are listed in extraction.diagnostics.consolidation. No-op when enrichment is off (the default; see --crossref) or when no matches were found. Place after the input path (e.g. bibr chew paper.pdf --consolidate), or use --consolidate=replace.
--figure-images	False	Include base64-encoded figure images in output (off by default)
--regions, --include-regions	False	Include the extraction.regions debug payload (per-region layout: bbox, font, content, etc.). Off by default — not consumed by standard downstream tools like Metacheck.
--region-meta	False	Include extraction.text_regions: per-sentence layout features (bbox, font size, region type; training/debug payload). Off by default.
--pages		Page range to process (e.g., '1-5', '3')
--device		Force compute device
--batch-size	0	Files per chunk in batch processing (default: auto-detected from memory mode)
--preset		Apply a preset before processing (does not modify .env)
--serve-url		Base URL of a bibr serve — selects the remote executor
--token		Bearer token (default: AUTH_API_KEY or BIBR_SERVE_TOKEN from the environment, else AUTH_API_KEY from .env)
--allow-insecure-http	False	Send the bearer token over plain http:// to a public host. Loopback and private-network hosts (LAN, tailnet, single-label names) never need it; plain http to a LAN host is allowed with a warning.
--concurrency	2	Initial number of jobs in flight (default: 2)
--min-concurrency	1	In-flight floor the runner drops to on a 429 (default: 1)
--max-concurrency	4	In-flight ceiling it grows back to after successes (default: 4)
--poll-timeout	2400.0	Per-paper wall clock for a job to finish, in seconds (default: 2400)
--poll-interval	4.0	Seconds between job status polls (default: 4)
--retries	3	Retries per paper for transient failures — 502/503/504, connection errors, a job failed by an upstream OCR/LLM outage (default: 3)
--ready-timeout	900.0	Seconds to wait for GET /ready before giving up (default: 900)
--form	[]	Extra multipart form field for POST /papers/jobs (repeatable)

bibr setup

interactive setup wizard

The wizard handles its own options. Use bibr setup --advanced for the detailed provider/backend picker and bibr setup --help for its full help. See Quickstart.

bibr serve

start the HTTP API (see 'bibr serve --help')

The server handles --host and --port in its own parser. Run bibr serve --help for their defaults. See Deployment for binding, authentication, and environment settings.

bibr demo

bibr demo — interactive scientific paper metadata extraction

Flag	Default	Description
--host	'127.0.0.1'	Host to bind to
--port	7860	Port to bind to
--share	False	Create a public Gradio share link
--allow-unauthenticated	False	Allow --share or a non-loopback --host without GRADIO_PASSWORD. Anyone who reaches the demo can then process papers on your LLM quota.
--log-level	'info'	Log level
--ocr		OCR backend (default: from .env or auto-detected)
--memory		Memory mode (default: PIPELINE_MEMORY_MODE from .env, else auto-detected)
--llm		LLM backend: cloud, or a managed local server. 'local' auto-picks vllm-mlx/Rapid-MLX, llama.cpp, or vLLM for this machine.
--refs		Reference extraction strategy: 'ner' (default) parses each reference with the local encoder-CRF model (no per-reference LLM cost); 'llm' parses the bibliography with the configured LLM. Overrides REF_PARSE_STRATEGY for the demo.
--presets	False	Enable preset switching dropdown in the demo UI

bibr mcp

Run a Model Context Protocol server over stdio, exposing extraction as agent tools: chew_paper / load_paper register a paper, then get_metadata, get_sections, get_text, search_text, get_references, get_reference_citations, get_tables, get_figures and save_paper query the result in slices, and export_references / save_references give its reference list as CSL-JSON, BibTeX or RIS. One warm pipeline serves the whole session, so pipeline options are fixed at start via the flags below (a subset of 'bibr chew'). The file tools reach only the --allow-dir directories (default: the current directory). Requires the 'mcp' extra. Register with e.g.: claude mcp add bibr -- uv run bibr mcp

Flag	Default	Description
--allow-dir		Directory chew_paper, load_paper, save_paper and save_references may access, with symlinks resolved; repeat for several (default: the current directory)
--ocr		OCR backend (as for 'bibr chew')
--ocr-url		URL of an external OCR server (as for 'bibr chew': paddle-http unless --ocr or OCR_BACKEND names a GLM backend)
--ocr-model		Model path or served model name for OCR (as for 'bibr chew')
--ocr-profile		OCR model family for a custom --ocr-model alias
--llm		LLM backend (as for 'bibr chew')
--refs		Reference extraction strategy (as for 'bibr chew')
--ref-seg		Reference segmentation strategy (as for 'bibr chew')
--crossref	False	Enable Crossref reference enrichment (off by default; as for 'bibr chew')
--no-crossref	False	Disable Crossref reference enrichment (as for 'bibr chew')
--no-equations	False	Disable equation extraction
--no-llm	False	Skip downstream LLM extraction and Crossref; OCR remains active (as for 'bibr chew')
--consolidate		Merge accepted Crossref match data into the bib table (as for 'bibr chew')
--figure-images	False	Keep base64 figure images in stored exports (available via save_paper)
--memory		Memory management mode (default: auto-detected from system RAM, CUDA VRAM and the LLM backend)
--device		Force compute device
-v, --verbose	False	Enable verbose logging (stderr)

bibr ref-model

download the pinned fine-tuned reference adapter

bibr ref-model download

verify and install the reference adapter

Flag	Default	Description
--output		new adapter directory

bibr doctor

validate your environment

bibr tables

Write bibr JSON exports as one Parquet file per table — paper, author, affiliation, text, section, bib, xref, figure, table, eq, the match tables and the extraction processing lists — each row keyed by paper_id. Column types come from the export schema, so every file has the same columns however many papers it holds. Directories are searched recursively for *.json, leaving out what 'bibr chew -o' writes beside each export x.json (x.core.json, x.json.receipt.json, x.json.enrichment.json, _quarantine/); other JSON files and exports of another schema major are skipped.

Flag	Default	Description
inputs		Export JSON files or directories containing them
--out		Output directory for the .parquet files

bibr references

Write the references of bibr JSON exports as one file for a reference manager: CSL-JSON (Zotero, Mendeley, Pandoc), BibTeX or RIS. Values are as printed; what a reference does not print is filled from the record Crossref enrichment matched to it, but only when the reference check found the two agree (bib_check status matched). A note on each reference says what the check found when it is not matched, and names a retraction or withdrawal of its record. Cite keys are unique across the file. Directories are searched recursively for *.json as for 'bibr tables'.

Flag	Default	Description
inputs		Export JSON files or directories containing them
--format		Output format (default: from the output file's extension: .json, .bib, .ris)
-o, --out		Output file (default: standard output, which needs --format)
--prefer	'printed'	printed (default): only what the reference printed; record: a matched record's values first, gaps such as a missing DOI filled from it, with a note naming those values (needs --crossref results; a record whose check did not match is never used)
--no-check-note	False	Leave out the note saying what the reference check found

bibr inspect

Summarize a bibr JSON export: title/authors/DOI/paper type, section/sentence/table/figure/equation counts, reference and enrichment stats, the validation block, and per-model LLM token usage.

Flag	Default	Description
json_file		Path to a bibr extraction-output JSON file

bibr preset

Save / load named .env snapshots (LLM provider, OCR backend, rate limits, ...). Secrets like API keys are never written to preset files — they stay in .env.

bibr preset list

List all saved presets

bibr preset save

Save current .env as a named preset (excludes secrets by default)

Flag	Default	Description
name		Preset name
--force	False	Overwrite an existing preset without confirmation

bibr preset use

Apply a preset to .env

Flag	Default	Description
name		Preset name to activate

bibr preset deactivate

Remove the active-preset marker from .env (no other settings change)

bibr preset rm

Delete a preset

Flag	Default	Description
name		Preset name to delete
-y, --yes	False	Skip the deletion confirmation

bibr preset show

Show contents of a preset

Flag	Default	Description
name		Preset name to display

bibr preset diff

Compare a preset against current .env

Flag	Default	Description
name		Preset name to compare

bibr config

Show resolved settings and where each one comes from, locate your .env file, set individual values, or print an example .env template. Secret values (API keys, tokens, passwords) are always redacted in output — there is no flag to un-redact them.

bibr config show

Show current settings (non-default only, unless --all)

Flag	Default	Description
--sources	False	Show where each value comes from (env / .env path / default)
--all	False	Show every setting, including defaults

bibr config path

Show the .env file(s) bibr reads and whether they exist

bibr config set

Write one setting to .env

Flag	Default	Description
key		Setting name (env var), case-insensitive
value		Value to write

bibr config example

Print an example .env template

Flag	Default	Description
--full	False	Print every setting, grouped by section, commented out