CLI

Commands

reqfile check [--fast] [--changed [BASE]] [--only ID,...] [--use LOCATION]... [-v|-q]
              [--command-override 'FROM=>TO']... [--format auto|pretty|plain|json]
              [--log FILE [--log-tag KEY=VALUE]...]
reqfile eval [--only ID,...] [--use LOCATION]... [--command-override 'FROM=>TO']...
             [--repeat N] [-v] [--format auto|pretty|plain|json]
reqfile example add <ID> <NAME> --expected violation|ok [--finding FILE]... [--rationale TEXT] [--holdout] <FILE>...
reqfile explain <PATH>
reqfile list [--kind product|code|process] [--format summary|json]
reqfile add <LOCATION> [ID]... [--dry-run]
reqfile update [--dry-run]

reqfile check

• --changed [BASE] checks everything a change since the merge-base of BASE and HEAD can affect: the changed files (committed, uncommitted, untracked and deleted), and every file whose applicable block is not the same as at the merge-base, because another block now applies to it or because its requirement, its $REQFILE_ASSETS files, its settings or the commit of its source changed. Commands without files still run. BASE defaults to the nearest base in .reqfile/config.yaml, else origin/HEAD; without it, origin/main or origin/master. In a repository without a remote, it is the local main or master, else the last commit, and before the first commit everything is checked. A base other than origin/HEAD is named in a note line.
• --fast runs only decision checks and the commands declared fast: true, for edit hooks; the summary counts the checks left for a full run. Without it, every check runs, so a CI running reqfile check never skips checks.
• --only runs only the listed requirements.
• --use LOCATION adds the requirements of a location for this run (see packages).
• --command-override 'FROM=>TO' replaces FROM by TO in the run of every command check, for this run only, never in a Reqfile; repeatable. A FROM no command contains is an error.
• --log FILE appends one JSON line per judged code unit (clean ones included), command check and command finding: run id, git HEAD, requirement, location, the unit's source and fingerprint, the question's fingerprint, probability, verdict, exact model and whether the answer was cached, plus any --log-tag KEY=VALUE. It feeds evaluation and replay without changing results.

Output

• In a terminal, auto (the default) draws a table of requirements, then the details of what does not pass, grouped by requirement with each fix hint once, and a summary line, in color unless NO_COLOR is set. -v shows every finding and what each check ran, -q only what fails the run.
• Anywhere else, such as in a hook, a pipe or CI, it is plain: one finding per line, stable for agents and scripts (summary is still accepted).
• json is the same content as data, including each finding's conflicts.
• Before anything runs, a missing Jev key is said once, first (setup in the plain output, a banner in the pretty one, setup in JSON), naming the variable and the requirements whose decision checks will not judge code.

The summary counts checks run, checks with nothing to check, and code units judged, so a run that looked at nothing shows.

Other commands

• list lists every requirement of the repository with its type, the types of its checks and, for a use block, its source; --format json gives the same as data.
• explain <path> lists the requirements that apply to a path: for each, the block that applies, and for a use block its resolved definition and whether its checks are inherited or set in the block.
• eval measures each requirement's checks on its labeled examples, each case --repeat N times; --format json gives the counts per split and every case as data (see evals).
• example add turns files of the repository into a labeled example.
• add writes use blocks pinned to a commit, update moves the pins (see packages).

Exit codes

3 takes precedence over 1. An advisory check that cannot run, such as a decision check without an API key in a pull request from a fork, is reported as an advisory error without changing the exit code: it could never have blocked. Exit 0 means the checks passed, not that the requirements hold: checks approximate requirements.