Usage

reqstool [-h] {command: report,export,status,validate} {location: local,git,maven,pypi} ...

Use -h/--help for more information about each command and location.

Location types

Each command accepts a location argument that specifies where the reqstool data resides:

  • local — path on the local file system

  • git — Git repository (URL, ref (branch, tag, or commit SHA), optional token)

  • maven — Maven artifact (ZIP)

  • pypi — PyPI package (tar.gz)

Example with git location:

reqstool report git -u URL_TO_REPOSITORY.git -t ACCESS_TOKEN -p PATH_TO_DIR -r REF

Environment variable interpolation

Reqstool expands environment variables in YAML input (requirements.yml, svcs.yml, mvrs.yml, annotations.yml, reqstool_config.yml) before parsing, using POSIX shell parameter expansion (the envsubst standard). Only the braced form is interpolated:

Syntax Behaviour

${VAR}

Substitute the value of VAR.

${VAR:-default}

Use default when VAR is unset or empty.

${VAR:?message}

Fail with message when VAR is unset or empty.

${VAR:+alt}

Use alt when VAR is set.

A bare ${VAR} whose variable is unset and has no inline default is a hard error — this keeps ingestion deterministic and surfaces misconfiguration in CI rather than silently producing empty values.

The bare $VAR form (without braces) is intentionally not expanded, so the # yaml-language-server: $schema=…​ directive, regular expressions and other literal $ characters are left untouched.

This is the recommended way to keep imported artifact versions current — pin the version to an environment variable and let a tool such as Renovate update it:

imports:
  maven:
    - url: https://repo.maven.org
      group_id: com.example
      artifact_id: my-lib
      version: ${MY_LIB_VERSION}

Command: status

Verdict surface for developers and CI/CD: shows which requirements are met, why the unmet ones are failing, and exits with the number of unmet requirements (exit 0 = all met).

Usage:

reqstool status [--verbosity compact|normal|verbose|extra-verbose] [--incomplete] [--format console|json] \
    local -p path_to_dir [--req-ids ID...] [--svc-ids ID...]

Options:

  • --verbosity — console detail level (default: normal); ignored for --format json

  • --incomplete — show only incomplete requirements (console only)

  • --format — console (default) or json

  • --req-ids / --svc-ids — scope JSON output to specific IDs (must follow the location subcommand)

  • --check-all-reqs-met — exit 1 unless every requirement is met

Verbosity levels

Level Output

compact

Single line — ideal for CI logs. ms-001: 6 requirements · 1 complete · 5 incomplete · FAIL

normal (default)

Verdict list grouped COMPLETE first, then INCOMPLETE with one reason per line. Actionable failures appear nearest the prompt.

verbose

Per-requirement table (URN / ID / Implementation / Automated Tests / Manual Tests).

extra-verbose

Verdict list with full drill-down per incomplete requirement: SVCs, individual test results (✓/✗), MVR pass/fail, and implementation annotations.

Example — normal output:

Requirements status · ms-001

COMPLETE (1)
  REQ_ext001_100      ext-001

INCOMPLETE (5)
  REQ_010             ms-001      automated test failed (2/3 passed)
  REQ_020             ms-001      manual verification failed
  REQ_sys001_505      sys-001     not implemented · automated test missing · manual result missing
  REQ_ext002_300      ext-002     automated test missing
  REQ_ext002_400      ext-002     manual result missing

1/6 complete · 5 incomplete · FAIL

Example — show only what’s still missing:

reqstool status --incomplete --verbosity extra-verbose local -p path_to_dir

Command: validate

Checks spec completeness using only authored data (requirements.yml, svcs.yml, mvrs.yml) — no code or test results required. Useful while authoring requirements, before any implementation exists.

Checks performed:

  • Every requirement has at least one SVC defined.

  • Every manual SVC has at least one MVR defined.

  • All SVC/MVR/annotation cross-references point to existing IDs (referential integrity via SemanticValidator).

Referential errors are always fatal (exit 1). Coverage gaps are warnings by default; use --strict to promote them to errors (CI gate for spec completeness).

Usage:

reqstool validate [--strict] local -p path_to_dir

Example output:

Validating reqstool setup · ms-001

⚠ ms-001:SVC_026    manual-test — no MVR defined
⚠ sys-001:SVC_sys001_600    manual-test — no MVR defined

2 warnings
  (use --strict to treat warnings as errors)

MVR supersession

When a manual verification is repeated (for example, a first attempt fails and a corrected one passes), add both results as separate MVR entries and set a date on each. Reqstool selects the entry with the latest date as the effective verdict for that SVC. Older entries are retained as audit history and shown with a (superseded) marker in the report, but are excluded from the pass/fail computation.

results:
  - id: MVR_001
    svc_ids: ["SVC_021"]
    date: "2026-01-10T09:00:00Z"   (1)
    pass: false
    comment: "XSD validation failed."

  - id: MVR_002
    svc_ids: ["SVC_021"]
    date: "2026-01-15T14:30:00Z"   (2)
    pass: true
    comment: "All fields present."
1 Older entry — superseded, shown as history in the report.
2 Latest entry — effective verdict; this determines pass/fail.

date field rules:

  • The date value must be an RFC 3339 date-time, for example "2026-01-15T14:30:00Z" or "2026-01-15T14:30:00+01:00". A timezone offset is mandatory — bare local datetimes without a timezone are rejected. Note the required quotes — unquoted values are parsed by YAML as date objects, not strings.

  • date is optional when only one MVR references a given SVC; the single entry is always the verdict regardless.

  • date is required on every MVR that references a given SVC as soon as more than one MVR does. A missing date in that situation is a semantic validation error.

  • Two MVRs for the same SVC with the exact same UTC moment are a validation error — add a time component to disambiguate (e.g. T09:00:00Z vs T14:30:00Z).

Command: report

Generates a detailed report suitable for auditors and stakeholders. Supports AsciiDoc and Markdown output formats.

Usage:

reqstool report local -p path_to_requirements_dir -o path_to_output_file.adoc
reqstool report --format markdown local -p path_to_requirements_dir -o path_to_output_file.md

Options:

  • --format — output format: asciidoc (default) or markdown

  • --group-by — grouping option (default: initial_imports)

  • --sort-by — sorting options (default: id)

The report command relies on PosixPath which could result in issues when running on Windows machines. If an error occurs, don’t hesitate to file a bug report!

Command: report-asciidoc (deprecated)

report-asciidoc is deprecated. Use report --format asciidoc instead.

This command still works but delegates to the report command with --format asciidoc.

Command: export

Full data dump for interchange, archival, and tooling. Two serialization formats of the same dataset:

  • json (default) — structured JSON conforming to export_output.schema.json

  • sqlite — binary SQLite database written via the SQLite backup API; requires -o <file>

Usage:

reqstool export local -p path_to_requirements_dir -o path_to_output_file.json
reqstool export --format sqlite local -p path_to_requirements_dir -o path_to_output.db
reqstool export local -p path_to_requirements_dir --req-ids REQ_001 REQ_002
reqstool export local -p path_to_requirements_dir --svc-ids SVC_001

Options:

  • --format — json (default) or sqlite

  • --req-ids / --svc-ids — filter JSON output to specific IDs (must follow the location subcommand)

  • --no-filters — disable requirement/SVC filters defined in YAML

Using the Docker image

You can also run reqstool from a container, using the same commands as above. Mount the paths to the input data and output directory:

docker run --rm \
  -v path_to_requirements_files_folder:/input \
  -v path_to_output_folder:/output \
  <containerId/tag> sh -c "reqstool report --format asciidoc local -p ./input -o ./output/report.adoc"