Usage

reqstool [-h] {command: report,export,status} {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, branch, 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 -b BRANCH_NAME

Command: status

Shows the status of all requirements — whether they are implemented, have passing tests, and have manual verification results.

Usage:

reqstool status local -p path_to_dir

Example output:

╒═══════════════════════════════════════════════════════════════════════════╕
│                              REQUIREMENTS: 6                             │
╘═══════════════════════════════════════════════════════════════════════════╛
╒═════════╤════════════════╤══════════════════╤═══════════════════╤════════════════╕
│   URN   │       ID       │  Implementation  │  Automated Tests  │  Manual Tests  │
╞═════════╪════════════════╪══════════════════╪═══════════════════╪════════════════╡
│ ms-001  │    REQ_010     │   Implemented    │    T3 P2 F1 M1    │     T1 P1      │
├─────────┼────────────────┼──────────────────┼───────────────────┼────────────────┤
│ ms-001  │    REQ_020     │   Implemented    │     T1 P1 M1      │     T1 F1      │
├─────────┼────────────────┼──────────────────┼───────────────────┼────────────────┤
│ sys-001 │ REQ_sys001_505 │     Missing      │     T1 P1 M2      │     T0 M1      │
├─────────┼────────────────┼──────────────────┼───────────────────┼────────────────┤
│ ext-001 │ REQ_ext001_100 │   Implemented    │        N/A        │     T1 P1      │
├─────────┼────────────────┼──────────────────┼───────────────────┼────────────────┤
│ ext-002 │ REQ_ext002_300 │   Implemented    │       T0 M1       │      N/A       │
├─────────┼────────────────┼──────────────────┼───────────────────┼────────────────┤
│ ext-002 │ REQ_ext002_400 │   Implemented    │     T1 P1 M1      │     T0 M1      │
╘═════════╧════════════════╧══════════════════╧═══════════════════╧════════════════╛
╒═══════════╤════════════╤════════════╤═════════════╤═════════════╕
│ T = Total │ P = Passed │ F = Failed │ S = Skipped │ M = Missing │
╘═══════════╧════════════╧════════════╧═════════════╧═════════════╛

The requirements table shows for each requirement:

URN — the source system or microservice
ID — the requirement identifier
Implementation — whether the requirement has a matching @Requirements annotation in code (Implemented or Missing)
Automated Tests — test results from JUnit XML: T=total SVCs, P=passed, F=failed, S=skipped, M=missing (no test found for SVC)
Manual Tests — manual verification results: T=total, P=passed, F=failed, M=missing

The exit code equals the number of unmet requirements, making it suitable for CI/CD gates (exit 0 = all requirements met).

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

Exports requirement data in the specified format, with optional filters for specific requirements or SVCs.

Usage:

reqstool export local -p path_to_requirements_dir -o path_to_output_file.json
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 — output format (default: json)
--req-ids — filter by specific requirement IDs
--svc-ids — filter by specific SVC IDs
--no-filters — disable requirement/SVC filters defined in YAML

Command: generate-json (deprecated)

generate-json is deprecated. Use export --format json instead.

Exports all requirement data as JSON.

Usage:

reqstool generate-json local -p path_to_requirements_dir -o path_to_output_file.json

There is currently no JSON Schema for this file and it is a raw dump of the data structures using jsonpickle. The format might change at any time.

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"