Skip to content

Exit codes

TL;DR

Every command exits with one of four codes: 0 completed successfully, 1 the check failed, 2 it could not judge, 3 a fault in qmstrace itself. A pipeline branches on them, and qmstrace --help prints them at its foot.

As --help prints them

Usage: qmstrace [OPTIONS] COMMAND [ARGS]...

  The trace layer under a quality-management system.

Options:
  -C PATH    Run as if qmstrace had been started in PATH, as with git -C. Before
             or after the command.
  --version  Print the version and exit.
  --help     Show this message and exit.

Commands:
  status   Where am I: what was read, and one line per requirement.
  thread   Trace one item: what it derives from, and what hangs off it.
  impact   What changing several items affects, with a candidate Impacts line.
  results  Test verdicts per requirement, from a JUnit or TRX report.
  check    What is wrong, and what is not done yet — the gate with --strict.
  rules    What check holds this repo to, and whose each rule is.
  init     Set up trace configuration, agent guidance and pytest markers.
  graph    Write an offline, interactive view of the local trace graph.
  ledger   The project side's verbs — run them in the ledger repo.

  Exit codes:
    0  completed — informational views may include failures
    1  the check failed — violations, or gaps under the gate; the result line says which
    2  could not judge — usage, configuration, the wrong kind of repo, an unknown ID,
       an unreadable report, a shallow clone where baselines are configured, a repo of
       the project that cannot be read or holds other rules
    3  internal error — a fault in qmstrace, not in the repo

Reading them in a pipeline

  • 0 means the command completed; 1 means a check failed. For a check, 1 means violations — or, under the gate, gaps too. The command's last line says which.
  • 2 is no verdict at all. The run could not judge: no qmstrace.toml above the folder, a trace schema it cannot read, a ledger repo where a product repo was expected, or a product repo where the ledger was; for ledger check, a repo of the project that cannot be read or holds other rules than the ledger's. Fix what it names; do not read it as a pass or as a failure. A mistyped command or option exits 2 as well, as with most command-line tools.
  • 3 is a fault in qmstrace, not in the repo. It prints one line, never a traceback.

qmstrace status, thread, impact and results are informational. In particular, results exits 0 even when matched tests failed or some report entries did not match; a report with no matching tests exits 2. Use pytest's exit code to gate test success.