CLI Reference

CLI Reference

xberg

Xberg document intelligence CLI

Options

Name	Flags	Type	Default	Description
log_level	--log-level	Option<String>		Set log level (trace, debug, info, warn, error). Overrides RUST_LOG env var.

xberg api

API utilities

xberg api schema

Output the OpenAPI schema (JSON)

xberg batch

Batch extract from multiple documents

Arguments

Name	Flags	Type	Default	Description
paths		Vec<PathBuf>		Paths to documents

Options

Name	Flags	Type	Default	Description
input	--input	Option<PathBuf>		JSON or JSONL manifest containing batch inputs.
input_format	--input-format	Option<BatchInputFormat>		Format for –input.
config	--config	Option<PathBuf>		Path to config file (TOML, YAML, or JSON). If not specified, searches for xberg.toml/yaml/json in current and parent directories.
no_config_discovery	--no-config-discovery	bool		Skip project and user config discovery and start from built-in defaults.
config_json	--config-json	Option<String>		Inline JSON configuration. Applied after config file but before individual flags.
config_json_base64	--config-json-base64	Option<String>		Base64-encoded JSON configuration. Useful for shell environments where quotes are problematic.
format	--format	WireFormat	json	Output format for CLI results (text or json).
output_dir	--output-dir	Option<PathBuf>		Directory where extracted image files are written (text/toon output only).
ocr	--ocr	Option<bool>		Enable or disable OCR. When true, configures an OCR backend (default: tesseract). When false, removes any OCR configuration.
ocr_backend	--ocr-backend	Option<String>		OCR backend to use when –ocr is enabled (tesseract, paddle-ocr, vlm, or candle-*).
ocr_language	--ocr-language	Option<String>		OCR language code. Tesseract uses ISO 639-3 (eng, fra, deu). PaddleOCR uses short codes (en, ch, french, korean).
force_ocr	--force-ocr	Option<bool>		Force OCR even if text extraction succeeds.
ocr_scanned_pages	--ocr-scanned-pages	bool		OCR pages that look like scans, keeping native text elsewhere.
scanned_min_confidence	--scanned-min-confidence	Option<f64>		Minimum scan confidence (0.0-1.0) for –ocr-scanned-pages. Default: 0.7.
disable_ocr	--disable-ocr	Option<bool>		Disable OCR entirely (even for images)
no_cache	--no-cache	Option<bool>		Disable extraction result caching.
ocr_auto_rotate	--ocr-auto-rotate	Option<bool>		Enable automatic image rotation before OCR based on detected orientation.
ocr_backend_options	--ocr-backend-options	Option<String>		JSON object of per-backend OCR options (e.g. {"layout_mode":"whole_page"}).
vlm_model	--vlm-model	Option<String>		VLM model for OCR (implies –ocr-backend vlm). Uses liter-llm routing format (e.g., “openai/gpt-4o”, “anthropic/claude-sonnet-4-20250514”).
vlm_api_key	--vlm-api-key	Option<String>		VLM API key for OCR
api_key	--api-key	Option<String>		Default LLM API key shared across every LLM-backed feature (VLM OCR, structured extraction, translation, classification, captioning, summarisation, NER). Lower precedence than --vlm-api-key and any api_key set in the loaded config file, higher precedence than the XBERG_LLM_API_KEY environment variable.
vlm_prompt	--vlm-prompt	Option<String>		Custom VLM OCR prompt template (Jinja2)
chunk	--chunk	Option<bool>		Enable or disable text chunking.
chunk_size	--chunk-size	Option<usize>		Maximum chunk size in characters.
chunk_overlap	--chunk-overlap	Option<usize>		Overlap between consecutive chunks in characters.
chunking_tokenizer	--chunking-tokenizer	Option<String>		Tokenizer model for token-based chunk sizing (e.g. “Xenova/gpt-4o”). Implicitly enables chunking. Requires the chunking-tokenizers feature.
content_format	--content-format	Option<ContentOutputFormatArg>		Content rendering format (plain, markdown, djot, html). Controls the format of extracted content.
output_format	--output-format	Option<ContentOutputFormatArg>		Content rendering format (DEPRECATED: use –content-format instead).
include_structure	--include-structure	Option<bool>		Include hierarchical document structure in results.
jupyter_cell_rendering	--jupyter-cell-rendering	Option<JupyterCellRenderingArg>		For Jupyter notebooks: render code cells as source, outputs, or both (default: both). Cells are never executed — outputs come only from those saved in the notebook.
quality	--quality	Option<bool>		Enable quality post-processing.
detect_language	--detect-language	Option<bool>		Enable language detection on extracted text.
layout	--layout	Option<bool>		Enable layout detection with default model settings (RT-DETR v2). Use --layout to enable or --layout false to explicitly disable.
layout_confidence	--layout-confidence	Option<f32>		Layout detection confidence threshold (0.0 - 1.0).
layout_strategy	--layout-strategy	Option<String>		Which pages the layout model runs on: always (default, every page) or auto (pre-screen each page and skip the model where it cannot help).
layout_table_model	--layout-table-model	Option<String>		Table structure model: tatr (default), slanet_wired, slanet_wireless, slanet_plus, slanet_auto, disabled.
use_layout_for_markdown	--use-layout-for-markdown	bool		Feed layout detection regions into the non-OCR markdown pipeline to improve heading/table/list/figure structure. Requires --layout to be enabled. Default: false.
acceleration	--acceleration	Option<AccelerationArg>		ONNX Runtime execution provider for model inference.
max_concurrent	--max-concurrent	Option<usize>		Maximum number of concurrent extractions in batch mode.
max_threads	--max-threads	Option<usize>		Cap all internal thread pools (Rayon, ONNX intra-op, batch semaphore).
extract_pages	--extract-pages	Option<bool>		Extract pages as a separate array in results.
page_markers	--page-markers	Option<bool>		Insert page marker comments into the main content string.
extract_images	--extract-images	Option<bool>		Enable image extraction from documents.
target_dpi	--target-dpi	Option<i32>		Target DPI for image normalisation (e.g. 150, 300, 600).
pdf_password	--pdf-password	Vec<String>		Password(s) for encrypted PDFs. Can be specified multiple times.
pdf_extract_images	--pdf-extract-images	Option<bool>		Extract images embedded in PDF pages.
pdf_extract_tables	--pdf-extract-tables	Option<bool>		Extract tables from PDF (pdf_oxide native grid + heuristic text-layer fallback). Default: true.
pdf_ocr_inline_images	--pdf-ocr-inline-images	Option<bool>		OCR extracted inline images and inject results into the document.
pdf_extract_metadata	--pdf-extract-metadata	Option<bool>		Extract PDF metadata (title, author, etc.).
pdf_backend	--pdf-backend	Option<String>		PDF extraction backend to use (currently only “pdf-oxide” is supported).
token_reduction	--token-reduction	Option<ReductionLevelArg>		Token reduction level (off, light, moderate, aggressive, maximum).
msg_codepage	--msg-codepage	Option<u32>		Windows codepage fallback for MSG files without codepage metadata. Common values: 1250 (Central European), 1251 (Cyrillic), 1252 (Western).
cache_namespace	--cache-namespace	Option<String>		Cache namespace for tenant isolation.
cache_ttl_secs	--cache-ttl-secs	Option<u64>		Per-request cache TTL in seconds (0 = skip cache).
html_theme	--html-theme	Option<String>		Built-in colour theme for styled HTML output (default, github, dark, light, unstyled). Implies –content-format html and enables the styled HTML renderer.
html_css	--html-css	Option<String>		Inline CSS string appended after the theme stylesheet in styled HTML output.
html_css_file	--html-css-file	Option<std::path::PathBuf>		Path to a CSS file loaded once and appended after the theme stylesheet in styled HTML output.
html_class_prefix	--html-class-prefix	Option<String>		CSS class prefix used on every emitted class name (default: “kb-”).
html_no_embed_css	--html-no-embed-css	bool		Suppress the embedded <style> block in styled HTML output.
file_configs	--file-configs	Option<PathBuf>		Path to a JSON file mapping file paths to per-file extraction config overrides. The JSON should be an object where keys are file paths and values are FileExtractionConfig objects. Example: {“doc1.pdf”: {“force_ocr”: true}, “doc2.pdf”: {“output_format”: “markdown”}}

