Commands
Every command accepts --json (one JSON document on stdout) and --repo-root <DIR>. The same text is available from rqtk <command> --help.
Requirements Toolkit
Usage: rqtk [OPTIONS] <COMMAND>
Commands:
init Scaffold a new requirement set in the current repo
add Add a new requirement with the next free ID in its category
add-activity Add a verification activity to an existing requirement
add-stakeholder Add a new stakeholder definition
add-need Add a new stakeholder need
lint Check every file against the schema, the config and the `verifies` links in source
context Everything relevant to one requirement, need or stakeholder: links, tests, status, evidence and lint findings. Designed as the briefing for working on an item
impact What changed since a git revision, and which requirements and activities it affects
trace Show the parent/child traceability chain of a requirement
coverage Report need satisfaction and verification status (verified / suspect / failed / …)
graph Print the traceability graph of stakeholders, needs and requirements
baseline Stamp all requirements and create a git tag baseline for HEAD
export Export requirements to a file in the given format
diff Show requirements that changed between two git revisions or baselines
scan List `verifies` links between source code and verification activities
verify Record test results as verification evidence in `.rqtk/evidence.toml`
review Confirm a requirement still holds after something it depends on changed
search Search requirements, needs and stakeholders by substring
open Open a requirement file in $EDITOR
log Show the git commit history for a single requirement
install-hook Install a git pre-commit hook that runs `rqtk rehash` and `rqtk lint`
rehash Refresh stored content hashes that no longer match their requirement or need
report Generate a Markdown requirements report
schema Print the JSON Schema of a file kind, or list the kinds
explain Explain a lint rule and how to fix it, or list all rules
skills Agent skills for working with rqtk in coding agents (Claude Code, Codex, …)
help Print this message or the help of the given subcommand(s)
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
-V, --version Print version
Exit codes:
0 success, nothing to report
1 findings: lint errors, failed or suspect verification, stale evidence
2 usage error: bad arguments or unsupported option
3 error: configuration, I/O or git failure
rqtk init
Scaffold a new requirement set in the current repo
Usage: rqtk init [OPTIONS]
Options:
--repo-root <REPO_ROOT>
Repository root (the directory containing `.rqtk/`) [default: .]
--requirements-dir <REQUIREMENTS_DIR>
--force
Overwrite an existing `.rqtk/config.toml`
--json
Print one JSON document to stdout instead of text. Errors go to stderr as JSON
--agents
Also install the agent skills (see `rqtk skills install`)
--example
Also create an example stakeholder and need
--hook
Also install the git pre-commit hook (see `rqtk install-hook`)
--dry-run
Report the files that would be created without writing them
-h, --help
Print help
rqtk add
Add a new requirement with the next free ID in its category
Usage: rqtk add [OPTIONS] --category <CATEGORY> --type <REQ_TYPE> --title <TITLE> --statement <STATEMENT>
Options:
--category <CATEGORY> Category key from `.rqtk/config.toml`, e.g. SYS
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
--type <REQ_TYPE> Requirement type from `types.allowed`
--title <TITLE>
--statement <STATEMENT> A single normative sentence, e.g. "The system shall …"
--rationale <RATIONALE>
--parent <PARENTS> Parent requirement ID (repeatable, or comma-separated)
--satisfies <SATISFIES> ID of a need this requirement satisfies (repeatable, or comma-separated)
--priority <PRIORITY> Priority from `priority.levels` [default: Medium, or the middle level]
--method <METHOD> Verification method from `verification.methods` [default: the first]
--level <LEVEL> Verification level from `verification.levels` [default: the first]
--phase <PHASE> Verification phase from `verification.phases` [default: the first]
--criteria <CRITERIA> Success criteria: what a passing verification shows
--activity <ACTIVITIES> Add a verification activity with this name (repeatable). IDs are generated as VA-<CATEGORY>-<NUMBER>-<NN>
--dry-run Print the file that would be created without writing it
-h, --help Print help
rqtk add-activity
Add a verification activity to an existing requirement
Usage: rqtk add-activity [OPTIONS] --name <NAME> <REQUIREMENT>
Arguments:
<REQUIREMENT> Requirement ID
Options:
--name <NAME> What the activity checks
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--id <ID> Defaults to the next free VA-<CATEGORY>-<NUMBER>-<NN>
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
--dry-run Print the activity that would be added without writing it
-h, --help Print help
rqtk add-stakeholder
Add a new stakeholder definition
Usage: rqtk add-stakeholder [OPTIONS] --name <NAME>
Options:
--id <ID> Defaults to the next free STK-NNN
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
--name <NAME>
--role <ROLE>
--organization <ORGANIZATION>
--dry-run Print the file that would be created without writing it
-h, --help Print help
rqtk add-need
Add a new stakeholder need
Usage: rqtk add-need [OPTIONS] --title <TITLE> --statement <STATEMENT>
Options:
--id <ID> Defaults to the next free NEED-NNNN
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
--title <TITLE>
--statement <STATEMENT>
--stakeholders <STAKEHOLDERS> Stakeholder IDs associated with this need (comma-separated)
--rationale <RATIONALE> Why the stakeholders need it
--dry-run Print the file that would be created without writing it
-h, --help Print help
rqtk lint
Check every file against the schema, the config and the `verifies` links in source
Usage: rqtk lint [OPTIONS]
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk context
Everything relevant to one requirement, need or stakeholder: links, tests, status, evidence and lint findings. Designed as the briefing for working on an item
Usage: rqtk context [OPTIONS] <ID>
Arguments:
<ID>
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk impact
What changed since a git revision, and which requirements and activities it affects
Usage: rqtk impact [OPTIONS] <BASE>
Arguments:
<BASE> Branch, tag, SHA, `HEAD~N` or baseline name to compare the working tree against
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk trace
Show the parent/child traceability chain of a requirement
Usage: rqtk trace [OPTIONS] <ID>
Arguments:
<ID>
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk coverage
Report need satisfaction and verification status (verified / suspect / failed / …)
Usage: rqtk coverage [OPTIONS]
Options:
--repo-root <REPO_ROOT>
Repository root (the directory containing `.rqtk/`)
[default: .]
--strict
Exit 1 unless every requirement is Verified and every need is satisfied
--allow <ALLOW>
With --strict, also accept requirements in this state (repeatable), e.g. for requirements written ahead of their implementation
Possible values:
- planned: Activities defined, nothing run yet
- in-progress: Some activities done, not all
--json
Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-s, --short
Print only the one-line summary
-h, --help
Print help (see a summary with '-h')
rqtk graph
Print the traceability graph of stakeholders, needs and requirements
Usage: rqtk graph [OPTIONS]
Options:
--format <FORMAT>
Possible values:
- dot: Graphviz DOT
[default: dot]
--repo-root <REPO_ROOT>
Repository root (the directory containing `.rqtk/`)
[default: .]
--json
Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help
Print help (see a summary with '-h')
rqtk baseline
Stamp all requirements and create a git tag baseline for HEAD
Usage: rqtk baseline [OPTIONS] <VERSION>
Arguments:
<VERSION>
Options:
--dry-run Report what would be stamped and tagged without changing anything
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk export
Export requirements to a file in the given format
Usage: rqtk export [OPTIONS] --format <FORMAT>
Options:
--format <FORMAT> [possible values: csv, json, markdown]
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
--output <OUTPUT>
-h, --help Print help
rqtk diff
Show requirements that changed between two git revisions or baselines
Usage: rqtk diff [OPTIONS] <FROM> <TO>
Arguments:
<FROM>
<TO>
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk scan
List `verifies` links between source code and verification activities
Usage: rqtk scan [OPTIONS]
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk verify
Record test results as verification evidence in `.rqtk/evidence.toml`.
Reads JUnit XML (cargo-nextest, pytest --junitxml, go-junit-report, jest-junit, …), matches test cases to `verifies` links and records each activity's outcome against the requirement's current content hash.
Usage: rqtk verify [OPTIONS] --results <RESULTS>...
Options:
--repo-root <REPO_ROOT>
Repository root (the directory containing `.rqtk/`)
[default: .]
--results <RESULTS>...
JUnit XML result files
--check
Do not write; exit 1 if the evidence file is out of date
--json
Print one JSON document to stdout instead of text. Errors go to stderr as JSON
--dry-run
Report what would be recorded without writing
-h, --help
Print help (see a summary with '-h')
rqtk review
Confirm a requirement still holds after something it depends on changed.
Settles a Suspect requirement whose tests passed again unchanged after it was reworded, or whose ancestor or need changed. Recorded in `.rqtk/evidence.toml`.
Usage: rqtk review [OPTIONS] <ID>
Arguments:
<ID>
Requirement ID
Options:
--note <NOTE>
Why the requirement still holds, kept with the review
--repo-root <REPO_ROOT>
Repository root (the directory containing `.rqtk/`)
[default: .]
--dry-run
Report what would be recorded without writing
--json
Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help
Print help (see a summary with '-h')
rqtk search
Search requirements, needs and stakeholders by substring
Usage: rqtk search [OPTIONS] <PATTERN>
Arguments:
<PATTERN> Pattern to search for
Options:
-i, --ignore-case Case-insensitive matching
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
-f, --field <FIELD> Restrict search to specific fields: id, title, statement, rationale, notes, keywords
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk open
Open a requirement file in $EDITOR
Usage: rqtk open [OPTIONS] <ID>
Arguments:
<ID>
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk log
Show the git commit history for a single requirement
Usage: rqtk log [OPTIONS] <ID>
Arguments:
<ID>
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk install-hook
Install a git pre-commit hook that runs `rqtk rehash` and `rqtk lint`
Usage: rqtk install-hook [OPTIONS]
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk rehash
Refresh stored content hashes that no longer match their requirement or need.
Only files that carry a `content_hash` are touched; `--all` also stamps the rest.
Usage: rqtk rehash [OPTIONS]
Options:
--all
Also write a hash into files that have none
--repo-root <REPO_ROOT>
Repository root (the directory containing `.rqtk/`)
[default: .]
--dry-run
Report stale hashes without writing
--json
Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help
Print help (see a summary with '-h')
rqtk report
Generate a Markdown requirements report
Usage: rqtk report [OPTIONS]
Options:
-o, --output <OUTPUT> Write to this file instead of stdout
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk schema
Print the JSON Schema of a file kind, or list the kinds
Usage: rqtk schema [OPTIONS] [KIND]
Arguments:
[KIND] config, requirement, need, stakeholder or evidence
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk explain
Explain a lint rule and how to fix it, or list all rules
Usage: rqtk explain [OPTIONS] [CODE]
Arguments:
[CODE]
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk skills
Agent skills for working with rqtk in coding agents (Claude Code, Codex, …)
Usage: rqtk skills [OPTIONS] <COMMAND>
Commands:
list List the bundled skills and who can invoke them
install Write the skills into the repo and point AGENTS.md / CLAUDE.md at them
help Print this message or the help of the given subcommand(s)
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk skills list
List the bundled skills and who can invoke them
Usage: rqtk skills list [OPTIONS]
Options:
--repo-root <REPO_ROOT> Repository root (the directory containing `.rqtk/`) [default: .]
--json Print one JSON document to stdout instead of text. Errors go to stderr as JSON
-h, --help Print help
rqtk skills install
Write the skills into the repo and point AGENTS.md / CLAUDE.md at them.
By default the skills go into `.agents/skills` (read by Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Amp and most other agents), and `.claude/skills` links to them for Claude Code. Skills you have edited are kept unless --force is given. The rqtk block goes into AGENTS.md and/or CLAUDE.md where they exist; no file is created unless named with --instructions.
Usage: rqtk skills install [OPTIONS]
Options:
--for <TARGETS>
Agents to install for
Possible values:
- universal: `.agents/skills`: the shared location read by Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Amp, Cline, Zed, Warp and others
- claude: `.claude/skills`: Claude Code
[default: universal claude]
--repo-root <REPO_ROOT>
Repository root (the directory containing `.rqtk/`)
[default: .]
--dir <DIR>
Install a single copy into this directory instead (overrides --for)
--json
Print one JSON document to stdout instead of text. Errors go to stderr as JSON
--copy
Copy the skills into .claude/skills instead of linking to .agents/skills
--instructions <INSTRUCTIONS>
Instructions file (AGENTS.md or CLAUDE.md) to add the rqtk block to; created if missing. Repeat for several
--force
Replace skills that were edited locally
--dry-run
Report what would be written without writing
-h, --help
Print help (see a summary with '-h')