Synopsis

docent [OPTIONS] <COMMAND>

Options

-h, --help

Print help.

Scope: built-in

-V, --version

Print version.

Scope: built-in

Commands

Command reference

docent status

Show project lint plan and effective rules

Print project metadata, lint scan roots, excluded dependencies, resolved targets, and effective rule severities. Always exits 0 after a successful report (use docent to lint and enforce severities).

Parent: docent

Synopsis

docent status [OPTIONS] <paths>...

Arguments

<paths>…​

Files or directories to summarize. If omitted, uses package paths from build.zig.zon when available.

Variadic: accepts multiple values.

Options

--config-path <PATH>

Path to docent.toml

When omitted, Docent searches upward from the working directory for .config/docent.toml.

Scope: local

--lib

Lint library targets only (default)

Default: false

Scope: local

--bins

Lint all binary targets

Default: false

Scope: local

--bin <STRING>…​

Lint specific binary by name (repeatable)

Scope: local

--tests

Lint all test targets

Default: false

Scope: local

--test <STRING>…​

Lint specific test by name (repeatable)

Scope: local

--deps

Also lint files under path dependencies from build.zig.zon

Default: false

Scope: local

--include-deps

List build targets and module roots discovered in path dependencies

Default: false

Scope: local

--build-script

Include the build script module and everything it depends on to be analyzed

Default: false

Scope: local

docent init

Create a default Docent configuration file

Write .config/docent.toml using the bundled template and the published JSON Schema URL. Does not overwrite an existing file.

Parent: docent

Synopsis

docent init [OPTIONS]

Options

--force

Overwrite an existing configuration file

Default: false

Scope: local

docent check

Run Docent lint checks

Run documentation, style, complexity, or size checks. Use a category subcommand for full diagnostics, or run docent check alone for a compact summary across every category.

Parent: docent

Synopsis

docent check [OPTIONS] <COMMAND>

Options

--config-path <FILE>

Path to a docent.toml configuration file

Must point to a file, not a directory. When omitted, Docent searches upward from the working directory for .config/docent.toml.

Scope: local

--manifest-path <PATH>

Path to a build.zig.zon manifest or its parent directory

Operates as if Docent were invoked from the manifest’s directory. Accepts the manifest file directly or a directory containing it. When omitted, searches upward from the working directory.

Scope: local

--lib

Analyze library targets only (default)

Default: false

Scope: local

--bins

Analyze all binary targets

Default: false

Scope: local

--bin <STRING>…​

Analyze specific binary by name (repeatable)

Scope: local

--tests

Analyze all test targets

Default: false

Scope: local

--test <STRING>…​

Analyze specific test by name (repeatable)

Scope: local

--deps

Also analyze local path dependencies from build.zig.zon (.path entries only, not URL-based)

Default: false

Scope: local

--build-script

Include the build script module and everything it depends on to be analyzed

Default: false

Scope: local

Subcommands

docent check doc

Check documentation comments

Lint doc comments on the public API surface (or all declarations when scan_mode is "all" in config). Exits non-zero when a denied rule reports a finding.

Parent: docent check

Synopsis

docent check doc [OPTIONS] <paths>...

Arguments

<paths>…​

Files or directories to analyze. If omitted, uses package paths from build.zig.zon when available.

Variadic: accepts multiple values.

Options

--config-path <FILE>

Path to a docent.toml configuration file

Must point to a file, not a directory. When omitted, Docent searches upward from the working directory for .config/docent.toml.

Scope: global

--manifest-path <PATH>

Path to a build.zig.zon manifest or its parent directory

Operates as if Docent were invoked from the manifest’s directory. Accepts the manifest file directly or a directory containing it. When omitted, searches upward from the working directory.

Scope: global

--lib

Analyze library targets only (default)

Default: false

Scope: global

--bins

Analyze all binary targets

Default: false

Scope: global

--bin <STRING>…​

Analyze specific binary by name (repeatable)

Scope: global

--tests

Analyze all test targets

Default: false

Scope: global

--test <STRING>…​

Analyze specific test by name (repeatable)

Scope: global

--deps

Also analyze local path dependencies from build.zig.zon (.path entries only, not URL-based)

Default: false

Scope: global

--build-script

Include the build script module and everything it depends on to be analyzed

Default: false

Scope: global

-f, --format <FORMAT>

Output format

Default: pretty

Possible values: pretty, minimal, json

Scope: local

-F, --fail-fast <WHEN>

Stop after the first matching severity

Default: none

Possible values: none, error, warn, any

Scope: local

docent check style

Check naming-case and style rules

Check identifiers in the import-closure reachable from the project’s module roots. Severities are set in project config (.config/docent.toml). Exits non-zero when a denied rule reports a finding.

Parent: docent check

Synopsis

docent check style [OPTIONS] <paths>...

Arguments

<paths>…​

Files or directories to analyze. If omitted, uses package paths from build.zig.zon when available.

Variadic: accepts multiple values.

Options

--config-path <FILE>

