> ## Documentation Index
> Fetch the complete documentation index at: https://xspec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField path="--json" type="flag">
  Emit a single JSON document on stdout. For `query` and `review export`, JSON is always emitted regardless of this flag.
</ParamField>

<ParamField path="--config" type="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.
</ParamField>

## 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.