xspec CLI Reference: Commands and Conventions

Complete reference for xspec CLI conventions: global flags, argument rules, exit codes, output streams, freshness model, and concurrency guarantees.

The xspec CLI gives you a consistent interface for building, inspecting, querying, and refactoring your requirement graph. All commands follow the same flag syntax, stream assignment, and exit-code contract so you can compose them reliably in scripts and CI pipelines.

Commands

Command	Purpose
build	Parse sources, validate, generate TypeScript and Markdown, write graph data
check	Everything build validates, plus staleness, policy, and review session integrity — writes nothing
ids	List requirement IDs as a flat or tree view
show	Print full detail for a single node
coverage	Measure how much of the requirement graph your code and tests cover
impact	Compare the current workspace against a git baseline and show impacted code
review	Create and manage staged review sessions
query	JSON-first graph access for scripts and automation
rename	Rename a requirement ID and rewrite every reference
move	Relocate a file or section and rewrite every reference

Global flags

--json · flag

Emit a single JSON document on stdout. For query and review export, JSON is always emitted regardless of this flag.

--config · path

Use the specified config file instead of searching upward from the current working directory. This path is resolved relative to the filesystem, not the workspace root.

Flag syntax

• Flags use space separation: --config path/to/xspec.json, not --config=path/to/xspec.json.
• Each flag may appear at most once per invocation.
• List-valued flags accept a comma-separated value: --kinds depends,embeds.

Argument conventions

All arguments that refer to workspace locations — <node>, <graph-node>, <file>, and --file — are workspace-relative paths, resolved from the workspace root regardless of your current working directory. The only exceptions are --config and --test-hold, which are resolved relative to your filesystem working directory.

A node argument takes the form path#id to reference a specific node, or a bare path to reference the file root node. A graph-node argument additionally accepts code-location syntax: path, path#unit, or path#unit@N.

Output streams

• Human-readable reports are written to stdout.
• Usage errors and configuration errors are written to stderr.
• When --json is active, stdout contains only the JSON document — no mixed output.

All output is byte-deterministic: running the same command twice on the same inputs produces identical bytes. When a shortest path is reported and ties exist, xspec breaks them byte-lexicographically.

Exit codes

Code	Class	Meaning
0	Success	Clean build or check; all informational commands (ids, show, impact, query, coverage without --check)
1	Findings	build on invalid sources; check findings; coverage --check with uncovered nodes; refused rename/move; refused review operations; corrupt review session
2	Usage / config error	Unknown command, flag, or value; missing arguments; unknown profile, session, group, node, or file; invalid or missing config; unreadable baseline; mutating command blocked by concurrency lock
70	Internal error	A crash — please report it

Freshness model

build is the only command that (re)generates TypeScript modules and Markdown files. Read commands — ids, show, coverage, impact, review, and query — automatically refresh graph data if it is stale, but they never regenerate TypeScript or Markdown. If sources fail validation during an auto-refresh, read commands report the errors and exit 1. check never refreshes anything: it treats stale or orphaned derived files as findings.

Concurrency

Mutating commands (rename, move, and the review subcommands create, resolve, and split) are mutually exclusive per workspace. If a second mutating command is attempted while one is already running, it fails immediately with exit 2. Non-mutating commands can run concurrently without restriction. All file writes are atomic in effect.