CLI Reference¶

Overview¶

The docling-graph CLI provides command-line tools for document-to-graph conversion, configuration management, and graph visualization.

Available Commands: - init - Create configuration files - convert - Convert documents to graphs - inspect - Visualize graphs in browser

Quick Start¶

Installation¶

# Install with all features
uv sync

# Verify installation
uv run docling-graph --version

Basic Usage¶

# 1. Initialize configuration
uv run docling-graph init

# 2. Convert a document
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument"

# 3. Visualize the graph
uv run docling-graph inspect outputs/

Global Options¶

Available with all commands:

Option	Short	Description
`--verbose`	`-v`	Enable detailed logging
`--version`		Show version and exit
`--help`	`-h`	Show help message

Examples¶

# Show version
uv run docling-graph --version

# Enable verbose logging
uv run docling-graph --verbose convert document.pdf -t "templates.BillingDocument"

# Show help
uv run docling-graph --help
uv run docling-graph convert --help

Command Overview¶

init¶

Create a configuration file with interactive prompts.

uv run docling-graph init

Features: - Interactive configuration builder - Dependency validation - Provider/model identifiers use LiteLLM routing - API key guidance

Learn more: init Command →

convert¶

Convert documents to knowledge graphs.

uv run docling-graph convert SOURCE --template TEMPLATE [OPTIONS]

Features: - Multiple backend support (LLM/VLM) - Flexible processing modes - Configurable chunking - Multiple export formats

Learn more: convert Command →

inspect¶

Visualize graphs in your browser.

uv run docling-graph inspect PATH [OPTIONS]

Features: - Interactive HTML visualization - CSV and JSON import - Node/edge exploration - Self-contained output

Learn more: inspect Command →

Common Workflows¶

Workflow 1: First-Time Setup¶

# 1. Initialize configuration
uv run docling-graph init

# 2. Install dependencies (if prompted)
uv sync

# 3. Set API key (if using remote)
export MISTRAL_API_KEY="your-key"

# 4. Convert first document
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument"

Workflow 2: Batch Processing¶

# Process multiple documents
for pdf in documents/*.pdf; do
    uv run docling-graph convert "$pdf" \
        --template "templates.BillingDocument" \
        --output-dir "outputs/$(basename $pdf .pdf)"
done

# Visualize results
for dir in outputs/*/; do
    uv run docling-graph inspect "$dir" \
        --output "${dir}/visualization.html" \
        --no-open
done

Workflow 3: Development Iteration¶

# 1. Convert with verbose logging
uv run docling-graph --verbose convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "test_output"

# 2. Inspect results
uv run docling-graph inspect test_output/

# 3. Iterate on template
# Edit templates/billing_document.py

# 4. Re-run conversion
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "test_output"

Configuration Priority¶

The CLI uses the following priority order (highest to lowest):

Command-line arguments (e.g., --backend llm)
config.yaml (created by init)
Built-in defaults (from PipelineConfig)

Example¶

# config.yaml
defaults:
  backend: llm
  inference: local

# This uses remote inference (CLI overrides config)
uv run docling-graph convert doc.pdf \
    --template "templates.BillingDocument" \
    --inference remote

Environment Variables¶

API Keys¶

# Remote providers
export MISTRAL_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export WATSONX_API_KEY="your-key"

Local Providers¶

# vLLM base URL (default: http://localhost:8000/v1)
export VLLM_BASE_URL="http://custom-host:8000/v1"

# Ollama base URL (default: http://localhost:11434)
export OLLAMA_BASE_URL="http://custom-host:11434"

Output Structure¶

Default output directory structure:

outputs/
├── metadata.json          # Pipeline metadata
├── docling/               # Docling conversion output
│   ├── document.json      # Docling format
│   └── document.md        # Markdown export
└── docling_graph/         # Graph outputs
    ├── graph.json         # Complete graph
    ├── nodes.csv          # Node data
    ├── edges.csv          # Edge data
    ├── graph.html         # Interactive visualization
    └── report.md          # Summary report

Error Handling¶

Common Errors¶

Configuration Error:

[red]Configuration Error:[/red] Invalid backend type: 'invalid'

Solution: Use llm or vlm

Extraction Error:

[red]Extraction Error:[/red] Template not found: 'templates.Missing'

Solution: Check template path and ensure it's importable

Pipeline Error:

[red]Pipeline Error:[/red] API key not found for provider: mistral

Solution: Set MISTRAL_API_KEY environment variable

Verbose Mode¶

Enable verbose logging for debugging:

uv run docling-graph --verbose convert document.pdf \
    --template "templates.BillingDocument"

Best Practices¶

👍 Use Configuration Files¶

# ✅ Good - Reusable configuration
uv run docling-graph init
uv run docling-graph convert document.pdf -t "templates.BillingDocument"

# ❌ Avoid - Repeating options
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --inference remote \
    --provider mistral \
    --model mistral-large-latest

👍 Organize Output¶

# ✅ Good - Organized by document
uv run docling-graph convert invoice_001.pdf \
    --template "templates.BillingDocument" \
    --output-dir "outputs/invoice_001"

# ❌ Avoid - Overwriting outputs
uv run docling-graph convert invoice_001.pdf \
    --template "templates.BillingDocument"

👍 Use Verbose for Development¶

# ✅ Good - Debug during development
uv run docling-graph --verbose convert document.pdf \
    --template "templates.BillingDocument"

# ✅ Good - Silent in production
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument"

Next Steps¶

Explore each command in detail:

init Command → - Configuration setup
convert Command → - Document conversion
inspect Command → - Graph visualization
CLI Recipes → - Common patterns

Or continue to: - Python API → - Programmatic usage - Examples → - Real-world examples