Path to a docent.toml configuration file

Must point to a file, not a directory. When omitted, Docent searches upward from the working directory for .config/docent.toml.

Scope: global

--manifest-path <PATH>

Path to a build.zig.zon manifest or its parent directory

Operates as if Docent were invoked from the manifest’s directory. Accepts the manifest file directly or a directory containing it. When omitted, searches upward from the working directory.

Scope: global

--lib

Analyze library targets only (default)

Default: false

Scope: global

--bins

Analyze all binary targets

Default: false

Scope: global

--bin <STRING>…​

Analyze specific binary by name (repeatable)

Scope: global

--tests

Analyze all test targets

Default: false

Scope: global

--test <STRING>…​

Analyze specific test by name (repeatable)

Scope: global

--deps

Also analyze local path dependencies from build.zig.zon (.path entries only, not URL-based)

Default: false

Scope: global

--build-script

Include the build script module and everything it depends on to be analyzed

Default: false

Scope: global

-f, --format <FORMAT>

Output format

Default: pretty

Possible values: pretty, minimal, json

Scope: local

-F, --fail-fast <WHEN>

Stop after the first matching severity

Default: none

Possible values: none, error, warn, any

Scope: local

docent check complexity

Check function complexity

Measure cognitive and cyclomatic complexity for every function reachable from the project’s module roots. Thresholds are set in project config (.config/docent.toml). Exits non-zero when a denied rule reports a finding.

Parent: docent check

Synopsis

docent check complexity [OPTIONS] <paths>...

Arguments

<paths>…​

Files or directories to analyze. If omitted, uses package paths from build.zig.zon when available.

Variadic: accepts multiple values.

Options

--config-path <FILE>

Path to a docent.toml configuration file

Must point to a file, not a directory. When omitted, Docent searches upward from the working directory for .config/docent.toml.

Scope: global

--manifest-path <PATH>

Path to a build.zig.zon manifest or its parent directory

Operates as if Docent were invoked from the manifest’s directory. Accepts the manifest file directly or a directory containing it. When omitted, searches upward from the working directory.

Scope: global

--lib

Analyze library targets only (default)

Default: false

Scope: global

--bins

Analyze all binary targets

Default: false

Scope: global

--bin <STRING>…​

Analyze specific binary by name (repeatable)

Scope: global

--tests

Analyze all test targets

Default: false

Scope: global

--test <STRING>…​

Analyze specific test by name (repeatable)

Scope: global

--deps

Also analyze local path dependencies from build.zig.zon (.path entries only, not URL-based)

Default: false

Scope: global

--build-script

Include the build script module and everything it depends on to be analyzed

Default: false

Scope: global

-f, --format <FORMAT>

Output format

Default: pretty

Possible values: pretty, minimal, json

Scope: local

-F, --fail-fast <WHEN>

Stop after the first matching severity

Default: none

Possible values: none, error, warn, any

Scope: local

docent check size

Check source size limits

Measure source size limits such as line width and function parameter counts for every file reachable from the project’s module roots. Thresholds are set in project config (.config/docent.toml). Exits non-zero when a denied rule reports a finding.

Parent: docent check

Synopsis

docent check size [OPTIONS] <paths>...

Arguments

<paths>…​

Files or directories to analyze. If omitted, uses package paths from build.zig.zon when available.

Variadic: accepts multiple values.

Options

--config-path <FILE>

Path to a docent.toml configuration file

Must point to a file, not a directory. When omitted, Docent searches upward from the working directory for .config/docent.toml.

Scope: global

--manifest-path <PATH>

Path to a build.zig.zon manifest or its parent directory

Operates as if Docent were invoked from the manifest’s directory. Accepts the manifest file directly or a directory containing it. When omitted, searches upward from the working directory.

Scope: global

--lib

Analyze library targets only (default)

Default: false

Scope: global

--bins

Analyze all binary targets

Default: false

Scope: global

--bin <STRING>…​

Analyze specific binary by name (repeatable)

Scope: global

--tests

Analyze all test targets

Default: false

Scope: global

--test <STRING>…​

Analyze specific test by name (repeatable)

Scope: global

--deps

Also analyze local path dependencies from build.zig.zon (.path entries only, not URL-based)

Default: false

Scope: global

--build-script

Include the build script module and everything it depends on to be analyzed

Default: false

Scope: global

-f, --format <FORMAT>

Output format

Default: pretty

Possible values: pretty, minimal, json

Scope: local

-F, --fail-fast <WHEN>

Stop after the first matching severity

Default: none

Possible values: none, error, warn, any

Scope: local

docent check all

Run every check category

Run documentation, style, complexity, and size checks in one pass and print all diagnostics. Exits non-zero when a denied rule reports a finding.

Parent: docent check

Synopsis

docent check all [OPTIONS] <paths>...

Arguments

<paths>…​

Files or directories to analyze. If omitted, uses package paths from build.zig.zon when available.

Variadic: accepts multiple values.

Options

--config-path <FILE>