xberg cache

Cache management operations

xberg cache clear

Clear the Xberg-managed cache (does not clear shared Hugging Face files)

Options

Name	Flags	Type	Default	Description
cache_dir	--cache-dir	Option<PathBuf>		Cache directory (default: .xberg in current directory)
format	--format	WireFormat	text	Output format (text or json)

xberg cache manifest

Output model manifest (expected model files, checksums, sizes)

Options

Name	Flags	Type	Default	Description
format	--format	WireFormat	json	Output format (text or json)

xberg cache stats

Show cache statistics

Options

Name	Flags	Type	Default	Description
cache_dir	--cache-dir	Option<PathBuf>		Cache directory (default: .xberg in current directory)
format	--format	WireFormat	text	Output format (text or json)

xberg cache warm

Download model artifacts eagerly

Options

Name	Flags	Type	Default	Description
cache_dir	--cache-dir	Option<PathBuf>		Xberg cache directory; for HF models, an explicit HF cache root
format	--format	WireFormat	text	Output format (text or json)
all_embeddings	--all-embeddings	bool		Download all embedding model presets (fast, balanced, quality, multilingual)
embedding_model	--embedding-model	Option<String>		Download a specific embedding model preset
all_table_models	--all-table-models	bool		Download all table structure models including SLANeXT variants (~730MB)
all_grammars	--all-grammars	bool		Download all tree-sitter grammar parsers
grammar_groups	--grammar-groups	Option<Vec<String>>		Download specific tree-sitter grammar groups (comma-separated: web,systems,scripting,data,jvm,functional)
grammars	--grammars	Option<Vec<String>>		Download specific tree-sitter grammars by language name (comma-separated)
ner	--ner	bool		Download the default xberg GLiNER NER model alias
ner_model	--ner-model	Option<String>		Download a specific xberg GLiNER NER model alias or catalog id
all_ner_models	--all-ner-models	bool		Download every GLiNER NER model variant xberg knows about

