CLI Reference

Process AsciiDoc files to populate the traceability graph.

Generate traceability matrices from processed items.

Validate the traceability graph for dangling references (missing targets), invalid relations, duplicate item IDs, and circular references.

Exits with non-zero code if errors are found.

Export the graph to Neo4j-compatible formats. Supply either -i <dir> (a local directory) or a playbook path (every component and repository in the playbook).

Display role statistics for the current graph.

Output shows item counts per role and relationship counts.

List all available presets with descriptions.

Show a preset’s configuration details.

Write a preset’s traceability YAML to a file for customization.

Get the next available sequential ID for a given prefix.

Auto-detects padding from existing IDs. If REQ-001 and REQ-002 exist, returns REQ-003. If TST-0001 exists, returns TST-0002. With no existing items matching the prefix, defaults to 3-digit padding (REQ-001).

When idAllocation.endpoint is configured, next-id requests the next ID from the allocator and prints its id verbatim. A configured-but-unreachable allocator, a non-2xx response, or a malformed body exits with an error instead of falling back to a local ID. Pass --local to override. See Configuration Reference for the idAllocation key and Run the ID allocation server for the service.

Export allocator seed values for the ID allocation server. For each ID prefix found in the scanned items, it reports the numeric max+1 value as a start seed, so the server continues from existing local IDs instead of colliding at 001.

The command accepts either -i <dir> (scan a directory) or a playbook path (harvest every component and repository in the playbook).

The output is a prefixes: map consumable directly as the server’s seed configuration:

start is max+1 — the first ID the server allocates — never the current maximum and never a formatted REQ-055 string. See Run the ID allocation server for the seeding workflow.

Resolve and report the authoring guidance for a role. Prints the resolved guidance page path and the ID prefix fallback:

Exits non-zero with "No guidance for role" when the role has no roleGuidance entry. The idPrefix is advisory; existing project conventions win.

Query the traceability graph directly from the command line — no Antora build required. Parses your .adoc source files and answers one structural question per invocation.

Subcommands:

Exit codes: 0 for success (including empty results), 1 for an unknown item ID or when no path exists.

Inspect supersession relationships without an Antora build. The check subcommand reports whether an item has been superseded, its direct successors, and every functional link that still targets it and therefore requires review.

The command is read-only: it never modifies source files. A superseded item is identified by an incoming supersedes relationship, not by a status attribute. History relationships (supersedes / superseded_by) are excluded from the review list.

Move a superseded item’s block to the module’s parallel superseded.adoc page. The block is removed from its source file and appended to superseded.adoc in the same directory, which is created with a heading if missing.

Only superseded items can be archived — a non-superseded or unknown ID is rejected with no file change.

Remove an orphaned or isolated item’s block from its source file. Orphaned items (superseded, no incoming functional links) are removed after a y/N confirmation; isolated items (no relationships at all) require typing the item ID verbatim.

The command previews the block before prompting. Any other item (neither orphaned nor isolated) is rejected with no file change. Git preserves history, so removal is safe once an item is orphaned.

Diff two sets of AsciiDoc sources into a traceability delta. Builds two graphs (baseline and changed) and reports items added, removed, and modified, plus relationship changes on surviving items.

Items are matched by stable ID, so the diff works with any role or relation vocabulary. A modified item lists the changed fields (title, content, role, status, attributes). Relationship changes are reported only for items that survive the diff, except supersedes history links. The command never modifies source files.

Build the full cross-source traceability graph from an Antora playbook and emit a canonical JSON snapshot. The harvest runs Antora’s content aggregation and classification stages only — no HTML, PDF, or DOCX output is produced — so it captures items from every content source, component, and version the playbook resolves.

Each item in the snapshot carries component, module, and version scope. The snapshot is versioned (format: 1) and omits per-page pubUrl fields.

Requires the optional @antora/content-aggregator, @antora/content-classifier, and @antora/playbook-builder packages.

When the playbook’s extension config sets excludeComponents, the harvest omits those components so the snapshot matches the graph the Antora build produces. The same exclusion applies to export neo4j and seed when given a playbook.

Diff two JSON graph snapshots into a traceability delta without checking out either version’s sources. The snapshots are produced by site-graph (or by the extension’s per-version graph.json attachment).

Items are matched by component-qualified identity (component + version + ID), falling back to bare ID for items without a component. An unknown format value is rejected with a prompt to re-run site-graph.