Path to a docent.toml configuration file

Must point to a file, not a directory. When omitted, Docent searches upward from the working directory for .config/docent.toml.

Scope: global

--manifest-path <PATH>

Path to a build.zig.zon manifest or its parent directory

Operates as if Docent were invoked from the manifest’s directory. Accepts the manifest file directly or a directory containing it. When omitted, searches upward from the working directory.

Scope: global

--lib

Analyze library targets only (default)

Default: false

Scope: global

--bins

Analyze all binary targets

Default: false

Scope: global

--bin <STRING>…​

Analyze specific binary by name (repeatable)

Scope: global

--tests

Analyze all test targets

Default: false

Scope: global

--test <STRING>…​

Analyze specific test by name (repeatable)

Scope: global

--deps

Also analyze local path dependencies from build.zig.zon (.path entries only, not URL-based)

Default: false

Scope: global

--build-script

Include the build script module and everything it depends on to be analyzed

Default: false

Scope: global

-f, --format <FORMAT>

Output format

Default: pretty

Possible values: pretty, minimal, json

Scope: local

-F, --fail-fast <WHEN>

Stop after the first matching severity

Default: none

Possible values: none, error, warn, any

Scope: local

docent fmt

Format Zig source code

Filesystem-based formatter: recursively walks directories and formats every .zig / .zon file, including orphans not reachable from a module root. Path filters may be set in .config/docent.toml under [fmt].include / [fmt].exclude (Deno-style); CLI paths override include, and CLI --exclude merges with config exclude.

Parent: docent

Synopsis

docent fmt [OPTIONS] <paths>...

Arguments

<paths>…​

Files or directories to format. If omitted, uses [fmt].include from config when set.

Variadic: accepts multiple values.

Options

--stdin

Format source from stdin and write the result to stdout

Scope: local

--check

List non-conforming files and exit with an error if the list is non-empty

Scope: local

--ast-check

Validate formatted source with Zig’s AST checker

Scope: local

-f, --format <FORMAT>

Output format for --check mode

Default: pretty

Possible values: pretty, minimal

Scope: local

--exclude <PATH>…​

Exclude file or directory from formatting (merged with [fmt].exclude)

Scope: local

--zon

Treat all input files as ZON, regardless of file extension

Scope: local

docent typeset

Generate docs.json for Typst-based PDF documentation

Discovers a package’s modules (or walks explicit paths) and emits docs.json for rendering by the Typst template in typst/docent-docs/. Does not invoke typst itself; see the docs-pdf build step for the full docs.json -\> PDF pipeline.

Parent: docent

Synopsis

docent typeset [OPTIONS] <paths>...

Arguments

<paths>…​

Explicit module root file(s). If omitted, discovers targets from build.zig.

Variadic: accepts multiple values.

Options

--lib

Document library targets (default when no bin/test filters are set)

Default: false

Scope: local

--bins

Document all executable targets

Default: false

Scope: local

--bin <STRING>…​

Document a specific executable by name (repeatable)

Scope: local

--tests

Document all test targets

Default: false

Scope: local

--test <STRING>…​

Document a specific test target by name (repeatable)

Scope: local

--deps

Also document direct local .path dependencies from build.zig.zon as appendix modules

Default: false

Scope: local

--deps-recursive

With --deps, also recurse into nested .path dependencies (e.g. vereda -\> xdg)

Default: false

Scope: local

--include-private

Include non-public declarations

Default: false

Scope: local

--module-name <NAME>

Name for the module (single explicit path only; used to build fully-qualified decl ids). Defaults to the file stem.

Scope: local

-o, --output <PATH>

Path to write docs.json to

Default: docs.json

Scope: local

--external-refs <PATH>…​

Load a dependency’s published reference sidecar (repeatable). See --refs-output.

Scope: local

--refs-output <PATH>

Also write a reference sidecar (id -\> --refs-doc-url) for dependents to consume via --external-refs

Scope: local

--refs-doc-url <URL>

URL recorded in the sidecar for every id (required with --refs-output)

Scope: local

--bundle-std

Bundle referenced std.* declarations into the appendix instead of linking to ziglang.org (requires zig on PATH)

Default: false

Scope: local

docent docs

Generate AsciiDoc documentation for this CLI

Parent: docent

Synopsis

docent docs [OPTIONS]

Options

-o, --output-dir <STRING>

Output directory where the AsciiDoc documentation is written.

Default: zig-out/docs

Scope: local

-f, --file <STRING>

Output file name.

Default: docent.adoc

Scope: local

--template <STRING>

Optional path to a custom Trama template file (AsciiDoc).

Scope: local

docent completion

Generate shell completion scripts

Parent: docent

Synopsis

docent completion [OPTIONS] <shell>

Arguments

<shell>

Target shell.

Required when present in the synopsis.

Possible values: bash, zsh, fish, pwsh, nu

docent help

Print this message or the help of the given subcommand(s)

Parent: docent

Synopsis

docent help [COMMAND]...