TraceSpec CLI

tracespec is the npm-distributed CLI for TraceSpec Semantic Model V2 graph workspaces.

TraceSpec stores engineering knowledge as YAML-authored puzzle pieces in Git, then projects that graph into validation diagnostics, graph views, impact analysis, readiness views, baselines, and delivery artifacts.

Install

npm install -g @tracespec/cli
tracespec --help

or run directly:

npx @tracespec/cli --help

Node.js 22 or newer is required.

Start A Workspace

Create a normal TraceSpec workspace:

tracespec init --full
tracespec validate --gate semantic-quality

For a safe agent-assisted draft area, create a proposal workspace outside the canonical authored spec/ tree:

tracespec init --proposal launch-summary
tracespec validate .tracespec/proposals/launch-summary --gate semantic-quality
tracespec graph .tracespec/proposals/launch-summary --focus REQ-LAUNCH-SUMMARY --depth 2
tracespec impact REQ-LAUNCH-SUMMARY .tracespec/proposals/launch-summary --json
tracespec readiness .tracespec/proposals/launch-summary

Proposal workspaces are review material. Copy accepted YAML into canonical spec/ only after an explicit review/apply decision.

Common Commands

tracespec init --minimal
tracespec init --full
tracespec init --proposal <slice-id>
tracespec contract init <interface-id> --format json-schema
tracespec validate --gate semantic-quality
tracespec list
tracespec list --type Requirement --tag security --json
tracespec search "tool policy" --types Requirement,Component --json
tracespec query --type Requirement --tag security --json
tracespec query --from REQ-123 --relationship verifies --json
tracespec inspect <piece-id> --json
tracespec links <piece-id> --incoming --json
tracespec neighborhood <piece-id> --depth 1 --json
tracespec matrix
tracespec graph
tracespec graph --focus <piece-id> --depth 2
tracespec graph --impact <piece-id> --depth 2 --json
tracespec impact <piece-id> --json
tracespec impact <piece-id> --summary --max-items 50 --json
tracespec readiness
tracespec baseline create R2026.4
tracespec baseline create R2026.4 --scope requirements-only
tracespec export graph-index
tracespec export backlog-pack R2026.4
tracespec export engineering-work-pack R2026.4
tracespec export delivery-pack <piece-id> --mode authoring --format grill-prompt-pack

Path-explicit variants are also supported:

tracespec validate path/to/workspace --gate semantic-quality
tracespec graph path/to/workspace --json
tracespec impact REQ-123 path/to/workspace --json
tracespec baseline create path/to/workspace R2026.4
tracespec export backlog-pack path/to/workspace R2026.4

When a path is omitted, commands resolve the workspace from tracespec.config.json or fall back to the current directory.

Diagnostics

tracespec validate --gate semantic-quality reports Semantic Model V2 graph quality diagnostics: malformed YAML, unknown piece types, broken relationship targets, weak relationships, missing verification paths, unresolved risks, unsupported assumptions, and missing Evidence or DesignArtifact source metadata.

Graph exploration is also diagnostic-aware. For example, tracespec graph --focus UNKNOWN and tracespec graph --impact UNKNOWN return clear missing-ID diagnostics. JSON output includes deterministic machine-readable diagnostic entries.

For diagnostic meanings and canonical fixes, see the TraceSpec repository documentation: docs/reference/diagnostics.md.

Graph, Impact, And Readiness

Use compact graph navigation commands when an AI coding agent or local tool needs a small amount of context without full impact expansion:

tracespec inspect REQ-123 --json
tracespec links REQ-123 --incoming --outgoing --json
tracespec neighborhood REQ-123 --depth 1 --json
tracespec list --type Requirement --tag security --lifecycle active --json
tracespec search "tool policy" --types Requirement,Component --limit 20 --json
tracespec query --type Requirement --tag security --relationship verifies --json

Graph navigation commands print graph-navigation.v1 JSON with compact node summaries, source paths, metadata summaries, and relationship edges. Semantic search prints semantic-search.v1 JSON with ranked compact node results, matched-field snippets, scores, and source paths. Both projections are generated from authored YAML and are not semantic source of truth.

tracespec search <query> is local deterministic text search over node IDs, titles, summaries/descriptions, tags, contexts, source paths, and selected metadata fields. It does not use embeddings, vector search, or a live AI provider. The default result limit is 20 and the command accepts --limit values from 1 to 100. Use --types Requirement,Component to filter by canonical or YAML-authored type, and --context <id> when a workspace has multiple contexts.

tracespec graph [path] --json prints a deterministic graph.v1 explorer projection with canonical Semantic Model V2 nodes, relationships, categories, source paths, validation state, and optional focused-neighbourhood or impact-neighbourhood metadata. The projection is generated from authored YAML and is not a semantic source of truth.

tracespec impact <piece-id> [path] --json prints the full impact.v2 projection that groups affected pieces by intent, design, governance, verification, and evidence. This detailed mode remains the default automation contract for complete impact analysis.

For routine agent context gathering, use tracespec impact <piece-id> [path] --summary --max-items 50 --json. Summary mode prints impact-summary.v1 JSON with the focal node, compact bounded impact groups, relationship path summaries, source paths, counts, and truncation flags. The default summary limit is 50 and the command accepts --max-items values from 1 to 100.

tracespec readiness [path] --json prints graph-derived confidence across Intent, Design, Governance, Verification, and Evidence. Readiness is a projection, not a lifecycle stage.

Interface Contracts

Use tracespec contract init <interface-id> [path] --format json-schema to create an active ContractArtifact, its defines relationship, and a valid starter JSON Schema under assets/contracts/. Optional --artifact-id and --contract-path flags override deterministic defaults; --validation-command records metadata without executing the command.

Contract validation is offline. JSON Schema object and Boolean forms are parsed, but remote HTTP(S) $ref values are reported rather than fetched. Unsupported formats retain descriptor validation and are not scaffolded yet.

Generated Graph Index

tracespec export graph-index [path] writes a compact generated graph index to .tracespec/out/graph.json by default. Use --out <file> to write somewhere else.

The index uses graph-index.v1 JSON with compact node summaries, relationship edges, source paths, tags, lifecycle, release, and basic metadata summaries. It is generated output for local tools and agents. Canonical truth remains the YAML under spec/, and validation, impact, search, inspect, links, and neighborhood commands do not require the index.

tracespec query [path] reads the generated index and returns graph-index-query.v1 output. It supports exact structured filters over the index: --type, --tag, --lifecycle, --release, --context, --source-path, --from, --to, and --relationship. Use --index <file> to query a non-default graph index. The default query path reads the generated JSON index only; it does not reparse authored YAML.

Regenerate the index after changing authored YAML or workspace topology. Agent tools should treat the file as stale whenever the Git working tree has newer spec/ changes than the exported index or when the file is missing.

Published Packages

From the 0.5.0 CLI milestone onward, the published runtime package set is:

• @tracespec/model
• @tracespec/workspace
• @tracespec/analysis
• @tracespec/delivery
• @tracespec/cli

The retired @tracespec/core, @tracespec/req, and @tracespec/arch packages are not active compatibility surfaces for new releases.

Versioning And Releases

• This package is independently versioned from the monorepo root.
• Release tags use cli-vX.Y.Z.
• The tag version must match packages/cli/package.json.
• Runtime workspace package versions must align with the CLI package version for numbered milestones.