Running Trace
Trace can be run from the command line, from the macOS app, or from the Windows app. All three paths use the same core workbook loader and report engine, and all three now support the same explicit validation profiles: generic, medical, aerospace, and automotive.
CLI
Basic usage
rtmify-trace my-template.xlsx
This writes my-template.docx alongside the input file. The default output format is Word.
All flags
| Flag | Description |
|---|---|
| <workbook.xlsx> | Path to the input workbook. Required for report generation. |
| --format <fmt> | Output format: md, docx, pdf, or all. Default: docx. |
| --output <path> | Output path. Directory: writes derived-name files inside it. File: used as the literal output path. Omitted: writes beside the input file. |
| --project <name> | Project name to embed in report headers. |
| --strict | Exit non-zero if gaps are detected. Use in CI pipelines to gate on traceability completeness. |
| --gaps-json <path> | Write a machine-readable gap and diagnostics file at the given path. |
| --profile <name> | Validation profile: generic, medical, aerospace, or automotive. Default: generic. |
| license info [--json] [--license <path>] | Show signed-license status and, optionally, payload details. Does not generate a report. |
| license install <path> | Verify and install a signed license file. Does not generate a report. |
| license clear | Remove the installed license file. Does not reset the one-free-run marker. |
| --license <path> | Use a specific signed license file for this run. |
| --version | Print the Trace version and exit. |
| --help | Print usage and exit. |
Common invocations
Generate all three formats
rtmify-trace my-template.xlsx --format all
Write outputs to a specific directory
rtmify-trace my-template.xlsx --format all --output ./reports/
CI: fail the build if gaps exist
rtmify-trace my-template.xlsx --format md --strict --gaps-json gaps.json
Run profile-aware validation
rtmify-trace my-template.xlsx --profile medical --format pdf
Install a signed license file
rtmify-trace license install /path/to/license.json
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. Report generated, no fatal errors. |
| 1 | Input error. File not found, not a valid .xlsx, schema failure, or unresolvable workbook. |
| 2 | License required or Trace free run exhausted. |
| 3 | License expired. |
| 4 | Invalid, tampered, or wrong-product license. |
| 5 | Output error. Trace could not write or render the requested report file. |
| N | In --strict mode, the hard-gap count may be returned as the exit code. |
Processing sequence
For a normal generation run the CLI does, in order:
- Initialize licensing
- Parse arguments
- Handle fast-path commands (
license info,license install,license clear,--version,--help) and exit if matched - Load and validate the workbook
- Ingest workbook rows into the traceability graph
- Compute warnings and gaps
- Generate one or more report files
- Optionally write the gaps JSON file
macOS app
The macOS app now exposes the same four profiles as the CLI. The selected profile is explicit in the drop-zone UI and changing it reloads the workbook under the new profile before generation.
Loading a workbook
The macOS app accepts .xlsx files by drag-and-drop onto the drop zone, or via Browse… (NSOpenPanel). Other file types are rejected with an explanatory message:
| File type | Message shown |
|---|---|
| .xls | Old Excel format not supported — save as .xlsx first |
| .csv | CSV files are not supported |
| .ods | ODS files are not supported |
| Other | Only .xlsx files are accepted |
App state flow
- licenseGateLaunch checks for an installed signed license or the one-free-run state. If neither permits use, the app shows the license import gate.
- dropZoneLicensed users land here. Choose a profile, then drag a workbook or click Browse.
- fileLoadedValid file loaded. Shows filename, selected profile, standards, warning count, total gaps, and the generic/profile-specific breakdown when applicable.
- generatingReport is being written. Progress indicator shown.
- doneOutput complete. Options to open the generated file, reveal it in Finder, or generate another.
Output naming
Output filenames are derived from the input stem with an -rtm suffix. If a collision exists, a numeric suffix is added. The files appear in the same directory as the input workbook.
Windows app
The Windows app now runs the same profile-aware Trace path as the CLI. Profile selection is explicit in the UI, and changing the profile reloads the current workbook under the new analysis context.
Loading a workbook
The Windows app accepts .xlsx files by drag-and-drop (WM_DROPFILES) or via a browse dialog. Rejection messages mirror the macOS app, adapted for Windows context (e.g. "open in Excel and re-save as .xlsx" for .xls files).
App state flow
The Windows app follows the same five-state model as macOS — license_gate → drop_zone → file_loaded → generating → done — with explicit profile selection in the drop zone and the done state offering open, show in Explorer, and reset actions.
Async execution
Load, generate, and license-import operations run on background worker threads. Completion is signaled back to the UI thread via Windows messages (WM_LOAD_COMPLETE, WM_GENERATE_COMPLETE, WM_LICENSE_COMPLETE), keeping the UI responsive during library work.
Output naming
Names are derived from the input stem (e.g. requirements-rtm.pdf). Collisions are resolved first with a numbered suffix (-2 through -99), then with a timestamp suffix as a last resort.