The docuriser-cli reference: scaffolding and building sites and versions from scripts and CI.
docuriser-cli is the command-line companion to the Docuriser desktop app. It drives the same engine, so anything the GUI builds, the CLI can build from a script or a CI job. The build steps in the README produce it at bin/docuriser-cli.
The GUI itself shells out to the CLI for every build and for the versions table (the Build panels run site build --porcelain and build --porcelain as subprocesses, and the Versions panel reads versions --porcelain), so a working CLI is part of a working GUI install. It is also the only place Docuriser runs git.
Run it with no arguments to print the usage summary:
Usage:
docuriser create <name> <version> <logo> <source_dir> <output_dir>
docuriser build <config_file> [version] [--working-tree] [--porcelain]
docuriser versions <config_file> [--porcelain]
docuriser site init <dir>
docuriser site build <site_config> [--strict] [--porcelain]
docuriser --help | --version
Every command exits 0 on success and 1 on failure, so the CLI composes with shell scripts and CI pipelines. site build is the one exception: it keeps going past errors, so it exits 0 once the config loads unless you pass --strict (below). --help (also -h) prints the usage summary and --version (also -v) prints the release version, both exiting 0.
docuriser-cli site init ./my-site
Scaffolds a starter website in the given directory: a .docuriser-site config with a default home layout (home.sections: the site description first, then your projects and socials once you add them) and an empty content-fragments/ directory for any custom sections you add later. The scaffold never clobbers an existing .docuriser-site. This is the CLI twin of the GUI's New Website dialog: open the generated .docuriser-site in the desktop app to continue in the site configurator, or edit the JSON directly using the configuration reference.
docuriser-cli site build ./my-site/.docuriser-site
Builds the whole website: the home page, project pages, policy and license pages, the built documentation bundles, and the static assets they need. The output directory comes from the config's output key, and the emitted pages are self-contained static HTML: open them straight from disk or serve the directory with any static host. See the websites guide for what a build produces.
docuriser-cli site build ./my-site/.docuriser-site --strict
A site build logs each problem and keeps going, so one problem doesn't stop the whole site, and it exits 0 once the config loads. With --strict, it still builds everything, then exits 1 if it logged any error, ending with one more error line that says so:
[Site] --strict: the build logged 2 error(s), exiting with failure.
Use it in CI, so a deploy step after it doesn't publish a site with missing pieces. A download fallback is not an error: when the newest tag is missing a platform's file and the site keeps serving an older complete set, the build logs an Info line and --strict still exits 0. When a project has download rows, a missing downloads/ folder or no complete set at all is an error. See the configuration reference.
docuriser-cli build <config_file> [version] [--working-tree]
For a .docuriser-project config, build is tag-driven (see the versions guide for the model). Each version builds from its minor's latest X.Y.Z tag: the CLI snapshots the tag into a temporary detached git worktree, reads the snapshot's in-repo .docuriser manifest, builds the bundle into versions/<label>/ beside the config, and writes the .docuriser-built provenance (which tag, which commit, the tag's date, and when it was built). Builds never edit the config.
With a bare config, it builds every pending included version, newest first: this is exactly what the GUI's Build N Pending button runs. A tagged version counts as included unless versions_excluded[] lists it.
docuriser-cli build ./projects/layers/.docuriser-project
With an explicit version, it rebuilds that included version from its latest tag regardless of status (a Complete version rebuilds too; this is how a Docuriser upgrade regenerates existing docs):
docuriser-cli build ./projects/layers/.docuriser-project 2.0
The version must not be excluded, and its minor needs at least one X.Y.Z tag whose snapshot carries the manifest; the errors name whichever piece is missing.
docuriser-cli build ./projects/layers/.docuriser-project 2.1 --working-tree
Builds the named version from the checkout as it sits, no tag involved. The label must be major.minor. The provenance marks the output as a preview: it publishes with the release date Unreleased, and reads preview (or pending, when the minor has a tag) until a tag build replaces it. Useful for projects that haven't released yet and for previewing docs mid-development; releases go through tags.
Legacy flat .docuriser configs (the format create writes) keep the original behavior: a bare build parses the configured sources and emits API reference pages into the configured output directory.
docuriser-cli versions ./projects/layers/.docuriser-project
Prints the project's derived version rows: one line per known minor with its latest tag, release date, status (excluded, pending, complete, preview), whether it is included, and whether it is supported (latest for the version the site fronts, else yes or no; see the versions guide). This is the same derivation the GUI's Versions table shows; the table literally runs this command. Built output still lists when git is unavailable, so nothing silently vanishes, and the exit code reflects the config being readable, not git.
build, versions, and site build all take --porcelain: machine-readable framing for embedders, and the mode the GUI drives. Colors and the banner are dropped, and every log line becomes one tab-separated stdout record, flushed immediately so a pipe reader can stream the run live:
<tag>\t<message>
where <tag> is I (info), A (advanced), or E (error). Two commands add data records:
site build emits O\t<output_dir> right after the config loads (the resolved output directory, so an embedder's "open output" affordance works even if the build then fails partway).versions emits one R record per row: R\t<label>\t<latest_tag>\t<date>\t<status>\t<included>\t<supported>. <included> is 1 or 0. <supported> is latest for the version the site fronts (the newest published build), 1 for a version that versions_supported[] lists, and 0 for any other. For example, R\t2.1\t2.1.3\tJuly 15, 2026\tcomplete\t1\t1.The exit code remains the machine signal for success or failure.
docuriser-cli create <name> <version> <logo> <source_dir> <output_dir>
Writes a legacy flat <name>.docuriser config recording the project's name, version, logo, and output directory. This format predates the website/project model and survives for standalone class-doc extraction; new work should start from site init (or the GUI's New Website dialog) and .docuriser-project configs instead.