Reference¶
The reference below is generated from the live Click command tree — every command and flag, straight from the code. It changes only when the CLI changes, and you rarely read it top to bottom.
Use doctrail <command> --help for command-specific option details.
doctrail¶
SQLite document enrichment with normalized outputs and derived views.
Agents: run doctrail agent for the full operating manual in one shot —
the mental model, the enrichment workflow, and troubleshooting. Start
there; everything else is discoverable from it.
Humans: doctrail docs prints the complete reference manual; this --help
lists every command.
Usage:
doctrail [OPTIONS] COMMAND [ARGS]...
Options:
--skip-requirements Skip system requirements check
-v, --version Show version
-h, --help Show this message and exit.
doctrail agent¶
Print the full agent guide: mental model, workflow, troubleshooting.
This is the entry point for an LLM or coding agent driving doctrail. It
prints the complete operating manual to stdout, no install required. Same
content as doctrail skill; agent is the name agents reach for.
Usage:
doctrail agent [OPTIONS]
Options:
-h, --help Show this message and exit.
doctrail batch¶
Manage submitted provider batch enrichment runs.
Usage:
doctrail batch [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit.
doctrail batch cancel¶
Cancel all active batch shards for a run.
Usage:
doctrail batch cancel [OPTIONS]
Options:
--db-path TEXT Path to SQLite database
--run-id TEXT Run ID to cancel [required]
-h, --help Show this message and exit.
doctrail batch poll¶
Poll batch jobs once and reconcile any completed outputs.
Usage:
doctrail batch poll [OPTIONS]
Options:
--db-path TEXT Path to SQLite database
--run-id TEXT Poll only one run ID
-h, --help Show this message and exit.
doctrail batch watch¶
Poll until a batch-backed run is fully reconciled.
Usage:
doctrail batch watch [OPTIONS]
Options:
--db-path TEXT Path to SQLite database
--run-id TEXT Run ID to watch [required]
--interval FLOAT Polling interval in seconds [default: 5.0]
-h, --help Show this message and exit.
doctrail diff-runs¶
Show where two runs disagree.
Usage:
doctrail diff-runs [OPTIONS]
Options:
--db-path PATH Path to SQLite database
--run-a TEXT First run ID [required]
--run-b TEXT Second run ID [required]
--limit INTEGER Max differing cells to show [default: 20]
--json Output as JSON
-h, --help Show this message and exit.
doctrail docs¶
Print the packaged manual: everything an agent needs, in one file.
Usage:
doctrail docs [OPTIONS]
Options:
-h, --help Show this message and exit.
doctrail document¶
Get a single document by ID.
Usage:
doctrail document [OPTIONS]
Options:
--db-path PATH Path to SQLite database [required]
--id TEXT Document ID (primary key value) [required]
--format [text|json] Output format
-h, --help Show this message and exit.
doctrail edit¶
Open a project enrichment YAML in $EDITOR.
Usage:
doctrail edit [OPTIONS] NAME
Options:
-h, --help Show this message and exit.
doctrail enrich¶
Enrich database content using LLM processing.
Run enrichments by name: doctrail enrich language doctrail enrich language summarize
In a doctrail project (.doctrail/ folder), enrichments are loaded from
.doctrail/enrichments/doctrail view create
or doctrail view pivot to inspect them in a wide, human-readable form.
Usage:
doctrail enrich [OPTIONS] [ENRICHMENT_NAMES]...
Options:
--config TEXT Path to config YAML (auto-detects
.doctrail/config.yml)
--enrichments TEXT (Legacy) Enrichment task names
--limit INTEGER Limit number of rows to process
--overwrite Overwrite existing data in output columns
--verbose Enable verbose logging
--log-updates Log updates to a file
--model TEXT Override the default model for all
enrichments
--db-path TEXT Override the database path from config
--output-db TEXT Write enrichments to this database instead
of the source database
--batch-size INTEGER Override batch size for processing
--rowid INTEGER Process only a specific row by rowid
--sha1 TEXT Process only a specific row by sha1 hash
--truncate Truncate long inputs to fit model context
window instead of failing
--skip-cost-check Skip cost estimation and confirmation
--cost-threshold FLOAT Cost threshold for confirmation prompt
(default: $5.00)
--where TEXT Filter the enrichment query with an outer
SQL WHERE predicate
--query TEXT Replace the SQL query from config entirely
--project TEXT Tag enrichments with a project name for
filtering (e.g., mock_compliance)
--dry-run Preview without calling LLM: show row
counts, schema, and sample input
--dedupe-scope [query|prompt|enrichment|name]
Append-mode dedupe scope. Overrides per-
enrichment dedupe_scope.
--materialize-inputs / --no-materialize-inputs
Persist the exact input rowset for each run
--execution-mode [sync|batch|openai-batch]
How to execute the enrichment work. batch
maps direct OpenAI models to /v1/batches ->
/v1/chat/completions, direct Claude models
to /v1/messages/batches -> /v1/messages, and
direct Gemini models to File API upload ->
/v1beta/models/{model}:batchGenerateContent.
openai-batch is accepted as a legacy alias.
[default: sync]
--allow-column-collision Allow enrichment field names that match
source table columns
-h, --help Show this message and exit.
doctrail enrich¶
Enrich database content using LLM processing.
Run enrichments by name: doctrail enrich language doctrail enrich language summarize
In a doctrail project (.doctrail/ folder), enrichments are loaded from
.doctrail/enrichments/doctrail view create
or doctrail view pivot to inspect them in a wide, human-readable form.
Usage:
doctrail enrich [OPTIONS] [ENRICHMENT_NAMES]...
Options:
--config TEXT Path to config YAML (auto-detects
.doctrail/config.yml)
--enrichments TEXT (Legacy) Enrichment task names
--limit INTEGER Limit number of rows to process
--overwrite Overwrite existing data in output columns
--verbose Enable verbose logging
--log-updates Log updates to a file
--model TEXT Override the default model for all
enrichments
--db-path TEXT Override the database path from config
--output-db TEXT Write enrichments to this database instead
of the source database
--batch-size INTEGER Override batch size for processing
--rowid INTEGER Process only a specific row by rowid
--sha1 TEXT Process only a specific row by sha1 hash
--truncate Truncate long inputs to fit model context
window instead of failing
--skip-cost-check Skip cost estimation and confirmation
--cost-threshold FLOAT Cost threshold for confirmation prompt
(default: $5.00)
--where TEXT Filter the enrichment query with an outer
SQL WHERE predicate
--query TEXT Replace the SQL query from config entirely
--project TEXT Tag enrichments with a project name for
filtering (e.g., mock_compliance)
--dry-run Preview without calling LLM: show row
counts, schema, and sample input
--dedupe-scope [query|prompt|enrichment|name]
Append-mode dedupe scope. Overrides per-
enrichment dedupe_scope.
--materialize-inputs / --no-materialize-inputs
Persist the exact input rowset for each run
--execution-mode [sync|batch|openai-batch]
How to execute the enrichment work. batch
maps direct OpenAI models to /v1/batches ->
/v1/chat/completions, direct Claude models
to /v1/messages/batches -> /v1/messages, and
direct Gemini models to File API upload ->
/v1beta/models/{model}:batchGenerateContent.
openai-batch is accepted as a legacy alias.
[default: sync]
--allow-column-collision Allow enrichment field names that match
source table columns
-h, --help Show this message and exit.
doctrail export¶
Export enriched data in various formats.
Usage:
doctrail export [OPTIONS]
Options:
--config TEXT Path to the configuration YAML file [required]
--export-type TEXT Type of export to run (e.g., parallel-translation, case-
summaries) [required]
--output-dir TEXT Override the default output directory from config
--verbose Enable verbose logging
-h, --help Show this message and exit.
doctrail finalize¶
Materialize an editable final table from a run or existing review view.
Usage:
doctrail finalize [OPTIONS]
Options:
--db-path PATH Path to SQLite database
--run-id TEXT Materialize the final surface for one run ID
--view TEXT Materialize an existing review view instead of a run
--table TEXT Writable table name to create
--replace Replace the target table if it already exists
-h, --help Show this message and exit.
doctrail icr¶
Run intercoder reliability: enrich sampled rows with multiple models.
Example: doctrail icr threat_coding -m openrouter/google/gemini-2.5-flash -m gpt-4o-mini --sample 50 --seed 42
Usage:
doctrail icr [OPTIONS] ENRICHMENT_NAME
Options:
-m, --models TEXT Models to use as coders (repeat for multiple)
[required]
--sample INTEGER Sample N rows (default: all)
--stratify-by TEXT Stratify sample by this enrichment field
--seed INTEGER Random seed for reproducibility
--config TEXT Path to config YAML (auto-detects .doctrail/config.yml)
--db-path TEXT Database path override
--overwrite Re-run models that already have codings
--skip-cost-check Skip cost confirmation
--project TEXT Tag enrichments with a project name
--verbose Verbose logging
-h, --help Show this message and exit.
doctrail icr-report¶
Compute intercoder reliability statistics from enrichment codings.
Example: doctrail icr-report --db-path out/db.db --field hostility_level
Usage:
doctrail icr-report [OPTIONS]
Options:
--db-path TEXT Database path (defaults to
.doctrail/config.yml)
--field TEXT Field name to analyse [required]
--enrichment-name TEXT Filter by enrichment name
-m, --models TEXT Specific models to compare (repeat)
--sample-id TEXT Filter to specific ICR sample
--level [nominal|ordinal|interval]
Measurement level (auto-detected if omitted)
-o, --output TEXT Write CSV coding matrix to this path
--verbose Verbose logging
-h, --help Show this message and exit.
doctrail ingest¶
Ingest documents from local directories, Zotero, or plugins.
Supported local file types: txt/md; csv/tsv; pdf; epub; mobi; doc; rtf; docx; xlsx; xls; pptx; ppt; djvu; mhtml/mht; html/htm; png/jpg/jpeg/gif/bmp/tiff/tif.
Examples: doctrail ingest --input-dir ./docs --db-path ./data.db doctrail ingest --zotero --collection "Papers" --db-path ./lit.db doctrail ingest --plugin zotero --collection "My Research"
Usage:
doctrail ingest [OPTIONS]
Options:
--config TEXT Path to the configuration YAML file
--db-path TEXT SQLite database file, or a directory to
use/create doctrail.db in
--table TEXT Table name for documents
--verbose Enable detailed logging
--input-dir TEXT Input directory (can repeat)
--force Force ingest even if schema mismatch
--overwrite Overwrite existing documents
--limit INTEGER Limit files to process
--include-pattern TEXT Only process matching files
--exclude-pattern TEXT Skip matching files
--workers INTEGER RANGE Number of extraction worker threads [x>=1]
--pdf-engine [auto|pymupdf|pdftotext|mutool|mac-ocr]
PDF extraction strategy
--ocr-engine [auto|textra|ocrmypdf|mac-ocr]
OCR backend when OCR is needed
--readability Use readability for HTML
--html-extractor [default|smart]
--skip-garbage-check Skip garbage detection
-y, --yes Skip prompts
--fulltext Create FTS index
--manifest TEXT Path to manifest.json
--zotero Zotero mode
--collection TEXT Zotero collection name
--plugin TEXT Plugin name
--plugin-dir TEXT Custom plugins directory
--cache-db TEXT [doi_connector] Cache database
--project TEXT [doi_connector] Project name
--base-path TEXT [doi_connector] Base path
--api-key TEXT [zotero] API key
--user-id TEXT [zotero] User ID
--zotero-dir TEXT [zotero] Data directory
-h, --help Show this message and exit.
doctrail init¶
Initialize a doctrail project in the current directory.
Creates: - .doctrail/config.yml (project settings) - .doctrail/enrichments/ (your analysis tasks) - out/{name}.db (database, unless --database is used) - .env (API key, unless --no-env is used)
Doctrail stores model outputs in normalized enrichment tables and then materializes user-facing views for review and analysis.
Example: cd my_research/ doctrail init
Usage:
doctrail init [OPTIONS] [[test]] [[fed|un|econ-threat]]
Options:
--name TEXT Project name (used for database filename)
--api-key TEXT API key (or set interactively)
--provider [openai|gemini|anthropic|openrouter]
LLM provider (default: openai)
--docs TEXT Path to documents folder (relative to
current dir)
--database TEXT Path to SQLite database to use in config
--no-docs Skip document-folder setup for query-first
projects
--no-env Do not create a .env file; rely on existing
environment variables
-y, --yes Skip prompts, use defaults
-e, --enrichments TEXT Enrichments to set up (can repeat)
-h, --help Show this message and exit.
doctrail list-enrichments¶
List all available enrichments from a configuration file.
Usage:
doctrail list-enrichments [OPTIONS]
Options:
--config TEXT Path to the configuration YAML file [required]
-h, --help Show this message and exit.
doctrail models¶
List doctrail model identifiers by backend.
Usage:
doctrail models [OPTIONS]
Options:
-p, --provider TEXT Filter by backend (e.g. openai, anthropic, gemini, cli,
openrouter/openai)
-s, --search TEXT Search models by name or identifier
--refresh Force refresh the underlying pricing or batch catalog
cache
-n, --limit INTEGER Max models to display per section [default: 10]
--all Show the full OpenRouter catalog with pricing
--openai-batch Show the verified OpenAI batch model catalog and batch
pricing
--json Output as JSON
-h, --help Show this message and exit.
doctrail new¶
Create a new custom enrichment.
Example: doctrail new sentiment --prompt "Classify the sentiment" --enum "positive,negative,neutral"
Usage:
doctrail new [OPTIONS] [NAME]
Options:
-p, --prompt TEXT Instructions for the LLM
-o, --output TEXT Output column/field name
--type [string|integer|number|boolean|array]
Output type (default: string)
--enum TEXT Comma-separated enum values (e.g.,
"positive,negative,neutral")
--overwrite Overwrite an existing enrichment YAML
-h, --help Show this message and exit.
doctrail overrides-export¶
Export one run to a CSV template for human review and overrides.
Usage:
doctrail overrides-export [OPTIONS]
Options:
--db-path PATH Path to SQLite database
--run-id TEXT Run ID to export for review [required]
--output PATH CSV path to write (defaults to ./overrides_<run>.csv)
-h, --help Show this message and exit.
doctrail overrides-import¶
Import human overrides from a CSV and refresh the final merged view.
Usage:
doctrail overrides-import [OPTIONS]
Options:
--db-path PATH Path to SQLite database
--run-id TEXT Run ID to import overrides into [required]
--input PATH CSV created by overrides-export [required]
--reviewer TEXT Reviewer name stored with imported overrides
-h, --help Show this message and exit.
doctrail query¶
Query the database.
Examples: doctrail query # List documents doctrail query 1 # Show details of document #1 doctrail query -c # List with content preview doctrail query --json # Full JSON output doctrail query "SELECT ..." # Custom SQL
Usage:
doctrail query [OPTIONS] [QUERY_OR_ID]
Options:
-n, --limit INTEGER Limit number of rows (default: 10)
-t, --table TEXT Table name (defaults to project default_table, then
documents)
--json Output as JSON
-c, --content Show content preview
-h, --help Show this message and exit.
doctrail rebuild-enrichments¶
Rebuild _enrichments exactly from projection payloads stored in _enrichment_audit.
Usage:
doctrail rebuild-enrichments [OPTIONS]
Options:
--db-path PATH Path to SQLite database
--run-id TEXT Restrict rebuild to one run ID
--enrichment TEXT Restrict rebuild to one enrichment name
--key-value TEXT Restrict rebuild to one document key
-y, --yes Skip confirmation
-h, --help Show this message and exit.
doctrail review¶
Validate enrichment accuracy with a web UI.
Opens a browser-based interface for rapid Y/N validation of LLM classifications. Results are saved to the human_audit table.
Examples: doctrail review /path/to/db.db --field is_relevant --sample 50 doctrail review db.db --field language --sample 100 --table documents doctrail review db.db --field is_relevant --config enrichment.yml
Usage:
doctrail review [OPTIONS] DB_PATH
Options:
--field TEXT Field name to review (e.g., is_relevant) [required]
--sample INTEGER Sample size per class (default: 50)
--port INTEGER Port to run server on (default: 8765)
--table TEXT Table name (default: articles)
--config PATH Config file to get truncation from input_columns
--truncate INTEGER Content truncation limit (overrides config)
-h, --help Show this message and exit.
doctrail runs¶
List recent enrichment runs with persisted run IDs and summary counts.
Usage:
doctrail runs [OPTIONS]
Options:
--db-path PATH Path to SQLite database
--enrichment TEXT Filter to one enrichment name
--limit INTEGER Max runs to list [default: 20]
--json Output as JSON
-h, --help Show this message and exit.
doctrail serve¶
Start the Doctrail multi-database server.
The server provides HTTP endpoints for searching and enriching multiple SQLite databases. Configure databases in a YAML file:
doctrail-server.yaml¶
server: host: 0.0.0.0 port: 8000 databases: literature: /data/literature # directory containing .db file organs: /data/organs
Each database directory should contain: - A .db file (the SQLite database) - Optional: doctrail.yaml (schema config) - Optional: chroma_db/ (vector store for semantic search) - Optional: help.md (database-specific documentation)
Example: doctrail serve --config doctrail-server.yaml doctrail serve --port 9000
Usage:
doctrail serve [OPTIONS]
Options:
--config PATH Server configuration file (default: doctrail-server.yaml)
--host TEXT Override host from config
--port INTEGER Override port from config
--verbose Enable verbose logging
-h, --help Show this message and exit.
doctrail skill¶
Print or install the packaged Doctrail skill.
Usage:
doctrail skill [OPTIONS]
Options:
--install Install the packaged Doctrail skill into
~/.claude/skills/doctrail/SKILL.md
--force Overwrite an existing installed skill when used with --install
-h, --help Show this message and exit.
doctrail sql¶
Execute a read-only SQL query (SELECT only).
Usage:
doctrail sql [OPTIONS]
Options:
--db-path PATH Path to SQLite database [required]
-q, --query TEXT SQL SELECT query [required]
--format [text|json] Output format
-h, --help Show this message and exit.
doctrail stats¶
Get database statistics.
Usage:
doctrail stats [OPTIONS]
Options:
--db-path PATH Path to SQLite database [required]
--format [text|json] Output format
-h, --help Show this message and exit.
doctrail view¶
Manage derived views for reviewing and analyzing normalized enrichments.
Doctrail stores model outputs in normalized tables (_enrichments,
_enrichment_audit, _enrichment_runs). Views are the user-facing surface:
they join source rows with selected enrichment fields in a wide format.
Commands:
doctrail view List all views in database
doctrail view create List recent runs / enrichments
doctrail view create
View workflow:
doctrail runs
doctrail view create --run-id
Pivot examples: doctrail view pivot my_review -e framing_v6 doctrail view pivot my_review -e framing --fields hostility,frame --include "title,raw_content:500" doctrail view pivot icr_check -e framing --by-model --include title
View spec example: doctrail view spec payments_review doctrail view refresh doctrail view render payments_review --output payments_review.html
Review shortcut: doctrail view create my_enrichment doctrail query "SELECT * FROM v_run_my_enrichment_20260228_1430 LIMIT 20"
Usage:
doctrail view [OPTIONS] [[list|new|refresh|create|pivot|spec|render]] [NAME]
Options:
--table TEXT Source table to join against (default: from
config)
--run-id TEXT Run ID to build a view for
-e, --enrichment TEXT Enrichment name (for pivot action)
--fields TEXT Comma-separated field names to include (default:
all)
--include TEXT Source columns to include, with optional :N
truncation (e.g. "title,raw_content:500")
--by-model Create per-model columns for ICR comparison
--output TEXT Output path for render action
--format [html|csv|json] Output format for render action [default: html]
--limit INTEGER Optional row limit for render action
-h, --help Show this message and exit.