CLI
Synopsis¶
parsecraft [OPTIONS] COMMAND [ARGS]...
The app sets no_args_is_help=True: a bare parsecraft prints help and exits
with status 2. Shell completion is enabled (add_completion=True).
Global options¶
| Option | Alias | Behaviour |
|---|---|---|
--version |
-v |
Print the package version (eager) and exit |
--install-completion |
Install completion for the current shell | |
--show-completion |
Print the completion script | |
--help |
Show help and exit |
--version reads importlib.metadata.version("parsecraft") and falls back to
0.0.0 when the distribution is not installed (for example, a source checkout
run without an install).
Commands¶
parsecraft backends¶
List registered backends. Discovery runs lazily on first use.
| Option | Env var | Behaviour |
|---|---|---|
--json |
PARSECRAFT_JSON |
Emit machine-readable JSON instead of the table |
Exit status is 0. Load failures never raise — they are printed to stderr
before the table:
$ parsecraft backends
warning: backend 'broken' failed to load: failed to load backend 'broken' from entry point: ...
example-echo cpu text
Table columns:
| Column | Source |
|---|---|
| Name (24 columns) | descriptor.name |
| Device | gpu when capabilities.gpu_requirement is 1.0, cpu/gpu when it is between 0.0 and 1.0, otherwise cpu |
| VRAM | vram<=XG when capabilities.estimated_vram_gb is set, otherwise blank |
| Formats | Comma-joined capabilities.supported_formats, or - when empty |
With no backends registered:
$ parsecraft backends
No backends registered.
--json emits the descriptor list as JSON (indent=2, keys sorted). The list
is [] when none are registered. Each entry is the BackendDescriptor plus the
derived suffixes array (what this backend can ingest — see
Backends), sorted, including only backends whose
optional extra is installed:
[
{
"capabilities": {
"estimated_vram_gb": null,
"gpu_requirement": 0.0,
"languages": [],
"model_asset": null,
"ocr_capable": false,
"optional_dependency_group": null,
"supported_formats": ["text/plain"],
"supports_multi_page": false,
"supports_page_ranges": false
},
"name": "native-text",
"suffixes": [".c", ".cc", ".cfg", ".cpp", ".h", ".hpp", ".ini", ".log", ".m", ".py", ".rst", ".sh", ".tex", ".text", ".toml", ".txt"],
"version": "0.1.0"
}
]
parsecraft convert¶
Convert a document through the auto-mode pipeline: analyze the source, route it
with parsecraft.routing, execute with parsecraft.pipeline, and print the IR.
parsecraft convert SOURCE [OPTIONS]
| Option | Default | Behaviour |
|---|---|---|
--backend, -b NAME |
unset | Non-auto: lead with this backend (it must be eligible) |
--judge SPEC |
unset | Route with a judge provider (provider/model, or provider:model; model token verbatim); mutually exclusive with --backend, combinable with --classifier; may use the network (except ollama/<model>, which is local) |
--classifier SPEC |
unset | Fold OCR-need facts from a classifier provider (provider/model, or provider:model) into the analysis |
--auto / --no-auto |
--auto |
Route automatically; --no-auto requires --backend |
--max-passes N |
1 |
Fallback passes per page group (N >= 1) |
--timeout-s SECONDS |
unset | Per-request backend deadline in seconds (bounds each attempt, not the whole run; must be positive) |
--no-ocr |
off | Forbid OCR harnesses; a parser that OCRs internally stays eligible |
--preference AXIS |
balanced |
Ranking axis inside the eligible family: speed, balanced, or quality. Reachable in auto mode with or without --judge; ignored by --backend, which already names the lead |
--backend-option KEY=VALUE |
unset | Repeatable; a constructor option for --backend (which it requires). Values are coerced (true/false/yes/no/on/off, integers, floats). An unknown key is a silent no-op on every backend except docling, which exits 1 naming it and listing the accepted set (pc-23b tracks making this one policy) — so a typo looks like success today; docling accepts do_ocr, do_table_structure, force_full_page_ocr, keep_picture_images, do_picture_classification, do_code_enrichment, do_formula_enrichment, images_scale, ocr_lang |
--json |
off | Emit the IR as JSON instead of the Markdown projection |
--cache / --no-cache |
--no-cache |
Reuse a content-addressed conversion cache |
--output, -o PATH |
unset | Write the result to PATH (UTF-8) instead of stdout, truncating like > redirection; the parent directory must already exist — a missing one exits 2 before any conversion starts |
--config-file PATH |
unset | Load PATH as the project layer instead of ./parsecraft.toml — the judge model, the judge endpoint, the text-classifier model and the request deadline all read it |
Output is the Markdown projection (parsecraft.ir.markdown.to_markdown) or the
DocumentResult as JSON (--json) — printed to stdout, or written to PATH
with --output/-o (which leaves stdout empty). A first-use model download
prints one downloading <model> (<size>) into <dir> line to stderr before
the fetch starts — informational only, no prompt and no flag. Supported suffixes come from the public
parsecraft.pipeline.MEDIA_TYPES map: the text family (.txt, .text, .md,
.markdown, .html, .htm, .rst, .tex, .log, .ini, .cfg, .toml,
.sh, .py, .c, .cc, .cpp, .h, .hpp, .m), the delimited family (.csv, .tsv), the office family
(.doc, .docx, .pptx, .xlsx, .odt, .rtf, .epub), plus .pdf, .jpg,
.jpeg, .png, .tif, and .tiff. .json, .xml, and extensionless
paths stay out of MEDIA_TYPES on purpose — the CLI routes them through a
text sniff instead of rejecting them: content identified as text becomes
text/plain via native-text, without changing the source bytes or their
hash. Content identified as binary, or unreadable input, keeps the original
usage error and exits 2. This heuristic can misclassify either kind of input;
it is not a security check.
Fidelity notes — the sniff decides textness, not encoding, and a
heuristic decode is announced, never silent. native-text decodes
deterministic-first (BOM-declared codec, else historical UTF-8 path) and
routes everything else through charset detection carrying a text-encoding
WARNING diagnostic, echoed once per distinct message on stderr. So: charset
guesses can be wrong even without replacement characters; on a warning,
verify the output and if needed convert a copy of the source to UTF-8 before
ingestion. No guaranteed-fidelity claim is made for sniffed input.
That map is what the CLI accepts, not what a given install can convert: every
media type must be claimed by at least one registered backend, and the office
family is reached only through docling, pymupdf, pandoc, or openpyxl.
A host with none of them installed reports no eligible backend and exits 1.
For Word specifically, --backend docling file.docx is the layout-, table-, and
reading-order-aware path (DOCX conversion-verified 2026-10-17); pandoc (host
binary) and pymupdf (AGPL extra) are the other two.
$ parsecraft convert report.txt
<!-- page 1 -->
A paragraph comfortably longer than the forty character routing threshold.
The command probes the host once per invocation, analyzes with the
deterministic analysis backend (candidates whose optional dependency is
installed or dependency-free win; native backends first, then name order), and
reuses that probe for the routing constraints built by
parsecraft.environment.constraints_from_environment (installed extras,
measured VRAM, PARSECRAFT_OFFLINE). --max-passes and --no-ocr map to
RoutingConstraints.max_passes and allow_ocr.
Both optional routing seams accept a provider/model spec string, resolved
before any I/O. Both default to off, which is exactly the rule-table
behaviour, and --backend cannot be combined with --judge — both choose
the lead candidate. parsecraft judges prints the live provider catalog (model
tokens, credentials, and whether this host has them), and
Steer the auto-backend selector walks
through the flags with worked examples. The shipped values:
Judge providers (--judge)¶
| Spec | Endpoint | Credential | Notes |
|---|---|---|---|
typesafe-ai/jev-latest, typesafe-ai/jev-preview |
TypeSafe cloud, System One models | TYPESAFE_API_KEY |
typed Choice ranking; exit 1 without the key |
zen/jev-1.13, zen/jev-1.13-free |
OpenCode Zen, same System One wire | OPENCODE_API_KEY |
the -free model is quota-free |
ollama/<model> |
local Ollama daemon (:11434), same System One wire |
none | any local Nimble/Tev scoring model (nimble, tev); other GGUFs answer 400; bare name resolves to the daemon's :latest tag |
The SDK these providers share (typesafe-sdk) is a core dependency — the
base install needs no extra for them; the credential is the only thing a host
must add.
Classifier providers (--classifier)¶
| Spec | Endpoint | Credential | Notes |
|---|---|---|---|
pdfinspector/detect_pdf |
in-process, local (pdf-inspector library) | none | the only shipped provider; model-free text-layer scan; pdf-inspector is a core dependency |
What --classifier does, concretely: it runs during analysis, before any
routing decision, and folds per-page facts into the signals — an OCR-need
verdict per page, table pages, and a document pdf_type with confidence.
Two rules govern the fold:
- Augment-only. A page the classifier calls OCR-needy is routed to OCR even when its text statistics look fine; a page the text statistics already flag stays flagged regardless of the classifier's verdict. The classifier can add OCR-need, never remove it.
- Observable effects. Page routes may change, a
feature:tableshint is emitted when table pages are reported, and aclassifier-provenancedocument diagnostic records provider,pdf_type, and confidence. Nothing else in the output changes.
It works in auto mode and under --no-auto (the fold is analysis-level),
needs no credential and no network, and — like the judge — the mode token is
matched verbatim (it names the upstream call, detect_pdf, which is
already 1-indexed like the IR).
--judge is an explicit opt-in to whatever that provider does — the cloud
providers reach the network — and is not gated by PARSECRAFT_OFFLINE,
which excludes model-asset backends from candidacy rather than the judge
seam. With no --judge/--classifier spec, no provider is resolved at all.
Text-kind classification ([text_classifier])¶
| Spec | Endpoint | Credential | Notes |
|---|---|---|---|
typesafe-ai/<model> |
TypeSafe cloud, System One models | TYPESAFE_API_KEY (or the shared [providers.typesafe] section) |
verdict stamped as detected_kind on .txt chunks |
What the text-kind classifier does, concretely: it runs during extract, on
ambiguous .txt sources only, and chooses the structure parser — a verdict
of markdown-like routes the text through the markdown pipeline (heading
and list chunks stamped with detected_kind), anything else keeps the
plain-paragraph path byte-identical to the unconfigured output. A tie or an
unparsable answer resolves to plain with confidence 0.0.
There is deliberately no --text-classifier flag and no env var: the extract
only reads configuration, so a flag value could never reach it and would key
cache entries on a choice the extract never sees. The flag can come back when
the executor forwards request-scoped knobs to the backend (tracked in
pc-c54); until then the section is the whole surface. The dedicated
[text_classifier] model config-file value is the only activation surface —
routing judge configuration never switches on text-kind classification.
--preference is a ranking axis, never a permission: it reorders the
candidates the hard constraints already admitted (smallest declared VRAM first
for speed/balanced, largest first for quality) and cannot move a
candidate across an intent family. It reaches both the planner's own
DeterministicJudge — through RoutingConstraints.preference — and a resolved
System One judge, whose Choice question carries the axis verbatim.
Exit codes: 0 success, 1 analysis or routing failure, 2 usage error
(unsupported suffix, missing file, --no-auto without --backend, a --backend
that is not eligible for the source, a malformed --judge/--classifier spec,
an invalid --preference value, a missing --output directory, or --backend
combined with --judge). A missing optional backend dependency
also exits 1 with an actionable optional dependency missing: … message
naming the extra to install, and a provider that cannot be resolved exits 1
with judge unavailable: … or classifier unavailable: … — a malformed spec
exits 2 instead. When --judge and --classifier are both named and both
fail to resolve, the command reports them together (routing providers
unavailable: plus one <flag> <spec>: <reason> line each), so one run names
every missing extra; its exit code follows the failures (2 when any spec was
malformed, otherwise 1). A conversion in which every pass failed exits 1 with
conversion produced no content: every pass failed for all N page(s) … naming
the missing extra — an empty document is never reported as success. Partial
degradation (some pages converted, some not) stays 0 and records the failed
pages in the IR.
Eligibility matches RoutingConstraints.formats against each backend's
supported_formats; both declare MIME media types (text/plain,
application/pdf, image/jpeg, image/png), so a scanned PDF can route to
OCR and a digital PDF to pymupdf.
With --cache, a completed conversion is stored under
sha256(source bytes + registry.fingerprint() + canonical constraints +
effective judge identity), and a later identical conversion returns the stored
DocumentResult without dispatching any backend. Because nothing ran, a hit's
PipelineResult.groups are plan-shaped — the planned pages and candidates with
winner=None and attempts=[]; read plan for the route, not groups for
evidence of execution.
The key covers the source bytes, the registered backend set
(registry.fingerprint() — names, versions, supported formats), the resolved
RoutingConstraints, and the judge identity, so a fingerprint, constraint, or
envelope-schema change is a miss, never stale reuse. Caching is off by
default and opt-in per invocation; the root is $PARSECRAFT_CACHE_DIR or the
platform user-cache directory followed by parsecraft/conversions. Inspect or
clear it with parsecraft cache.
Judge endpoint configuration¶
A decision model needs an endpoint (base URL) and sometimes a credential. Each knob resolves per knob, highest precedence first:
- explicit CLI flags:
--judge-base-url,--judge-api-key; - generic env vars:
PARSECRAFT_JUDGE_BASE_URL,PARSECRAFT_JUDGE_API_KEY; - the
[providers.<section>]config-file value; - the built-in default (the provider's own base URL, or the legacy credential env var, or no credential for the local daemon).
The default model is selected the same way: an explicit --judge spec beats
PARSECRAFT_JUDGE_MODEL, which beats the [judge] model config-file value —
so a host default resolves with no flag at all. A configured default is still
a chosen lead: --backend cannot be combined with it either. The text-kind
default is section-only: [text_classifier] model, with no flag, no env var,
and no [judge] fallback. A per-request backend deadline resolves by the same
flag-beats-config rule: an explicit --timeout-s wins, otherwise the
timeout_s config key applies, otherwise requests stay unbounded.
The config-file sections accept provider aliases: [providers.zen]
is the zen provider, [providers.typesafe] is typesafe-ai, and
[providers.ollama-cloud] is the local ollama daemon pointed elsewhere.
An exact provider token ([providers.typesafe-ai]) always works too.
Credentials are secret-bearing: write api_key = "${OPENCODE_API_KEY}"
— never a literal — and config show redacts every providers.*.api_key.
# ~/.config/parsecraft/config.toml (global; overridden by ./parsecraft.toml)
[providers.typesafe]
base_url = "https://proxy.internal/v1"
api_key = "${TYPESAFE_API_KEY}"
[judge]
model = "typesafe-ai/jev-latest"
[text_classifier]
model = "typesafe-ai/jev-preview"
No provider-specific env vars or flags exist — only the two generic env vars
and the two generic flags above. The legacy credential env vars
(TYPESAFE_API_KEY, OPENCODE_API_KEY) keep working as the fallback when
nothing else names a credential.
Which file a config value comes from. Every config value above is read
from one effective configuration per run: the global file, the project layer
(./parsecraft.toml, or the file --config-file names — the same meaning
the flag has for parsecraft config check and parsecraft config show), and
the environment. The judge model, the judge endpoint, the text-classifier
model and the request deadline all read that one configuration, so a value
set in the file --config-file names is the value the conversion uses — it is
not limited to the config group (pc-8e6).
A library consumer that builds its own layer set
(parsecraft.cli.config.build_engine([...])) installs it for the run with
parsecraft.cli.config.config_scope(settings) — the judge spec, the endpoint,
the text-classifier spec and the timeout then read that configuration, the
same one the routing constraints were derived from, instead of a second,
silently different one.
parsecraft cache¶
Inspect or clear the conversion cache used by convert --cache.
| Option | Default | Behaviour |
|---|---|---|
--json |
off | Emit location, entries, total_bytes, and the sorted entry keys as JSON |
--clear |
off | Delete every cached conversion |
By default the command prints the cache location, the number of entries, and their total size:
$ parsecraft cache
location: /home/me/.cache/parsecraft/conversions
entries: 3
size: 12.4 KiB
Each entry is one JSON file named by its sha256 key. --json additionally
lists every key; per-entry sizes come from the library API
(parsecraft.cache.ConversionCache.entries() → key, size_bytes). With
--clear the output is the single line
removed N conversion cache entries from <root>. The root honours
PARSECRAFT_CACHE_DIR and otherwise defaults to the platform user-cache
directory plus parsecraft/conversions.
parsecraft inspect¶
Analyze a source with the cheapest analysis backend and preview the route
without converting content (same backend selection as convert).
| Option | Default | Behaviour |
|---|---|---|
--json |
off | Emit the analysis and routing preview as JSON |
--max-passes N |
1 |
Fallback passes for the previewed plan |
--no-ocr |
off | Forbid OCR harnesses in the preview; a parser that OCRs internally stays eligible |
Output lists the media type, source hash, page count, every page signal
(chars, images, blank, replacement), any diagnostics, and the routing
preview (primary, then per-page intent/chosen/candidates and reason).
When no backend is eligible the line reads routing: unavailable — <error> and
the command still exits 0, because the analysis itself succeeded.
$ parsecraft inspect report.txt
source: text/plain
hash: a5063811dae62ef716743d0c10e2f6e99afc19ff4d8dc53ec04d09d206cf234a
pages: 1
page 1: chars=131 images=0 blank=False replacement=n/a
routing: primary=native-text
page 1: intent=native chosen=native-text candidates=native-text
reason: page 1: native text sufficient (text_chars=131); first pass native-text
parsecraft judges¶
List the built-in judge providers: each provider's spec spelling, model tokens, credential, and whether this host has that credential. Pure description — nothing is resolved, no credential is read beyond its presence, and no endpoint is contacted.
| Option | Default | Behaviour |
|---|---|---|
--json |
off | Emit the provider profiles plus credential availability as JSON |
$ parsecraft judges
no --judge: the deterministic rule table decides; no provider is resolved and no network is used
typesafe-ai/jev-latest TYPESAFE_API_KEY (unset) SDK default base URL
parsecraft models¶
Command group over parsecraft.assets.AssetManager.
| Subcommand | Behaviour |
|---|---|
models list |
Descriptor catalogue joined with cache state (name, model id, revision, size, license, quant, VRAM est, cached). Size is measured on disk for a cached revision, else the backend's declared estimate. --json supported |
models install NAME |
Install a pinned asset; requires --yes (network opt-in) and --accept-license when the license requires it |
models remove NAME |
Delete every cached revision of one model |
models clean |
Delete every cached revision |
models path |
Print the cache location and total size (--json supported) |
NAME is a backend name (ocr-ovis) or a model id (ATH-MaaS/OvisOCR2).
Offline mode comes from the detected host (PARSECRAFT_OFFLINE);
list/path/remove/clean never touch the network.
Pinned manifests
models install builds the AssetPin from the descriptor's pinned
file_pins (repo path + SHA-256 per file) and verifies every file through
AssetManager.ensure. A descriptor with no file_pins (a non-model
backend) produces a typed "no pinned manifest" error (exit 1).
Fetching needs no extra — huggingface-hub is a core dependency, so the
asset layer works on a base install.
Every first-use fetch — here or during a conversion — announces itself with one
downloading <model> (<size>) into <dir> line on stderr before transferring
bytes (model, size, destination; no prompt, no flag).
parsecraft benchmark¶
Benchmark every eligible backend over local documents and print a deterministic report (the harness omits wall-clock metadata).
| Option | Default | Behaviour |
|---|---|---|
--json |
off | Print the JSON report instead of Markdown |
--markdown |
on | Force the Markdown report (mutually exclusive with --json) |
--output, -o DIR |
unset | Also write benchmark.json and benchmark.md into DIR |
--max-passes N |
1 |
Fallback passes per page group |
--timeout-s SECONDS |
unset | Per-request backend deadline in seconds (same flag-beats-config rule as convert) |
--no-ocr |
off | Forbid OCR harnesses; a parser that OCRs internally stays eligible |
--config-file PATH |
unset | Load PATH as the project layer instead of ./parsecraft.toml — the request deadline reads it |
Documents are read locally; a missing or unsupported path becomes a Skip
record rather than an error. Constraints come from the detected host
(constraints_from_environment) with no format restriction, because the
harness filters candidates by each document's own media type.
$ parsecraft benchmark tests/downloads/report.txt
# ParseCraft benchmark report
package: `2026.9.9`
...
parsecraft config¶
Command group for the layered configuration engine. Sources are
merged in order default → global → project → env → cli. The global file is
~/.config/parsecraft/config.toml on every platform; the project file is
./parsecraft.toml; settings come from PARSECRAFT_CONFIG_* env vars (__
separates nested sections).
The project layer may hold several files: a later file wins per key, and
every effective key records the exact file that set it, so config show
reports project:<path> per key (a consumer that keeps one config in its
vault and one in the working directory passes both, vault first). Missing
files are skipped; relative paths resolve against the current directory.
Shared options:
| Option | Env var | Behaviour |
|---|---|---|
--config-file PATH |
Load PATH as the project layer instead of ./parsecraft.toml |
|
--json |
PARSECRAFT_JSON |
Emit machine-readable JSON |
Recognized settings:
| Key | Type | Default | Notes |
|---|---|---|---|
hf_token |
string | unset | Secret; write ${HF_TOKEN}, never a literal. Redacted by show |
cache_dir |
path | unset | Asset-cache override; resolved relative to its declaring file |
offline |
bool | false |
Asset-manager offline mode |
min_free_bytes |
int | 0 |
Asset-manager free-space floor |
timeout_s |
float | unset | Per-request backend deadline in seconds; an explicit --timeout-s flag beats it |
providers.<name>.base_url |
string | provider default | Judge endpoint override; provider aliases include typesafe = typesafe-ai and ollama-cloud = ollama |
providers.<name>.api_key |
string | credential default | Secret; write ${VAR_NAME}, never a literal. Redacted by show |
judge.model |
string | unset | Default decision-model spec; --judge and PARSECRAFT_JUDGE_MODEL beat it |
text_classifier.model |
string | unset | Default text-kind spec (the only activation surface); never reads [judge] |
Routing settings¶
The [routing] section carries the auto-routing knobs. It maps 1:1 onto
RoutingConstraints; library consumers build one with
RoutingSettings.routing_constraints(...) instead of re-deriving the
mapping. Keys not set keep the documented default.
[routing]
preference = "balanced" # speed | balanced | quality
allow_ocr = true # omit the key to let eligibility derive it
engines = ["pandoc"] # required engine ids; unknown ids fail `config check`
preferred_backend = "docling" # preference, not a permission: ineligible pages still route elsewhere
# only_backend = "liteparse" # pin every page; unknown names fail `config check`
[routing.backend_options.docling]
do_ocr = false # forwarded verbatim; keys are backend-owned (pc-k92)
| Key | Type | Default | Notes |
|---|---|---|---|
preference |
string | balanced |
speed, balanced, or quality; orders eligible candidates, never admits one |
allow_ocr |
bool | unset | Key absent = no override (eligibility derives it); false forbids OCR backends |
engines |
string list | [] |
Required engine ids (e.g. pandoc, tesseract); an unknown id is a config check error |
preferred_backend |
string | unset | Move this backend to the front where it is eligible; empty string = unset |
only_backend |
string | unset | Pin every page to one backend; empty string = unset |
backend_options.<backend> |
table | {} |
Forwarded verbatim into that backend's options (part of the conversion-cache key); option keys are backend-owned and validated at first conversion, not here |
language |
string | unset | ISO language hint for language-gated backends |
max_passes |
int | 1 |
Fallback-pass budget; ≥ 1 |
vram_budget_gb |
float | 0.0 |
VRAM ceiling in GiB; ≥ 0 |
gpu_usable |
bool | false |
Whether GPU-resident backends may be considered |
Deliberately absent (derived per run, never configured): formats (from the
source media type), installed_extras (from the registry), cached_assets
(from the asset cache), offline (a top-level key).
parsecraft config check¶
Validate the effective configuration. Exit 1 when invalid, otherwise 0.
Warnings and errors print on stderr in text mode. An unknown
routing.preferred_backend, routing.only_backend, or routing.engines
name is an error naming the key and the accepted set.
$ parsecraft config check
Configuration is valid.
$ parsecraft config check --json
{
"errors": [],
"snapshot": { "cache_dir": null, "hf_token": null, "min_free_bytes": 0, "offline": false },
"valid": true,
"warnings": []
}
On failure --json returns "valid": false with an errors list.
parsecraft config show¶
Print every effective key with its value and provenance (layer:origin).
Values are coerced through the schema; hf_token is redacted as ***. When
the configuration is invalid, show still prints the raw source values.
$ parsecraft config show
cache_dir = null (default:<defaults>)
hf_token = "***" (default:<defaults>)
judge.model = null (default:<defaults>)
min_free_bytes = 0 (default:<defaults>)
offline = false (default:<defaults>)
routing.allow_ocr = null (default:<defaults>)
routing.engines = [] (default:<defaults>)
routing.gpu_usable = false (default:<defaults>)
routing.language = null (default:<defaults>)
routing.max_passes = 1 (default:<defaults>)
routing.only_backend = null (default:<defaults>)
routing.preference = "balanced" (default:<defaults>)
routing.preferred_backend = null (default:<defaults>)
routing.vram_budget_gb = 0.0 (default:<defaults>)
text_classifier.model = null (default:<defaults>)
timeout_s = null (default:<defaults>)
A key set by a project file reports the file it came from:
routing.max_passes = 2 (project:/work/parsecraft.toml).
--json emits one object per key:
{"key", "value", "source": {"layer", "origin"}}.
Environment variables¶
| Variable | Used by | Description |
|---|---|---|
PARSECRAFT_JSON |
parsecraft backends, parsecraft config |
Default value of --json |
PARSECRAFT_CONFIG_* |
parsecraft config |
Configuration settings (see below) |
PARSECRAFT_JUDGE_MODEL |
parsecraft convert |
Default decision-model spec; beats the [judge] config value |
PARSECRAFT_JUDGE_BASE_URL |
parsecraft convert |
Endpoint base-URL override; beats the [providers.*] config value |
PARSECRAFT_JUDGE_API_KEY |
parsecraft convert |
Credential override; beats the [providers.*] config value |
PARSECRAFT_CACHE_DIR |
parsecraft convert --cache, parsecraft cache |
Overrides the conversion-cache root |
PARSECRAFT_OFFLINE |
any command | Declares offline mode; backends carrying a model_asset are excluded |
PARSECRAFT_MINERU |
parsecraft backends, convert, inspect |
Declares the mineru extra installed — its requirements are identical to surya's, so no import can prove it. Accepts 1/true/yes; required as well as parsecraft[mineru] (see the mineru row) |
PARSECRAFT_TESSERACT |
parsecraft backends, convert, inspect |
Declares the tesseract binary's path, honoured verbatim and never probed past (ADR-0008 decision 2) |
PARSECRAFT_JSON is a CLI flag default. Configuration settings use the
distinct PARSECRAFT_CONFIG_ prefix so the flag cannot collide with a setting
key.
Source¶
src/parsecraft/cli/app.py— app, callback, command and group registrationsrc/parsecraft/cli/commands.py—backends,convert,inspect,benchmark,cache,models_*,config_*src/parsecraft/cli/convert.py—convert_source,PreferredBackendJudge, seam-spec resolution, renderingsrc/parsecraft/cli/inspect.py—inspect_source, preview renderingsrc/parsecraft/cli/benchmark.py— harness wrapper + report writerssrc/parsecraft/cli/models.py— asset catalogue,PinProvider, cache managementsrc/parsecraft/cli/errors.py—CliErrorsrc/parsecraft/cli/args.py—JsonFlag,ConfigFileOption,PARSECRAFT_JSONsrc/parsecraft/cli/config.py—ParsecraftConfig,build_engine, the run-scoped effective configuration (config_scope,effective_settings)