Skip to main content

CLI Workflow Recipes

This guide collects common CLI workflows once you are past the introductory quick start. Use it as a reference for day-to-day TRF operations.

Map heterogeneous sources​

tw build out/integration.twpack \
  --source requirements/**/*.md requirement \
  --source design/**/*.yaml design \
  --source src/**/*.c component \
  --source tests/results/**/*.json test \
  --extension automotive \
  --profile automotive_safety
  • Globs expand to multiple folders across the repository.
  • Use relative paths; the CLI records them in manifest.json for provenance.
  • Combine multiple --source options to collect different artifact kinds.

Incremental rebuilds​

tw build out/traceability.twpack --config trf.yaml --watch
  • Watches the listed source paths for changes.
  • Rebuilds the TWPack and reruns validation automatically.
  • Emits desktop notifications (when supported) for quick feedback.

Stop the watcher with Ctrl+C once the pack is stable.

Use profiles selectively​

tw build out/smoke.twpack --config trf.yaml --profile minimal
tw build out/full.twpack --config trf.yaml --profile automotive_safety

Profiles let you ship lightweight packages for rapid iteration and full evidence packs for formal reviews without rewriting mappings.

tw build out/traceability.twpack \
  --config trf.yaml \
  --links-from csv://scripts/manual-links.csv \
  --links-from json://scripts/generated-links.json
  • Use csv:// or json:// to import links generated by other tools.
  • Each link record requires from, to, and relation fields; optional confidence and rationale values are preserved.

Detect coverage gaps automatically​

tw coverage out/traceability.twpack --from requirement --to test --fail-under 0.95
  • Fails with exit code 1 if requirement → test coverage drops below 95%.
  • Combine with CI to block merges that reduce verification completeness.

Chain validation in CI/CD​

steps:
  - name: Install TRF CLI
    run: curl -sSL https://get.trf.dev | sh
  - name: Build package
    run: tw build --config trf.yaml --output out/${{ github.sha }}.twpack
  - name: Validate package
    run: tw validate out/${{ github.sha }}.twpack --full
  - name: Publish artifact
    uses: actions/upload-artifact@v4
    with:
      name: traceability-${{ github.sha }}
      path: out/${{ github.sha }}.twpack

This pattern keeps evidence aligned with every commit and makes TWPack files downloadable from CI artifacts.

Keep large packs manageable​

git lfs track "*.twpack"
git add .gitattributes
  • Git LFS stores binary packages efficiently and avoids bloating the repository.
  • Use semantic naming (e.g., safety-case-2024Q4.twpack) to make history easy to navigate.