Skip to main content
query is the JSON-native interface to the xspec requirement graph. Every subcommand emits JSON unconditionally — no --json flag is needed. Use query when you are writing scripts, CI tools, or editor integrations that need structured graph data.

​
Node vs graph-node

Two argument types appear across query subcommands:
  • <node> — a workspace-relative spec reference: path#id for a named node, or a bare path for the file root node. Only spec nodes are valid here.
  • <graph-node> — a superset of <node> that also accepts code locations: path for a file root, path#unit for a named code unit, or path#unit@N for a specific occurrence within a unit.

​
Subcommands

​
query node

Return the complete record for a single spec node.
Returns: identity, source range, own text, subtree text, all four hashes (ownHash, subtreeHash, effectiveHash, metadataHash), tags, coverage attribute, and all incoming and outgoing edges grouped by kind.

​
query nodes

Return one row per node in the workspace, with optional filters.
​
string
Restrict to nodes belonging to the named spec group. Accepts a spec group name only — not a file path.
​
glob
Restrict to nodes defined in files matching the given workspace-relative glob.
​
string
Restrict to nodes carrying the given tag.
​
string
Restrict by coverage attribute. Accepted values: required, none.
All filters combine conjunctively — a node must satisfy every provided filter to appear in the results. Returns: one object per matching node with identity, source range, tags, and coverage attribute.

​
query edges

Return all edges in the graph, with optional filters.
​
graph-node
Restrict to edges originating from this graph node.
​
graph-node
Restrict to edges terminating at this graph node.
​
string
Comma-separated list of edge kinds to include. Valid values: contains, depends, embeds, references.
Returns: one object per matching edge with from, to, and kind fields.

​
query subtree

Return the node and all of its descendants in document order.
Returns: one object per node (the root plus all descendants) with identity, source range, tags, and coverage attribute.

​
query ancestors

Return the proper ancestors of a node, nearest-first.
Returns: one object per ancestor node (not including the node itself) with identity, source range, tags, and coverage attribute. The immediate parent is first; the file root is last.

​
query reachable

Determine whether one graph node can reach another through the edge graph, and return the shortest path if so.
​
graph-node
required
The starting node for the reachability search.
​
graph-node
required
The target node.
​
string
Comma-separated edge kinds to traverse. Accepts only the three dependency kinds: depends, embeds, references. contains edges are not traversable here.
Returns: a path array with the identity strings along the shortest path, and a reachable boolean. If reachable is false, the path array is empty.
When multiple shortest paths exist, xspec selects the one that sorts first byte-lexicographically.

​
Always-JSON behavior

Unlike other xspec commands, query never produces human-readable output. All subcommands emit JSON unconditionally — passing --json is valid but has no additional effect. Pipe the output directly into jq or any JSON-aware tool.