xberg chunk

Chunk text for processing

Options

Name	Flags	Type	Default	Description
text	--text	Option<String>		Text to chunk. If not provided, reads from stdin.
config	--config	Option<PathBuf>		Path to config file (TOML, YAML, or JSON)
chunk_size	--chunk-size	Option<usize>		Chunk size in characters
chunk_overlap	--chunk-overlap	Option<usize>		Chunk overlap in characters
chunker_type	--chunker-type	String	text	Chunker type: text, markdown, yaml, or semantic
chunking_tokenizer	--chunking-tokenizer	Option<String>		Tokenizer model for token-based chunk sizing (e.g., “Xenova/gpt-4o”). Requires the chunking-tokenizers feature.
topic_threshold	--topic-threshold	Option<f32>		Topic threshold for semantic chunking (0.0-1.0, default: 0.75)
format	--format	WireFormat	json	Output format (text or json)

xberg completions

Generate shell completions

Arguments

Name	Flags	Type	Default	Description
shell		clap_complete::Shell		Shell to generate completions for

xberg detect

Detect MIME type of a file

Arguments

Name	Flags	Type	Default	Description
path		PathBuf		Path to the file

Options

Name	Flags	Type	Default	Description
format	--format	WireFormat	text	Output format (text or json)

xberg embed

Generate embeddings for text

Options

Name	Flags	Type	Default	Description
text	--text	Vec<String>		Text to embed. Can be specified multiple times for batch embedding.
preset	--preset	String	balanced	Embedding preset (fast, balanced, quality, multilingual). Used with –provider local.
provider	--provider	String	local	Embedding provider: “local” (default, ONNX), “llm” (liter-llm), or “plugin” (registered in-process backend)
model	--model	Option<String>		LLM model for provider-hosted embeddings (e.g., “openai/text-embedding-3-small”). Required when –provider is “llm”.
api_key	--api-key	Option<String>		API key for the LLM provider
plugin	--plugin	Option<String>		Name of a pre-registered in-process embedding backend. Required when –provider is “plugin”. The backend must have been registered via xberg::plugins::register_embedding_backend before this command runs.
format	--format	WireFormat	json	Output format (text or json)

xberg extract

Extract text from a document

Arguments

Name	Flags	Type	Default	Description
uri		Option<String>		URI to the document. Local paths and file:// URIs are supported in this checkout.

Options

