Every docouture command (@inditextech/docouture-cli), reproduced from its own
--help text. All eleven accept --dir <path> to run from anywhere inside the target
repository — the actual root is found by walking up, same as git itself.
Global flags, valid before or after the command name: -h/--help, -v/--version,
--json (machine-readable output where supported — currently doctor), --verbose
(same as DEBUG=docouture), --no-color.
docouture new <name>
Scaffold an Antora documentation site into docs/ (and its
workflows into .github/workflows/), plus AGENTS.md, into the root of an existing
git repository. Prompts interactively for anything not given as a flag, in a terminal;
--yes skips the wizard and uses defaults for everything unset.
| Argument/Flag | Effect |
|---|---|
|
Site name — also the default, title-cased, site title |
|
Repository root to scaffold into (default: cwd, or its enclosing repo) |
|
Site title (default: title-cased from |
|
Public site URL written as |
|
Name the Antora component after the site, adding an extra |
|
|
|
|
|
Trunk-based only: the one branch (default: |
|
Git-flow only: the prerelease branch (default: |
|
Git-flow only: the release branch (default: |
|
Versioned mode only: where the docs release version comes from — |
|
|
|
Skip the interactive wizard |
docouture version <value>
Set the version recorded in docs/src/antora.yml. See
Releasing a documentation.
| Argument/Flag | Effect |
|---|---|
|
Version string to record, e.g. |
|
Overrides |
|
Marks the version as a prerelease (mutually exclusive with |
|
Marks the version as stable (mutually exclusive with |
docouture dev
Build the site and serve it with live reload on every change under docs/ or to
antora-playbook.local.yml.
| Flag | Effect |
|---|---|
|
Dev server port (default |
docouture build
Build the site once — a thin wrapper around the site’s own npm run build
(antora --fetch antora-playbook.yml). No command-specific flags beyond the global
ones.
docouture publish <target>
Publish whatever is already at output.dir (default build/site) using the
@inditextech/docouture-publish-<target> driver — that package must be a
devDependency of the site itself. See Publishing a documentation.
| Argument/Flag | Effect |
|---|---|
|
Publish driver name, e.g. |
|
Any option the driver’s own |
|
Combines with |
|
See |
$ docouture publish gh-pages --branch gh-pages
docouture doctor
Check environment and site health: Node version, that the declared
package manager (package.json’s `packageManager field) is installed, the four names
that must agree (see Modifying the navigation), git history, that
Antora is installed, and (advisory only) whether AGENTS.md is still present, whether the
docs/release label exists, and whether the declared branching model
(docs/package.json’s `docouture.branching, plus docouture.prereleaseBranch under
git-flow) agrees with what
antora-playbook.yml/docouture-release.yml actually say — see
Branching model. On a versioned site it also shows the active
version source and warns about a stray or missing docs/.release-version, a project CLI that
differs from the running one, and a project CLI that predates release resolve — see
main:guides-releasing-a-documentation.adoc#version-sources. Does not check for the agent skills — see
AI-First approach, those are a separate, self-serve install
this CLI never scaffolds or verifies.
| Flag | Effect |
|---|---|
|
Machine-readable report instead of the human-readable console output |
docouture upgrade
Re-sync .github/workflows/ and agent support files (AGENTS.md) from the CLI’s
current templates. Workflows are fully overwritten (there is nothing site-specific in
them); AGENTS.md is merged — only docouture’s own managed section is replaced. The rest of docs/ — every
page a site owner has written — is never touched, with one exception: on a git-flow site
it writes or corrects docouture.branching and docouture.prereleaseBranch in
docs/package.json (derived from antora-playbook.yml), which docouture-release.yml
reads to open the prerelease sync PR. This also backfills sites scaffolded before that field existed.
On a versioned site without docouture.versionSource it writes "versionSource": "descriptor" (the
current behavior, so nothing changes) and points at docouture version-source; it never changes an
existing value, never prompts and never touches a standalone site. It warns when the project’s
installed @inditextech/docouture-cli differs from the running one, since the workflows use the project’s.
It also sets runtime.log.failure_level to error in docs/antora-playbook*.yml, replacing
any other value and printing each file it changed: builds then fail on errors such as a
broken xref: or a missing include, so run docouture build and fix what it reports before
your next CI run.
It also removes the retired check-links feature, printing each change: it deletes
docs/scripts/check-links.mjs and drops the check-links script and
docouture.checkLinks from docs/package.json, plus the linkinator devDependency
unless another script uses it. After that, run your package manager’s install to
refresh the lockfile. It warns about any of your own workflows that still mention
check-links. --dry-run lists these removals without applying them.
| Flag | Effect |
|---|---|
|
Overrides the title read back from |
|
Lists what would be written without writing it |
docouture branch-model <model>
Switch an already-scaffolded repository between the trunk-based and git-flow
branching models — see Branching model for the full mechanism.
Direction is inferred from the site’s current branch names (read live from
antora-playbook.yml/docouture-release.yml, never from a stored config) versus the
<model> argument given here — the same command handles both directions.
Trunk-based → git-flow: the current single branch becomes the release branch by
default (least disruption to anything already tagged off it) — --integration-branch
(the new prerelease branch) is required, since there is nothing on disk to infer that
name from.
Git-flow → trunk-based: lossy — --branch is required and must match one of the two
current branches exactly; a third, invented name is refused.
Re-renders .github/workflows/ (same machinery docouture upgrade uses) and patches
antora-playbook.yml’s `content.sources[0].branches and docs/package.json’s
`docouture.branching field (adding docouture.prereleaseBranch for git-flow, removing it
for trunk-based). Does NOT rename actual git branches, touch
branch-protection/ruleset rules, or change GitHub’s configured default branch — these
stay manual steps, printed as a reminder after every real run.
| Argument/Flag | Effect |
|---|---|
|
Target model: |
|
Trunk-based target only |
|
Git-flow target only: the new prerelease branch |
|
Git-flow target only: overrides the release branch’s name |
|
Lists what would be written without writing it |
docouture version-source [source]
Show or change where a versioned site’s docs release version comes from
(docs/package.json’s `docouture.versionSource). With no argument it prints the current
source. See main:guides-releasing-a-documentation.adoc#version-sources for what each
source means.
Refuses a standalone site, which always releases docs/stable. Per target:
-
descriptorcreatesdocs/.release-versionif it is missing, seeded with the next patch of the latestdocs/v*tag (or--version;0.1.0with no tag). -
github-releaseremovesdocs/.release-version. -
tag-bumpremovesdocs/.release-versionand prints thegh label createcommands fordocs/release-minoranddocs/release-major.
Removing the file warns when it held a pending version. The command is idempotent. No
workflow is re-rendered: the workflows read the source at run time, but they run the
project’s installed CLI, so install a version with release resolve first.
| Argument/Flag | Effect |
|---|---|
|
|
|
|
|
|
|
Lists what would change without changing anything |
docouture release resolve
Resolve the docs version and tag a release run targets. The docouture-release and
docouture-release-preview workflows call it so the version rules live in one place.
Where the version comes from depends on docouture.versionSource in docs/package.json
(descriptor when absent):
| Source | Version |
|---|---|
|
|
|
The published release tag ( |
|
The highest |
--version always takes precedence. A standalone site always targets stable. A versioned
version must be present, valid SemVer and not stable; otherwise the command fails with
exit code 1.
Prints version, tag, source, version_source and uses_descriptor as key=value
lines on stdout, ready to append to $GITHUB_OUTPUT. uses_descriptor is true only when
the descriptor bump and the prerelease sync apply. With --report, a version error is printed
as error (missing, invalid, reserved, prefix or unsupported) and error_value
instead, and the exit code stays 0.
| Argument/Flag | Effect |
|---|---|
|
Required: |
|
Explicit version; takes precedence over every source |
|
GitHub event name ( |
|
Tag of the published GitHub Release ( |
|
Pull request labels, comma-separated ( |
|
Existing tag names instead of listing git tags ( |
|
Report a version error as output instead of failing |
|
Repository root (default: cwd, or its enclosing repo) |