Command reference

Manuscrio has three commands: inspect, export, and license. They are the same whichever way you run it — the manuscrio command from npm or the container directly — because both drive the same engine inside the same image.

The output below is what --help prints. Run it against your own release to see the version you have:

manuscrio --help
manuscrio export --help

Commands

Usage: manuscrio [-hV] <command>
Generate professional PDF manuals from a static documentation Site Build.
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  inspect  Report the manuals a Site Build contains, as JSON.
  export   Render the manuals to PDF.
  license  Report the entitlement an export would run under, as JSON.

inspect

Reads the Site Build and reports what it found, without rendering anything. Start here on every new Site Build: the IDs it prints are the ones export accepts. The inspect report describes every field.

Usage: manuscrio inspect [-hV] [--framework=<name>] <build-dir>
Report the manuals a Site Build contains, as JSON.
      <build-dir>          Site Build directory.
      --framework=<name>   Documentation framework: docusaurus, starlight, or
                             mkdocs. Detected when omitted.
  -h, --help               Show this help message and exit.
  -V, --version            Print version information and exit.

export

Renders the selected manuals to PDF. Inspect and export explains editions and scopes, and brand your manuals covers --logo and --theme.

Usage: manuscrio export [-hV] [--all-editions] [--no-fail-on-clipped]
                        [--concurrency=<n>] [--framework=<name>]
                        [--license=<file>] [--logo=<file>]
                        [--max-chapter-level=<n>] [--output-dir=<dir>]
                        [--scope=<scope>] [--theme=<name>] [--edition=<id>]...
                        [--exclude-edition=<id>]... [--manual=<id>]...
                        <build-dir>
Render the manuals to PDF.
      <build-dir>            Site Build directory.
      --all-editions         Explicit alias for the default all-editions
                               selection.
      --concurrency=<n>      Maximum parallel exports (default: 4).
      --edition=<id>         Export only this edition. Repeatable.
      --exclude-edition=<id> Exclude an edition from the default set.
                               Repeatable.
      --framework=<name>     Documentation framework: docusaurus, starlight, or
                               mkdocs. Detected when omitted.
  -h, --help                 Show this help message and exit.
      --license=<file>       Signed Manuscrio licence. Without one the run is
                               Evaluation Mode: a complete manual carrying the
                               evaluation watermark and Manuscrio attribution.
                               Also read, in order, from
                               $MANUSCRIO_LICENSE_FILE, $MANUSCRIO_LICENSE (the
                               licence text itself), and /etc/manuscrio/license.
      --logo=<file>          Logo image for the cover and the running header.
                               Defaults to the logo found in the Site Build's
                               own navbar; give this to override it.
      --manual=<id>          Restrict export to a planned manual ID. Repeatable.
      --max-chapter-level=<n>
                             Deepest level numbered in the contents table and
                               PDF outline, 1 to 6 (default: 3). Raising it
                               exposes deeper in-page headings as navigable
                               chapters, at the cost of a longer contents table.
      --no-fail-on-clipped   Report clipped content without failing. Clipped
                               content is fatal by default.
      --output-dir=<dir>     PDF output directory. Defaults to manuscrio-output
                               beside the Site Build.
      --scope=<scope>        edition, section, or sidebar-root (default:
                               edition).
      --theme=<name>         Accent for top-level chapter titles and the
                               contents table: ink, lapis, malachite, garnet,
                               or amethyst (default: ink). ink is uncolored.
  -V, --version              Print version information and exit.

license

Reports the entitlement an export would run under, as JSON, without exporting anything. Use it to confirm a licence is being found before a release build depends on it — see licensing.

Usage: manuscrio license [-hV] [--license=<file>]
Report the entitlement an export would run under, as JSON.
  -h, --help             Show this help message and exit.
      --license=<file>   Licence file to inspect. Without it, the same sources
                           an export uses.
  -V, --version          Print version information and exit.

Paths are the one difference

Every option above behaves the same either way. What changes is what a path means.

	`<build-dir>`, `--output-dir`, `--logo`, `--license`
The `manuscrio` command	Paths on your machine. `manuscrio export ./build --logo brand/acme.svg` — the command mounts each one for you.
The container directly	Paths inside the container. Mount each one yourself and name the mounted path; see container invocation.

Most examples throughout this documentation use the manuscrio command and host paths such as ./build. The container invocation and Run in CI pages spell out container paths such as /input and /output because their subject is the direct image workflow.

Settings for the `manuscrio` command

These apply to the npm command only. They change how it reaches the image, never what the export produces.

Variable	Effect
`MANUSCRIO_RUNTIME`	Container engine to run. Otherwise Docker is tried, then Podman.
`MANUSCRIO_IMAGE`	Image reference to run, in place of the release’s own.
`MANUSCRIO_USER`	Value for `--user`, replacing the mapping the command works out for itself: your UID and GID, plus `--userns=keep-id` where Podman reports it is rootless. Set it only for a mapping neither case covers.

Two more variables are read by the engine itself, and work both ways: MANUSCRIO_LICENSE for the licence text and MANUSCRIO_LICENSE_FILE for a path to it. Licensing covers the order they are read in, and Run in CI shows them as pipeline secrets.

Exit codes

Code	Meaning
`0`	The command succeeded.
`1`	The run failed — a manual could not be rendered, a licence could not be honoured, or a path was not there.
`2`	The command line itself was wrong: an unknown option, a missing argument.

The container runtime can return additional non-zero codes when it cannot start or when the container is terminated. The npm command passes those codes through. Pipelines should depend only on 0 meaning success, not on a closed list of failure codes.

A pipeline should treat anything but 0 as a failed release step. An export that fails part-way leaves the manuals it had already written; when an export fails explains which failures are contained to a single manual.