CLI Reference¶
The opm command is a Typer application. This page is generated from opm.cli by scripts/gen_cli_docs.py. Run opm --help (or opm <command> --help) for the same information in your terminal.
opm¶
Open Processing Model: transform XML via ODD processing models (ODDs compile on demand into the user cache).
Usage:
Options:
| Option | Description |
|---|---|
--version, -V |
Show the installed version and exit. |
--quiet, -q |
Do not print the OPM logo. |
--install-completion |
Install completion for the current shell. |
--show-completion |
Show completion for the current shell, to copy it or customize the installation. |
--help |
Show this message and exit. |
Commands:
init: Create a local project: an empty one or a...transform: Transform an XML document via an ODD with...chunk: Chunk a large XML document into smaller...index: Emit embedding-ready JSONL records for a...serve: Start a local HTTP server rooted at the...odd: Inspect or document an ODD: corpus...
opm init¶
Create a local project: an empty one or a copy of a bundled example.
Usage:
Arguments:
| Argument | Description |
|---|---|
DIRECTORY |
Project directory (default: current directory). |
Options:
| Option | Description |
|---|---|
--force |
Overwrite existing generated files. |
--vocabulary TEXT |
Empty project for this vocabulary: tei, docbook, jats (default: tei). |
--example, -e TEXT |
Start from a bundled example project instead of an empty one: jats, docbook, serafin, escher, monograph, shakespeare, odd. |
--list-examples |
List the bundled example projects and exit. |
--copy-base-odd |
TEI only: also copy packaged teipublisher.odd and tp.css into odd/. |
--templates |
Also copy the alternative HTML templates (chapbook, journal, handbook, tufte, bootstrap) beside the one the project uses, and opm's plain default Typst template as templates/document.typ.j2. |
--base |
Also copy the templates the HTML templates inherit from (templates/opm/) and the base stylesheet (styles/default-styles.css), to edit them in the project. |
--bare |
Skip README.md, AGENTS.md, CLAUDE.md and .gitignore. |
--help |
Show this message and exit. |
opm transform¶
Transform an XML document via an ODD with processing instructions and return the result (HTML, markdown, …).
Usage:
Arguments:
| Argument | Description |
|---|---|
INPUT_XML |
Input XML file |
Options:
| Option | Description |
|---|---|
--odd, -d PATH |
ODD file to compile on demand into the user cache. Overrides transform. |
--type, -t TYPE |
Transform type / ODD output channel (web, print, epub, markdown, docx, typst, json). Selects transform. |
--channel CHANNEL |
With -t json only: which ODD output channel to record decisions for (web, print, epub, markdown, docx, typst). Default: web. |
--output, -o PATH |
Write transform output to this file (default: stdout unless --preview). With -t typst, a .pdf file name compiles the output with the typst command. |
--preview, -v |
Preview output: channel web/print → browser, markdown → Rich (paged in a TTY so bold/italic survive), docx/epub → the platform default application, typst → the compiled PDF, opened by typst (typst compile --open) when the typst command is installed; other channels → plain text in the terminal. |
--param, -p KEY=VALUE |
Runtime parameter for XPath $parameters (repeatable), e.g. -p mode=toc -p display=browse |
--css PATH |
CSS file replacing the packaged base rules compiled into the ODD stylesheet. Falls back to transform.css in the project config. |
--template PATH |
Template path: Jinja2 for HTML/print/Typst output, or .docx for DOCX output. |
--xpath, -x EXPR |
XPath 3.1 expression evaluated with the document root as the context item; the single selected element becomes the transform root. Unprefixed names use the same default element namespace as the document root. $parameters is bound from --param. |
--xpath-extensions TEXT |
Dotted import path(s) of Python module(s) whose public callables become XPath functions in the tp: namespace (repeat option to add modules; e.g. --xpath-extensions extensions.common --xpath-extensions extensions.dates). Importing these modules runs top-level code: only use trusted code. |
--footnote-order TEXT |
Dotted import path of a callable that orders each run's footnotes before they are placed, e.g. --footnote-order opm.runtime.footnote_order.labelled_first (lettered apparatus before numbered commentary). Applies to the output modes that place footnotes themselves (web, markdown). Falls back to transform.footnote_order in opm.toml. Importing the module runs top-level code: only use trusted code. |
--webcomponents, --no-webcomponents |
Enable/disable tei-publisher web components mode: alternate behaviours emit |
--strict |
Exit with an error when an XPath expression fails at run time, instead of treating it as false or empty. Expressions opm cannot run at all (eXist functions, XQuery syntax) are reported when the ODD is compiled and do not count. |
--config, -c PATH |
Path to a TOML configuration file (default: opm.toml in the current directory). |
--help |
Show this message and exit. |
opm chunk¶
Chunk a large XML document into smaller HTML pages or JSON data files.
Usage:
Arguments:
| Argument | Description |
|---|---|
INPUT_XML |
XML file to transform and chunk, or a directory of XML files. |
Options:
| Option | Description |
|---|---|
--odd, -d PATH |
ODD file to compile on demand for chunking (overrides chunking.odd in config). |
--output-dir, -o PATH |
Directory to write chunked files (overrides chunking.output_dir in config). |
--template, -t FILE |
Jinja2 template for chunk pages (overrides chunking.template in config). |
--force, -f |
Remove the existing output directory without prompting. |
--depth INTEGER |
Maximum division/section depth for chunk splitting (overrides chunking.depth in config). |
--webcomponents, --no-webcomponents |
Enable/disable tei-publisher web components mode. Falls back to transform.web.webcomponents in the project config. |
--xpath-extensions TEXT |
Dotted import path(s) of Python module(s) whose public callables become XPath functions in the tp: namespace (repeatable). Falls back to transform.xpath_extensions in opm.toml. |
--footnote-order TEXT |
Dotted import path of a callable that orders each run's footnotes before they are placed, e.g. --footnote-order opm.runtime.footnote_order.labelled_first (lettered apparatus before numbered commentary). Applies to the output modes that place footnotes themselves (web, markdown). Falls back to transform.footnote_order in opm.toml. Importing the module runs top-level code: only use trusted code. |
--format TEXT |
Output format for chunk files: "html" (default, rendered via Jinja2 template), "json" (one JSON file per chunk containing content, head, odd_css, and fragments — suitable for static site generators such as Eleventy), or "pb-view" (index.json lookup table plus one part file per chunk, consumable by the dynamic pb-view web component in static mode). |
--doc-path TEXT |
For --format pb-view: document path subdirectory. Data is written to |
--preview, -v |
After chunking, start a local HTTP server rooted at the output directory and open the first page in a browser (HTML output only). |
--port, -p INTEGER |
Port for --preview (default: 8080). |
--strict |
Exit with an error when an XPath expression fails at run time, instead of treating it as false or empty. Expressions opm cannot run at all (eXist functions, XQuery syntax) are reported when the ODD is compiled and do not count. |
--config, -c PATH |
Path to a TOML configuration file (default: opm.toml in the current directory). |
--help |
Show this message and exit. |
opm index¶
Emit embedding-ready JSONL records for a search index or vector store.
Records come from the processing model, not the raw source, so the ODD's
editorial decisions carry into the index: omitted apparatus stays out, and
alternate contributes the reading the page displays.
Usage:
Arguments:
| Argument | Description |
|---|---|
INPUT_XML |
XML file to index, or a directory of XML files (searched recursively). Defaults to ./data when it exists. |
Options:
| Option | Description |
|---|---|
--odd, -d PATH |
ODD file to compile on demand (overrides transform.json.odd in config). |
--output, -o PATH |
JSONL file to write (default: stdout). |
--max-chars INTEGER |
Split a section longer than this at record boundaries. Falls back to index.max_chars in opm.toml (default: 1500). |
--min-chars INTEGER |
Drop units shorter than this — bare headings are retrieval noise. Falls back to index.min_chars in opm.toml (default: 40). |
--overlap INTEGER |
Records of context carried into the next part when a unit splits. Falls back to index.overlap in opm.toml (default: 1). |
--strict |
Exit with an error when an XPath expression fails at run time, instead of treating it as false or empty. Expressions opm cannot run at all (eXist functions, XQuery syntax) are reported when the ODD is compiled and do not count. |
--config, -c PATH |
Path to a TOML configuration file (default: opm.toml in the current directory). |
--help |
Show this message and exit. |
opm serve¶
Start a local HTTP server rooted at the chunks output directory.
Usage:
Options:
| Option | Description |
|---|---|
--port, -p INTEGER |
Port to listen on (default: 8080). |
--directory, -d PATH |
Directory to serve (default: chunking.output_dir from config, or "chunks"). |
--config, -c PATH |
Path to a TOML configuration file (default: opm.toml in the current directory). |
--help |
Show this message and exit. |
opm odd¶
Inspect or document an ODD: corpus coverage, static schema reference sites.
Usage:
Options:
| Option | Description |
|---|---|
--help |
Show this message and exit. |
Commands:
compile: Follow the ODD inheritance chain and write...document: Generate a static HTML documentation site...coverage: Diagnose an ODD against a corpus: what...
opm odd compile¶
Follow the ODD inheritance chain and write one self-contained ODD, or its RELAX NG schema.
Walks each schemaSpec/@source, merges the layers (a TEI customization
onto the cached TEI schema when needed), and emits a single schemaSpec
with every selected spec and no moduleRef. Schema tools such as the
TEI Stylesheets' odd2relax take that file. Unlike opm odd document --prepare,
content models stay on the specs rather than in documentation pages.
--format rng goes one step further and writes the RELAX NG schema
itself. Main purpose is to enable simple validation in editors. Use with
care: not extensively tested on complex ODDs, does not embed Schematron rules.
Usage:
Arguments:
| Argument | Description |
|---|---|
SOURCE |
The ODD to compile, with its schemaSpec/@source chain. |
Options:
| Option | Description |
|---|---|
--output, -o PATH |
Where to write the result (default: SOURCE-STEM.compiled.odd, or SOURCE-STEM.rng with --format rng). |
--format TEXT |
"odd" (default) for the compiled ODD, or "rng" for the RELAX NG schema made from it. |
--force |
Overwrite the output file if it exists. |
--help |
Show this message and exit. |
opm odd document¶
Generate a static HTML documentation site from an ODD.
Follows schemaSpec/@source (processing-model chains included). A
TEI-targeting ODD (schemaSpec/@ns absent or the TEI namespace) is merged
onto the cached TEI schema; without SOURCE, TEI alone is documented. Writes
reference pages plus A–Z catalogs. Processing models are listed on each
elementSpec.
Chapter prose from the input is always kept, and when the input is itself the schema being documented (no SOURCE, a Guidelines p5.xml, a Specs directory) its chapters are published too. A customization documents itself, so TEI's chapters stay out of its site. An ODD pinning an older TEI/@version is compiled against the shipped snapshot, with a warning.
Run inside a project made by opm init --example odd, the site is built
with that project's ODD, runs, template, assets and extension modules, and
what to document, the language and the output directory default to its
[document] and [[chunking]] settings.
With -t typst, -t markdown or -t epub, the same documentation is
written as one PDF, Markdown or EPUB file instead, through the project's
[transform] settings: opm odd document --prepare and opm transform in
one step.
With --prepare, only the tree the site or document is made from is
written: the schema merged onto TEI, all references resolved, and the
pages the site adds — a title page if there is none, and the A–Z catalogs
— injected. Inside a documentation project, opm chunk over the result
writes that project's runs in any of its formats, e.g. --format json
for a static site generator.
Usage:
Arguments:
| Argument | Description |
|---|---|
SOURCE |
ODD, compiled spec document (p5subset.xml / Guidelines p5.xml), or a directory of Specs. Omit to document the TEI Guidelines, downloaded (specs plus prose, ~2 MB) into the user cache on first use; TEI-targeting ODDs merge onto the same schema. |
Options:
| Option | Description |
|---|---|
--output-dir, -o PATH |
Output directory (default: odd/ |
--type, -t TYPE |
Write one document instead of a site: typst, markdown, epub. Omit to build the HTML site. |
--prepare |
Write only the prepared TEI tree the documentation is made from, for opm chunk or opm transform to take over. |
--lang TEXT |
xml:lang to prefer on gloss/desc/remarks (default: en). |
--odd, -d PATH |
Processing ODD used to render nested TEI (default: packaged tagdocs.odd). |
--force |
Replace the output directory or file if it already exists. |
--preview, -v |
After building, serve the site and open it in a browser; with -t, open the document (PDF viewer, Rich for Markdown, the default application for EPUB). |
--port, -p INTEGER |
Port for --preview (default: 8080). |
--help |
Show this message and exit. |
opm odd coverage¶
Diagnose an ODD against a corpus: what never runs, and what is never handled.
Reports the models and elementSpecs you wrote that no document exercised, models that can never fire at all, elements no model matched, and elements whose spec exists but whose predicates were all false. Models inherited from an extended ODD are counted separately — a local elementSpec replaces the inherited one wholesale, so they are not yours to change.
Coverage transforms whole documents; chunking config is ignored.
Usage:
Arguments:
| Argument | Description |
|---|---|
INPUT_XML |
XML file or directory of XML files to measure the ODD against. Defaults to ./data when it exists. |
Options:
| Option | Description |
|---|---|
--odd, -d PATH |
ODD file to compile on demand (overrides transform.json.odd in config). |
--channel CHANNEL |
ODD output channel to report on (web, print, epub, markdown, docx, typst). Default: web. |
--param, -p TEXT |
Transform parameter KEY=VALUE (repeatable), as for opm transform. |
--all, -a |
List every finding instead of the first 20 per section. |
--json |
Print the whole report as JSON instead of tables. |
--config, -c PATH |
Path to opm.toml. |
--help |
Show this message and exit. |