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> [--porcelain]
docuriser --help | --version
Every command exits 0 on success and 1 on failure, so the CLI composes with shell scripts and CI pipelines. --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 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, writes the .docuriser-built provenance (which tag, which commit, when), and records the tag's date on the version's release_date.
With a bare config, it builds every pending included version, newest first: this is exactly what the GUI's Build N Pending button runs.
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 be included in the config's versions[], 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
The dev escape hatch: builds the named version from the checkout as it sits, no tag involved. Any provenance on the output is cleared, so the version honestly reads Pending until a real tag build replaces it. Useful 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 (new, excluded, pending, complete, no-tag), and whether it is included. This is the same derivation the GUI's Versions table shows; the table literally runs this command. Config-declared rows still list when git is unavailable (as no-tag), 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>.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.