Skip to main content

CLI Reference

The trf CLI (@traceweave/trf) is the unified interface for validating, building, analyzing, and querying TWPack files. All functionality is provided through four main commands.

Installation​

npm install -g @traceweave/trf

validate​

Validate .twpack files against the twpack 2.1 schema.

trf validate <files...> [options]

Arguments:

  • <files...> - One or more .twpack files to validate

Options:

  • -v, --verbose - Show detailed validation information
  • -q, --quiet - Only show errors
  • -h, --help - Display help

Examples:

# Validate a single file
trf validate my-pack.twpack

# Validate multiple files
trf validate pack1.twpack pack2.twpack pack3.twpack

# Verbose output
trf validate my-pack.twpack --verbose

# Quiet mode (only errors)
trf validate my-pack.twpack --quiet

build​

Create .twpack files programmatically.

trf build create [options]

Options:

  • -i, --id <id> - Pack ID (required)
  • -t, --title <title> - Pack title (required)
  • -a, --artifacts <path> - Path to artifacts.json file
  • -l, --links <path> - Path to links.json file
  • -p, --provenance <path> - Path to provenance.json file (optional)
  • -o, --output <path> - Output .twpack file path (required)
  • -h, --help - Display help

Examples:

# Build a pack with artifacts and links
trf build create \
  --id "my-project:v1.0" \
  --title "My Traceability Pack" \
  --artifacts ./artifacts.json \
  --links ./links.json \
  --output ./my-pack.twpack

# Include provenance
trf build create \
  -i "project:v2.0" \
  -t "Release 2.0" \
  -a ./artifacts.json \
  -l ./links.json \
  -p ./provenance.json \
  -o ./release-2.0.twpack

analyze​

Perform graph analytics on .twpack files.

stats​

Show graph statistics.

trf analyze stats -f <file>

Options:

  • -f, --file <path> - Path to .twpack file (required)

Example:

trf analyze stats -f my-pack.twpack

Output:

📊 Graph Statistics

Total Artifacts: 8
Total Links: 7
Average In-Degree: 0.88
Average Out-Degree: 0.88
Isolated Artifacts: 0

Artifacts by Kind:
  requirement: 3
  test: 2
  design: 2
  component: 1

Links by Relation:
  verified_by: 3
  implements: 2
  tests: 2

impact​

Analyze the downstream impact of changing an artifact.

trf analyze impact -f <file> -a <artifact-id>

Options:

  • -f, --file <path> - Path to .twpack file (required)
  • -a, --artifact <id> - Artifact ID to analyze (required)

Example:

trf analyze impact -f my-pack.twpack -a req:SAFETY-001

Output:

🔍 Impact Analysis: req:SAFETY-001

Total Impacted: 4 artifacts

Impacted Artifacts:
  [1] design:ARCH-001 (design)
      Path: req:SAFETY-001 → design:ARCH-001
  [2] test:UNIT-001 (test)
      Path: req:SAFETY-001 → test:UNIT-001
  ...

root-cause​

Analyze dependencies (backward traversal).

trf analyze root-cause -f <file> -a <artifact-id>

Options:

  • -f, --file <path> - Path to .twpack file (required)
  • -a, --artifact <id> - Artifact ID to analyze (required)

Example:

trf analyze root-cause -f my-pack.twpack -a test:INTEGRATION-001

coverage​

Analyze traceability coverage.

trf analyze coverage -f <file> -k <kind> [-r <relation>]

Options:

  • -f, --file <path> - Path to .twpack file (required)
  • -k, --kind <kind> - Artifact kind to analyze (required)
  • -r, --relation <relation> - Specific relation to check (optional)

Examples:

# Coverage for all requirements
trf analyze coverage -f my-pack.twpack -k requirement

# Coverage for requirements with verified_by relation
trf analyze coverage -f my-pack.twpack -k requirement -r verified_by

Output:

📈 Coverage Analysis: requirement (verified_by)

Coverage: 100.0%
Covered: 3/3

Uncovered artifacts: (none)

paths​

Find all paths between two artifacts.

trf analyze paths -f <file> --from <id> --to <id>

Options:

  • -f, --file <path> - Path to .twpack file (required)
  • --from <id> - Start artifact ID (required)
  • --to <id> - End artifact ID (required)

Example:

trf analyze paths -f my-pack.twpack --from req:REQ-001 --to test:TEST-005

query​

Execute queries on .twpack data.

artifacts​

Get artifacts by kind or relation.

trf query artifacts -f <file> [-k <kind>] [-r <relation>] [--json]

Options:

  • -f, --file <path> - Path to .twpack file (required)
  • -k, --kind <kind> - Filter by artifact kind
  • -r, --relation <relation> - Filter by relation
  • --json - Output as JSON

Examples:

# Get all requirements
trf query artifacts -f my-pack.twpack -k requirement

# Get all artifacts with verified_by relation
trf query artifacts -f my-pack.twpack -r verified_by

# JSON output
trf query artifacts -f my-pack.twpack -k test --json

Get links by relation.

trf query links -f <file> [-r <relation>] [--json]

Options:

  • -f, --file <path> - Path to .twpack file (required)
  • -r, --relation <relation> - Filter by relation
  • --json - Output as JSON

Example:

trf query links -f my-pack.twpack -r verified_by

sql​

Execute raw SQL queries.

trf query sql -f <file> -q <query>

Options:

  • -f, --file <path> - Path to .twpack file (required)
  • -q, --query <sql> - SQL query to execute (required)

Examples:

# Count artifacts by kind
trf query sql -f my-pack.twpack \
  -q "SELECT kind, COUNT(*) as count FROM artifacts GROUP BY kind"

# Find all tests with 'passed' status
trf query sql -f my-pack.twpack \
  -q "SELECT id, title FROM artifacts WHERE kind = 'test' AND json_extract(fields, '$.status') = 'passed'"

# Complex join query
trf query sql -f my-pack.twpack \
  -q "SELECT a.id, a.title, l.relation, b.title FROM artifacts a JOIN links l ON a.id = l.from_id JOIN artifacts b ON l.to_id = b.id"

Global Options​

  • -h, --help - Display help for any command
  • -V, --version - Output the version number

Exit Codes​

  • 0 - Success
  • 1 - Validation failure or error

Help​

Get help for any command:

trf --help
trf validate --help
trf build --help
trf analyze --help
trf query --help

Programmatic Usage​

All CLI functionality is also available programmatically:

const {
  validateTwpack,
  TwpackBuilder,
  TwpackAnalyzer,
  TwpackQuery
} = require('@traceweave/trf');

// See individual package documentation for API details

See Also​