Name	Flags	Type	Default	Description
url	--url	Option<String>		HTTP(S) URL to extract.
stdin		bool		Read document bytes from stdin.
config	--config	Option<PathBuf>		Path to config file (TOML, YAML, or JSON). If not specified, searches for xberg.toml/yaml/json in current and parent directories.
no_config_discovery	--no-config-discovery	bool		Skip project and user config discovery and start from built-in defaults.
config_json	--config-json	Option<String>		Inline JSON configuration. Applied after config file but before individual flags.
config_json_base64	--config-json-base64	Option<String>		Base64-encoded JSON configuration. Useful for shell environments where quotes are problematic.
mime_type	--mime-type	Option<String>		MIME type hint (auto-detected if not provided)
format	--format	WireFormat	text	Output format for CLI results (text or json).
output_dir	--output-dir	Option<PathBuf>		Directory where extracted image files are written (text/toon output only).
ocr	--ocr	Option<bool>		Enable or disable OCR. When true, configures an OCR backend (default: tesseract). When false, removes any OCR configuration.
ocr_backend	--ocr-backend	Option<String>		OCR backend to use when –ocr is enabled (tesseract, paddle-ocr, vlm, or candle-*).
ocr_language	--ocr-language	Option<String>		OCR language code. Tesseract uses ISO 639-3 (eng, fra, deu). PaddleOCR uses short codes (en, ch, french, korean).
force_ocr	--force-ocr	Option<bool>		Force OCR even if text extraction succeeds.
ocr_scanned_pages	--ocr-scanned-pages	bool		OCR pages that look like scans, keeping native text elsewhere.
scanned_min_confidence	--scanned-min-confidence	Option<f64>		Minimum scan confidence (0.0-1.0) for –ocr-scanned-pages. Default: 0.7.
disable_ocr	--disable-ocr	Option<bool>		Disable OCR entirely (even for images)
no_cache	--no-cache	Option<bool>		Disable extraction result caching.
ocr_auto_rotate	--ocr-auto-rotate	Option<bool>		Enable automatic image rotation before OCR based on detected orientation.
ocr_backend_options	--ocr-backend-options	Option<String>		JSON object of per-backend OCR options (e.g. {"layout_mode":"whole_page"}).
vlm_model	--vlm-model	Option<String>		VLM model for OCR (implies –ocr-backend vlm). Uses liter-llm routing format (e.g., “openai/gpt-4o”, “anthropic/claude-sonnet-4-20250514”).
vlm_api_key	--vlm-api-key	Option<String>		VLM API key for OCR
api_key	--api-key	Option<String>		Default LLM API key shared across every LLM-backed feature (VLM OCR, structured extraction, translation, classification, captioning, summarisation, NER). Lower precedence than --vlm-api-key and any api_key set in the loaded config file, higher precedence than the XBERG_LLM_API_KEY environment variable.
vlm_prompt	--vlm-prompt	Option<String>		Custom VLM OCR prompt template (Jinja2)
chunk	--chunk	Option<bool>		Enable or disable text chunking.
chunk_size	--chunk-size	Option<usize>		Maximum chunk size in characters.
chunk_overlap	--chunk-overlap	Option<usize>		Overlap between consecutive chunks in characters.
chunking_tokenizer	--chunking-tokenizer	Option<String>		Tokenizer model for token-based chunk sizing (e.g. “Xenova/gpt-4o”). Implicitly enables chunking. Requires the chunking-tokenizers feature.
content_format	--content-format	Option<ContentOutputFormatArg>		Content rendering format (plain, markdown, djot, html). Controls the format of extracted content.
output_format	--output-format	Option<ContentOutputFormatArg>		Content rendering format (DEPRECATED: use –content-format instead).
include_structure	--include-structure	Option<bool>		Include hierarchical document structure in results.
jupyter_cell_rendering	--jupyter-cell-rendering	Option<JupyterCellRenderingArg>		For Jupyter notebooks: render code cells as source, outputs, or both (default: both). Cells are never executed — outputs come only from those saved in the notebook.
quality	--quality	Option<bool>		Enable quality post-processing.
detect_language	--detect-language	Option<bool>		Enable language detection on extracted text.
layout	--layout	Option<bool>		Enable layout detection with default model settings (RT-DETR v2). Use --layout to enable or --layout false to explicitly disable.
layout_confidence	--layout-confidence	Option<f32>		Layout detection confidence threshold (0.0 - 1.0).
layout_strategy	--layout-strategy	Option<String>		Which pages the layout model runs on: always (default, every page) or auto (pre-screen each page and skip the model where it cannot help).
layout_table_model	--layout-table-model	Option<String>		Table structure model: tatr (default), slanet_wired, slanet_wireless, slanet_plus, slanet_auto, disabled.
use_layout_for_markdown	--use-layout-for-markdown	bool		Feed layout detection regions into the non-OCR markdown pipeline to improve heading/table/list/figure structure. Requires --layout to be enabled. Default: false.
acceleration	--acceleration	Option<AccelerationArg>		ONNX Runtime execution provider for model inference.
max_concurrent	--max-concurrent	Option<usize>		Maximum number of concurrent extractions in batch mode.
max_threads	--max-threads	Option<usize>		Cap all internal thread pools (Rayon, ONNX intra-op, batch semaphore).
extract_pages	--extract-pages	Option<bool>		Extract pages as a separate array in results.
page_markers	--page-markers	Option<bool>		Insert page marker comments into the main content string.
extract_images	--extract-images	Option<bool>		Enable image extraction from documents.
target_dpi	--target-dpi	Option<i32>		Target DPI for image normalisation (e.g. 150, 300, 600).
pdf_password	--pdf-password	Vec<String>		Password(s) for encrypted PDFs. Can be specified multiple times.
pdf_extract_images	--pdf-extract-images	Option<bool>		Extract images embedded in PDF pages.
pdf_extract_tables	--pdf-extract-tables	Option<bool>		Extract tables from PDF (pdf_oxide native grid + heuristic text-layer fallback). Default: true.
pdf_ocr_inline_images	--pdf-ocr-inline-images	Option<bool>		OCR extracted inline images and inject results into the document.
pdf_extract_metadata	--pdf-extract-metadata	Option<bool>		Extract PDF metadata (title, author, etc.).
pdf_backend	--pdf-backend	Option<String>		PDF extraction backend to use (currently only “pdf-oxide” is supported).
token_reduction	--token-reduction	Option<ReductionLevelArg>		Token reduction level (off, light, moderate, aggressive, maximum).
msg_codepage	--msg-codepage	Option<u32>		Windows codepage fallback for MSG files without codepage metadata. Common values: 1250 (Central European), 1251 (Cyrillic), 1252 (Western).
cache_namespace	--cache-namespace	Option<String>		Cache namespace for tenant isolation.
cache_ttl_secs	--cache-ttl-secs	Option<u64>		Per-request cache TTL in seconds (0 = skip cache).
html_theme	--html-theme	Option<String>		Built-in colour theme for styled HTML output (default, github, dark, light, unstyled). Implies –content-format html and enables the styled HTML renderer.
html_css	--html-css	Option<String>		Inline CSS string appended after the theme stylesheet in styled HTML output.
html_css_file	--html-css-file	Option<std::path::PathBuf>		Path to a CSS file loaded once and appended after the theme stylesheet in styled HTML output.
html_class_prefix	--html-class-prefix	Option<String>		CSS class prefix used on every emitted class name (default: “kb-”).
html_no_embed_css	--html-no-embed-css	bool		Suppress the embedded <style> block in styled HTML output.

