CLI reference
Run these commands as uv run bibr … from a source checkout. 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 containing PDF/DOCX/XML files (use '-' for stdin) | |
--manifest |
JSONL manifest carrying per-file source identity and output identity | |
-o, --output |
Output path (file for single input, directory for batch) | |
--memory |
Memory management mode (default: auto-detected from system RAM and CUDA VRAM) | |
--ocr |
OCR backend (default: paddle, automatically tries Paddle runtimes before the explicit GLM fallback chain) | |
--ocr-url |
URL for external OCR server (default profile: Paddle; --ocr glm-http keeps GLM) | |
--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, citation linking, equations, and Crossref. Preserves document structure and preparsed native metadata. OCR still uses the selected backend, including cloud vision providers. |
--refs |
Reference parser: 'ner' (default) uses the local ModernBERT-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. 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. Modified rows get a consolidated_fields marker. 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 the per-text underscore region metadata (_bbox_2d, _font_size, _region_type, …; training/debug payload from output). 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. Exits 0. |
bibr batch
Process a corpus — manifest text files (one path per line, '#' comments), directories (recursive) or files — writing
| 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 ledger line is 'failed' |
--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 |
-v, --verbose |
False |
Enable verbose logging |
--memory |
Memory management mode (default: auto-detected from system RAM and CUDA VRAM) | |
--ocr |
OCR backend (default: paddle, automatically tries Paddle runtimes before the explicit GLM fallback chain) | |
--ocr-url |
URL for external OCR server (default profile: Paddle; --ocr glm-http keeps GLM) | |
--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, citation linking, equations, and Crossref. Preserves document structure and preparsed native metadata. OCR still uses the selected backend, including cloud vision providers. |
--refs |
Reference parser: 'ner' (default) uses the local ModernBERT-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. 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. Modified rows get a consolidated_fields marker. 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 the per-text underscore region metadata (_bbox_2d, _font_size, _region_type, …; training/debug payload from output). 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) | |
--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 |
--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 ModernBERT-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. One warm pipeline serves the whole session, so pipeline options are fixed at start via the flags below (a subset of 'bibr chew'). Requires the 'mcp' extra. Register with e.g.: claude mcp add bibr -- uv run bibr mcp
| Flag | Default | Description |
|---|---|---|
--ocr |
OCR backend (as for 'bibr chew') | |
--ocr-url |
URL for external OCR server (as for 'bibr chew') | |
--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 and CUDA VRAM) | |
--device |
Force compute device | |
-v, --verbose |
False |
Enable verbose logging (stderr) |
bibr doctor
validate your environment
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 |