The command line
The command line
rqm has one program and a handful of commands. This page is about what they have in common. The pages after it describe each command.
rqm [--format human|json] [--strict] <command> [options]
Where a command runs
A command works on a project, and a project is a directory that holds an rqm.yaml. rqm looks for that file in the directory you run it in, and then in each parent directory, one after the other. The search stops at the first directory that has a .git entry, so rqm never reads a configuration that belongs to another repository, and it does not matter in which subdirectory of your repository you stand.
When it finds nothing, the command fails and says so:
$ rqm check
error[E-CONFIG-NOT-FOUND]: rqm.yaml was not found in the working directory or in any directory above it, up to the .git boundary
[exit 2]
The line [exit 2] is not printed by rqm. This book adds it to every example whose command fails, to show the exit code.
Two commands do not need a project to exist: init creates it, and --help and --version need nothing.
If you want to point rqm at a configuration file somewhere else, set the environment variable RQM_CONFIG to its path. A relative path is relative to the directory you run in, there is no search, and the project root is the directory that holds the file. It is the only environment variable rqm reads, and nothing else in the environment changes what it does.
All paths that rqm prints are relative to the project root and use /, on every platform.
Two options for every command
--format human|json chooses how the result is printed. The default, human, is for people and may change from one release to the next. json is a contract: one JSON object, followed by a newline, on standard output, and nothing on standard error. Scripts should use --format json. Its layout is described in The JSON output.
--strict makes a warning count as a failure for the exit code. It does not change the output.
Both options can be given before or after the command name.
What you see when something is wrong
Problems are reported as diagnostics. A diagnostic has a severity, a code, a message and, when it concerns a place in a file, the file with the line and the column:
error[E-FIELD-VALUE]: The field 'status' must be one of draft, approved, required, deprecated, rejected, found 'aproved'
--> requirements/RQM-2.yaml:11:9
The code is stable. It never changes meaning, and scripts can rely on it, while the message is for people. Diagnostic codes lists every code, what it means and what to do about it.
An error is a problem that stops something from working. A warning is a problem that does not, such as a requirement directory that does not exist yet:
$ rqm init --default-kind functional
created rqm.yaml (cargo project)
created .gitignore with .rqm/
next:
- cargo add --dev rqm-attr
- add to .config/nextest.toml, so that nextest writes the report rqm reads:
[profile.ci.junit]
path = "junit.xml"
- rqm create --title "..." to write the first requirement
- rqm check
$ rqm check
checked 0 requirements (loaded 0 of 0 discovered requirement files)
warning[W-ROOT-MISSING]: The requirement root 'requirements' does not exist, so it holds no requirements
--> requirements:1:1
$ rqm --strict check
checked 0 requirements (loaded 0 of 0 discovered requirement files)
warning[W-ROOT-MISSING]: The requirement root 'requirements' does not exist, so it holds no requirements
--> requirements:1:1
[exit 2]
(The summary line goes to standard output and the diagnostics go to standard error. The examples in this book show the standard output of a command first and then its standard error.)
Exit codes
The exit code tells a script what kind of outcome it was, and the diagnostic code tells it why.
| Exit code | Meaning |
|---|---|
| 0 | Success. Warnings do not change that, unless you gave --strict. |
| 1 | A gate failed: the command worked, and what it found must stop a build. rqm test, rqm check --baseline, and rqm --strict coverage are the commands that can exit with 1. |
| 2 | The input is invalid: a file or an argument is wrong. Everything a person has to fix gives 2. |
| 3 | An operational error: rqm could not do its work, for example because a file could not be read or written. |
When several things happen in one run, 2 wins over 3, 3 wins over 1, and 1 wins over 0.
The same everywhere
Commands that read a project give the same bytes for the same project, whatever directory you run them from, whatever your locale or time zone, and whether or not you are online. They never print the time, your user name or a path of your machine. The one value that differs from run to run is the uuid that create gives to a new requirement.
list, show, check, trace, affected and coverage are the commands that give the same bytes everywhere.
What is next
rqm initsets a project up.rqm createwrites a new requirement.rqm renamechanges the id of a requirement and every reference to it.rqm editopens a requirement in your editor, checks the result and reports errors.rqm listandrqm showread requirements.rqm affectedlists the requirements that a set of changed paths touches.rqm traceshows the tests bound to one requirement and what the latest run said about them.rqm checkchecks the whole project.rqm coveragereports gated requirements by verification status.