xberg formats

List all supported document formats

Options

Name	Flags	Type	Default	Description
format	--format	WireFormat	text	Output format (text or json)

xberg mcp

Start the MCP (Model Context Protocol) server

Options

Name	Flags	Type	Default	Description
config	--config	Option<PathBuf>		Path to config file (TOML, YAML, or JSON). If not specified, searches for xberg.toml/yaml/json in current and parent directories.
transport	--transport	String	stdio	Transport mode: stdio (default) or http
host	--host	String	127.0.0.1	HTTP host (only for –transport http)
port	--port	u16	8001	HTTP port (only for –transport http)
allowed_host	--allowed-host	Vec<String>		Additional Host header value to accept on the HTTP transport (repeatable; only for –transport http). Extends, but never replaces, rmcp’s loopback-only allowlist (localhost, 127.0.0.1, ::1) — needed when running behind a reverse proxy or ingress that forwards a different hostname. Precedence: this flag > XBERG_MCP_ALLOWED_HOSTS env var (comma-separated) > [mcp] allowed_hosts in the config file (only when –config is given explicitly) > default (loopback only).

xberg serve

Start the API server

Options

Name	Flags	Type	Default	Description
host	-H, --host	Option<String>		Host to bind to (e.g., “127.0.0.1” or “0.0.0.0”). CLI arg overrides config file and env vars.
port	--port	Option<u16>		Port to bind to. CLI arg overrides config file and env vars.
config	--config	Option<PathBuf>		Path to config file (TOML, YAML, or JSON). If not specified, searches for xberg.toml/yaml/json in current and parent directories.

xberg version

Show version information

Options

Name	Flags	Type	Default	Description
format	--format	WireFormat	text	Output format (text or json)