How to Query the Graph from the Command Line

The query command parses your AsciiDoc source files and answers structural questions about your traceability graph. It does not require an Antora build, so it works from any directory in your project.

Find what references an item

Before you change or remove an item, find everything that points at it:

npx antora-tracer query reverse REQ-005

The output lists each referencing item with its role, the relationship type, and the source file and line:

ID       Role   Relation   File                    Line
ARC-017  design addresses  pages/architecture.adoc  323
TST-001  test   verifies   pages/test-plan.adoc      17

Add --json for machine-readable output:

npx antora-tracer query reverse REQ-005 --json

Find the impact of changing an item

impact lists every item transitively connected to the given ID:

npx antora-tracer query impact REQ-005

Find forward-linked items by role

linked follows outgoing relationships from the starting item across any number of links, including through items with other roles. It returns each reachable item of the requested role once and does not follow inbound-only relationships.

npx antora-tracer query linked CHG-001 requirement -i docs/

For a complete graph spanning Antora components or repositories, generate a canonical snapshot and query it:

npx antora-tracer site-graph antora-playbook.yml --out graph.json
npx antora-tracer query linked CHG-001 requirement --snapshot graph.json

Multi-source queries require item IDs to be globally unique across every source in the snapshot. Use @antora-tracer/id-server to allocate IDs, seeded from the same playbook with npx antora-tracer seed antora-playbook.yml -o seeds.yml. Authors whose sources can be merged must share an allocation tenant and prefix settings; separate tenants with the same prefixes allocate overlapping IDs. Regenerate the snapshot after source changes.

Find isolated items

isolated lists items with no relationships in either direction:

npx antora-tracer query isolated
npx antora-tracer query isolated --role requirement

Find orphaned items

orphaned lists superseded items with no incoming functional links — the items that are safe to archive or remove:

npx antora-tracer query orphaned
npx antora-tracer query orphaned --role requirement

Extract all items of a role from one document

by-role returns the current items of a role as a document-ordered slice — the input an abstraction-level review needs:

npx antora-tracer query by-role design --document explanation/architecture --context --json

The JSON carries each item’s ID, title, content, and source line, plus — with --context — a skeleton of the document’s other-role items (ID and title only) as relocation context.

Review the slice for abstraction drift: an item written at a different altitude than its same-role siblings needs a rewrite; an item in the wrong section of the right document needs a move; an item that reads like a different role needs investigation.

For a cross-repository slice, query a snapshot instead:

npx antora-tracer site-graph antora-playbook.yml --out graph.json
npx antora-tracer query by-role design --document architecture --snapshot graph.json --json

Find a path between two items

path prints the shortest relationship chain between two items:

npx antora-tracer query path TST-001 REQ-001
TST-001 --tests--> IMP-001 --implements--> DES-001 --addresses--> REQ-001

Scope the search

By default query scans the current directory. Point it at a specific directory or file:

npx antora-tracer query reverse REQ-005 -i modules/ROOT/pages/
npx antora-tracer query orphaned -i requirements.adoc

Related