CLI Reference

Generate shell completion scripts for Bash, Zsh, or Fish, or install one for the current user. Generation writes the script to standard output, so redirect it to save a copy or inspect it.

Installation writes to ~/.local/share/bash-completion/completions/antora-tracer for Bash, ~/.zfunc/_antora-tracer for Zsh, and ~/.config/fish/completions/antora-tracer.fish for Fish. It prints the completion path and activation steps without editing shell startup files.

For Bash, source the installed file in the current shell; add the printed source command to ~/.bashrc yourself if you want it loaded in future sessions. For Zsh, add fpath=(~/.zfunc $fpath) and autoload -Uz compinit && compinit to ~/.zshrc, before any other compinit call. Fish automatically loads completion files from its completion directory in new sessions.

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. If the configured token references an unset environment variable, remote next-id exits with an error before making the request. Pass --local to scan locally without requiring the remote token. 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.

Copy Antora Tracer’s bundled Agent Skills to supported harness per-user directories. Without harness arguments in an interactive terminal, it prompts for a multi-select choice; with explicit harness names it installs without further prompting.

Harnesses: pi (copies to ~/.agents/skills/), claude (copies to ~/.claude/skills/), and codex (copies to ~/.codex/skills/).

The command never replaces an existing skill directory by default. Without --overwrite, conflicts are skipped in non-interactive mode and prompted individually in interactive mode.

When pi is selected, the command prints a note that installing @antora-tracer/core as a Pi package auto-discovers its skills and is the recommended approach.

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.

linked <id> <role> follows outgoing relationships any number of edges, traversing through items of every role and excluding the start item. For a multi-source snapshot, IDs must be globally unique across included sources; use @antora-tracer/id-server seeded with antora-tracer seed antora-playbook.yml and shared allocation tenant and prefix settings.

by-role <role> lists all current (non-superseded) items of the role in document order — source file, then line — carrying each item’s ID, title, content, and source location, which is the input an abstraction-level review or LLM judge consumes. --document <path> restricts the slice to one document by path-segment suffix, so --document architecture matches explanation/architecture. --context adds a skeleton of the matched documents' other-role items (ID, title, role, line — no content), giving a judge relocation context without paying for full bodies. JSON output is { items: […​], context? }.

siblings <id> traverses relationships undirected: an item’s neighbors are both its outgoing targets and incoming sources, because every relation has a declared reverse. Two items are siblings when they connect to a common neighbor through the same relation type. Each result lists the shared neighbors that make the items siblings, plus whether the sibling is superseded — a superseded sibling is often the more interesting review signal. --relation <type> restricts discovery so that only edges of that relation type contribute, on both the queried item’s side and the sibling’s side.

For a cross-source graph, build a snapshot with antora-tracer site-graph <playbook> and pass it via --snapshot; sibling discovery then spans every source the playbook resolves. --snapshot and --input cannot be combined.

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.