kapi check
kapi check [files...]Run content checks over one or more files and return structured findings plus a verdict (passed, failed, or did not run), gating on severity: the content-first counterpart to a test runner.
The default checkset is source-side and needs no translation: text hygiene (empty, doubled spaces/words, stray whitespace), length limits (--max-chars/ --max-words), forbidden/required patterns (--forbid/--require), and brand vocabulary when a profile is bound (--profile/--pack/--profile-file).
Bilingual checks (do-not-translate, placeholder integrity) are an opt-in: pass --target <file> --target-lang <lang> to check a translated target against its source.
Each finding carries a stable rule id (<check>.<category>) and a block location, so an assistant can fix the exact block and track rules across iterations. Output is a human table by default; --output-format json|yaml emits the kapi.check/v1 Report. Configuration warnings, such as an unknown key in a voice profile, follow the verdict and fill the report's warnings array. They name configuration to fix and never change the score, the gate or the exit code.
Positional paths accept glob patterns and directories, expanded by kapi itself.
Quote the pattern and ** recurses identically in every shell. Inside a .kapi
project, check with no file arguments checks the project's declared content;
naming files narrows it to those.
Project gate mode (--ship): it runs the project's bound quality gates (voice, terminology, rule-based checks) plus its ship/source coverage gates over the project's content, and exits non-zero when any gate is unmet: the pre-release bar. Target drift never blocks an ordinary build (see 'kapi status'); --ship is the explicit, opt-in enforcement point. With no file arguments it checks the project's source-only content and declared source/target pairs. Named source files receive content checks; named targets retain their source pairing.
Diff scope (--diff-file, --diff-against, --staged, --diff-range): check only the content blocks a unified diff touches, each block whole, and report the lines each spans. Every file the diff names is listed with what became of it: checked, untouched, out of scope (inside a project, content the recipe does not declare), deleted, or did not run (a changed file whose blocks cannot be located). --diff-file reads a diff from a file, or from standard input with -. --diff-against runs git diff against a revision, read-only, and treats untracked files as added. --staged checks what a commit made now would record: the staged changes, each file read from the index, leaving out unstaged edits and untracked files. --diff-range A..B checks the change between two commits, and A...B the change B made since it left A, each file read from B, so it reads nothing from the working tree and runs the same from any checkout. The recipe, voice profiles and terms on disk govern every one of these checks. Named files narrow the scope. The loop for an agent: edit, run 'kapi check --diff-against HEAD', repair, run it again. A pre-commit hook runs 'kapi check --staged', and a pull request check runs 'kapi check --diff-range origin/main...HEAD'.
Exit codes: 0 pass, 3 when the gate fails, 4 when the check did not run, 1 operational. A check did not run when it examined no content, or when one of its checks reported nothing on the known-bad sample it is given beside the content. --no-fail exits 0 when the gate fails (report mode for a fix loop); neither it nor --lenient turns a check that did not run into a pass.
Runs in your browser against a small sample file. Edit the command before running, or press Run to execute it as shown.
kapi check| Flag | Type | Default | Description |
|---|---|---|---|
| --diff-against | string | check only the content blocks changed since this git revision, including untracked files (runs git diff read-only) | |
| --diff-file | string | check only the content blocks this unified diff touches (a file, or - for standard input) | |
| --diff-range | string | check only the content blocks changed between two commits, A..B or A...B (since their merge base), each file read from B and nothing from the working tree | |
| --dnt | stringSlice | do-not-translate terms that must survive verbatim into the target (with --target) | |
| --forbid | stringSlice | regex that must NOT appear in the content (repeatable) | |
| --gate | stringSlice | with --ship: run only the named project gates (voice, terminology, qa); repeatable | |
| --lenient | bool | false | report only: never fail the gate (still prints findings) |
| --locale | string | with --ship: scope the target-side gates to a single target locale (e.g. fr) | |
| --max-chars | int | 0 | flag content longer than this many characters (0 = off) |
| --max-critical | int | 0 | fail if critical findings exceed this count |
| --max-major | int | -1 | fail if major findings exceed this count (-1 = no limit) |
| --max-minor | int | -1 | fail if minor findings exceed this count (-1 = no limit) |
| --max-words | int | 0 | flag content with more than this many words (0 = off) |
| --min-score | int | 0 | fail if the roll-up score is below this (0 = no score gate); with --ship: the brand-gate compliance threshold (default 80) |
| --no-fail | bool | false | exit 0 even when the gate fails (fix-loop mode) |
| --pack | string | built-in brand starter pack | |
| --profile | string | voice profile name from the local store | |
| --profile-file | string | path to a voice profile YAML | |
| --project, -p | string | path to a kapi.yaml project recipe or its directory (auto-discovered from cwd if omitted) | |
| --require | stringSlice | regex that MUST appear in the content (repeatable) | |
| --ship | bool | false | project gate mode: run the project's bound gates (voice, terminology, rule-based checks) plus its ship/source coverage gates; exit non-zero when unmet: the pre-release bar |
| --source-lang | string | source language (e.g. en, en-US; defaults to the project's source_language, else en) | |
| --staged | bool | false | check only the content blocks the staged changes touch, each file read from the index (leaves out unstaged edits and untracked files) |
| --strict | bool | false | strict gate: fail on any critical or major finding |
| --target | string | translated target file to check against the (single) source, enabling bilingual checks | |
| --target-lang | string | locale of the --target file (e.g. de) | |
| --termstore | string | with --ship: named terms or terms-store path for the terminology gate (defaults to the project terms store) | |
| --validate | string | off | reader structure/encoding validation: off|report|strict (report folds structure.*/encoding.* findings into the Report; strict also fails the gate on a Major+ structure/encoding problem) |
| --voice | bool | false | also run the voice/style-similarity check (needs the kapi-check plugin and a profile with examples) |
| --voice-min | float64 | 0.8 | voice-similarity cutoff (cosine, 0-1) below which a block is flagged off-voice |
← Back to the Command Reference