CLI reference
Every command, argument, and option in guardlink 2.2.0, from the
package published to npm.
guardlink [options] [command]Commands
Section titled “Commands”| Command | Summary |
|---|---|
guardlink init |
Initialize GuardLink in a project — creates .guardlink/ and updates agent instruction files |
guardlink parse |
Parse all GuardLink annotations and output the threat model as JSON |
guardlink status |
Show annotation coverage summary |
guardlink validate |
Check annotations for syntax errors and dangling references |
guardlink verify |
Record that the code beneath each claim was checked — writes .guardlink/verified.json and nothing else |
guardlink blame |
Who introduced, declared and fixed each claim, and which AI tool co-authored it — read from git, nothing written |
guardlink ci |
Advisory CI checks — parse diagnostics, unmitigated exposures, confirmed exploits, unqualified acceptances, drifted @source anchors, and stale claims (exit 0 unless –strict) |
guardlink report |
Generate a threat model report with Mermaid diagram |
guardlink migrate |
Move annotations between source comments and .guardlink/annotations/ sidecars |
guardlink reanchor |
Find @source blocks whose file:line no longer holds the symbol they name |
guardlink artifacts |
Emit .guardlink/model.json and .guardlink/graph/ — diagrams and the model as plain files |
guardlink diff |
Compare threat model against a git ref — find what changed |
guardlink paths |
Find source-to-sink flow paths with no control on them (derived from @flows, no LLM) |
guardlink lookup |
Query the threat model with the guardlink_lookup forms, e.g. “unentitled reaches”, “agents”, “effects for #db”, “cwe:CWE-89”. Prints JSON; an unrecognised form lists the supported ones |
guardlink sarif |
Export findings as SARIF 2.1.0 for GitHub Advanced Security, VS Code, etc. |
guardlink threat-report |
Generate an AI threat report using a framework or custom prompt |
guardlink threat-reports |
List saved AI threat reports |
guardlink annotate |
Launch a coding agent to add GuardLink security annotations |
guardlink lint |
Check annotations against the evidence bar: exposures that name code and are paired, severities within band, evidence on @confirmed; –since <ref> checks only what a session added, including that it wrote no @accepts or @entitles |
guardlink hypothesis |
What happened when an exposure was tested: record confirmed or refuted outcomes with evidence, see what is untested, and what to test next. Declared boundaries are claims too: record them supported or contradicted |
guardlink translate |
Translate GuardLink threats into CERT-X-GEN pentest templates (generation only, no execution) |
guardlink ask |
Ask questions about this project, its threat model, and security posture |
guardlink clear |
Remove all GuardLink annotations from source files — start fresh |
guardlink sync |
Sync agent instruction files with current threat model — keeps ALL coding agents up to date |
guardlink unannotated |
List source files with no GuardLink annotations |
guardlink review |
Governance review of unmitigated exposures — accept, remediate, or skip. Interactive at a TTY; scriptable with –accept/–from. Every acceptance records who, why, and until when. |
guardlink entitle |
Review proposed entitlements (@entitles) — accept, reject, or defer. Only acceptance writes to source, under the name of the human who accepted. |
guardlink config |
Manage LLM provider configuration |
guardlink dashboard |
Generate an interactive HTML threat model dashboard with diagrams |
guardlink link-project |
Link repos into a shared workspace for cross-repo threat modeling |
guardlink merge |
Merge multiple repo report JSONs into a unified workspace threat model |
guardlink estate |
Estate-wide open risk, read back from the merged report guardlink merge --json wrote (exit 0 unless –strict) |
guardlink feature |
Manage and inspect feature tags across the threat model |
guardlink mcp |
Start GuardLink MCP server (stdio transport) — for Claude Code, Cursor, etc. |
guardlink tui |
Interactive TUI — slash commands, AI chat, exposure triage |
guardlink gal |
Display GuardLink Annotation Language (GAL) quick reference |
Global options
Section titled “Global options”Accepted by every command.
| Option | Description |
|---|---|
-V, --version |
output the version number |
-h, --help |
display help for command |
guardlink init
Section titled “guardlink init”Initialize GuardLink in a project — creates .guardlink/ and updates agent instruction files
guardlink init [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Override project name |
-a, --agent <agents> |
Agent(s) to create files for: claude,cursor,codex,copilot,windsurf,cline,none (comma-separated) |
--mode <mode> |
Where annotations live: external (default, .gal sidecars under .guardlink/annotations/) or inline (comments in source) (default: “external”) |
--no-root-files |
Write nothing outside .guardlink/ — no root .mcp.json, no agent instruction files, no docs/ |
--skip-agent-files |
Only create .guardlink/, skip agent file updates |
--force |
Re-scaffold config and agent instructions — never overwrites an authored definitions file |
--reset |
DESTRUCTIVE: also overwrite the definitions file and a customised config.json with the empty template |
--dry-run |
Show what would be created without writing files |
-h, --help |
display help for command |
guardlink parse
Section titled “guardlink parse”Parse all GuardLink annotations and output the threat model as JSON
guardlink parse [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory to scan (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <name> |
Project name (default: the name in .guardlink/config.json) |
-o, --output <file> |
Write JSON to file instead of stdout |
--pretty |
Pretty-print JSON output (default: true) |
--no-pretty |
Emit compact JSON on one line |
--blame |
Attach git attribution to each exposure, confirmed and mitigation: who introduced, declared and fixed it, and which AI co-authored those commits |
-h, --help |
display help for command |
guardlink validate
Section titled “guardlink validate”Check annotations for syntax errors and dangling references
guardlink validate [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory to scan (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--strict |
Also fail on unmitigated exposures (for CI gates) |
--artifacts |
Also check .guardlink/graph/ artifacts against the current model; exits non-zero on drift |
--sync |
Also refresh agent instruction files (this used to happen unasked — see D16) |
--code-graph |
Also check declared @boundary claims against a code graph, when one is installed and built: a stated access level a route contradicts, a route handler with no boundary to the outside, a boundary nothing crosses. Warnings only |
-h, --help |
display help for command |
guardlink verify
Section titled “guardlink verify”Record that the code beneath each claim was checked — writes .guardlink/verified.json and nothing else
guardlink verify [options] [dir] [targets...]Arguments
| Argument | Description |
|---|---|
dir |
Project directory (default .). A file or file:line here is taken as a target. (default: “.”) |
targets |
file or file:line — lock unverified and re-lock stale claims there |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
-f, --format <fmt> |
Output format: text (default) or json (default: “text”) |
--stale |
Re-lock every stale claim (asserts each control still holds) |
--all |
Lock unverified and re-lock stale — adoption bootstrap, or a deliberate reset |
--dry-run |
Print what would change; write nothing |
--by <name> |
Verifier name (default: git user.name, then the OS user) |
--force |
Replace a ledger that failed to parse |
-h, --help |
display help for command |
guardlink lint
Section titled “guardlink lint”Check annotations against the evidence bar: exposures that name code and are paired, severities within band, evidence on @confirmed; –since <ref> checks only what a session added, including that it wrote no @accepts or @entitles
guardlink lint [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--since <ref> |
Only claims added since a git ref (what an agent session wrote) |
--json |
Machine-readable output (guardlink.lint/v1) |
-h, --help |
display help for command |
guardlink hypothesis
Section titled “guardlink hypothesis”What happened when an exposure was tested: record confirmed or refuted outcomes with evidence, see what is untested, and what to test next. Declared boundaries are claims too: record them supported or contradicted
guardlink hypothesis [options] [command]Subcommands
| Subcommand | Summary |
|---|---|
list |
Every exposure with its tested state: untested, confirmed, refuted, or retest (confirmed, then the code changed) |
next |
What to test next: retests first, then untested by severity, undefended path, and ownership |
refute |
Record that an exposure was tested and is not exploitable, with the evidence |
confirm |
Record that an exposure was tested and is exploitable, from evidence in hand or a cxg scan report |
boundaries |
Every declared @boundary with its tested state: unverified, supported, contradicted, or retest (contradicted, then the code changed) |
support |
Record that a declared @boundary held when tested: a probe from the outer side was refused where the boundary says it is |
contradict |
Record that a declared @boundary did not hold: a probe from the outer side got through where the boundary says it is refused |
Options
| Option | Description |
|---|---|
-h, --help |
display help for command |
guardlink hypothesis list
Section titled “guardlink hypothesis list”Every exposure with its tested state: untested, confirmed, refuted, or retest (confirmed, then the code changed)
guardlink hypothesis list [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--state <state> |
Only this state: untested, confirmed, refuted, retest |
--json |
Machine-readable output (guardlink.hypotheses-list/v1) |
-h, --help |
display help for command |
guardlink hypothesis next
Section titled “guardlink hypothesis next”What to test next: retests first, then untested by severity, undefended path, and ownership
guardlink hypothesis next [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
-n, --count <n> |
How many to list (default: “10”) |
--intake |
Print the queue as a brief for bugb intake |
--json |
Machine-readable output (guardlink.hypotheses-next/v1) |
-h, --help |
display help for command |
guardlink hypothesis refute
Section titled “guardlink hypothesis refute”Record that an exposure was tested and is not exploitable, with the evidence
guardlink hypothesis refute [options] <target> [dir]Arguments
| Argument | Description |
|---|---|
target |
The exposure as file:line |
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--evidence <text> |
What was tried and what came back (required) |
--by <name> |
Who tested it (default: human:<git user.name>) |
-h, --help |
display help for command |
guardlink hypothesis confirm
Section titled “guardlink hypothesis confirm”Record that an exposure was tested and is exploitable, from evidence in hand or a cxg scan report
guardlink hypothesis confirm [options] [target] [dir]Arguments
| Argument | Description |
|---|---|
target |
The exposure as file:line (omit with –from-scan) |
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--evidence <text> |
The request and response, the reproduction, or the scan proof (required without –from-scan) |
--from-scan <file> |
A cxg scan report (JSON). A finding carrying the claim key (claim_key, claimKey, guardlink/claimKey — at the finding’s top level or in its annotation, spread or as a forwarded partialFingerprints/properties map) resolves to the claim with that key, or is reported stale; only an unstamped finding falls to the weaker joins — location, then asset and threat, then CWE. A key that names a @boundary, or one under boundary_claim_key/boundaryClaimKey beside the exposure’s, records that boundary contradicted (supported when the finding’s boundary_outcome says so), in the ledger only |
--by <name> |
Who tested it (default: human:<git user.name>; cxg for –from-scan) |
--write |
Also insert the @confirmed line into the source. On the manual confirm <file:line> path it goes beneath that @exposes; under –from-scan only uncontested key-verified confirmations are written — the rest stay in the ledger alone and are reported with the command to record them by hand |
-h, --help |
display help for command |
guardlink hypothesis boundaries
Section titled “guardlink hypothesis boundaries”Every declared @boundary with its tested state: unverified, supported, contradicted, or retest (contradicted, then the code changed)
guardlink hypothesis boundaries [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--state <state> |
Only this state: unverified, supported, contradicted, retest |
--json |
Machine-readable output (guardlink.boundary-claims/v1) |
-h, --help |
display help for command |
guardlink hypothesis support
Section titled “guardlink hypothesis support”Record that a declared @boundary held when tested: a probe from the outer side was refused where the boundary says it is
guardlink hypothesis support [options] <target> [dir]Arguments
| Argument | Description |
|---|---|
target |
The boundary: its claim key, its #id, or the file:line of its @boundary |
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--evidence <text> |
What was sent from the outer side and what came back (required) |
--by <name> |
Who tested it (default: human:<git user.name>) |
-h, --help |
display help for command |
guardlink hypothesis contradict
Section titled “guardlink hypothesis contradict”Record that a declared @boundary did not hold: a probe from the outer side got through where the boundary says it is refused
guardlink hypothesis contradict [options] <target> [dir]Arguments
| Argument | Description |
|---|---|
target |
The boundary: its claim key, its #id, or the file:line of its @boundary |
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--evidence <text> |
The request that got through and its response (required) |
--by <name> |
Who tested it (default: human:<git user.name>) |
-h, --help |
display help for command |
guardlink status
Section titled “guardlink status”Show annotation coverage summary
guardlink status [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory to scan (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--not-annotated |
List source files with no GuardLink annotations |
--feature <names> |
Filter status to specific feature(s) (comma-separated) |
--sync |
Also refresh agent instruction files (this used to happen unasked — see D16) |
--blame |
Append who introduces and fixes exposures, per person and per AI tool (read from git, nothing written) |
-h, --help |
display help for command |
guardlink ci
Section titled “guardlink ci”Advisory CI checks — parse diagnostics, unmitigated exposures, confirmed exploits, unqualified acceptances, drifted @source anchors, and stale claims (exit 0 unless –strict)
guardlink ci [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory to scan (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
-f, --format <fmt> |
Output format: text (default) or json (default: “text”) |
--strict |
Exit 1 when any check finds something to gate on. Off by default — these are warnings, not a gate |
--severity <levels> |
Gate only on exposures and confirmed exploits at these severities (comma-separated: critical,high,medium,low). Unrated findings always count; drift and parse errors are unaffected |
--scope <paths> |
Gate only on findings under these root-relative paths (comma-separated). Prefix match on path segments |
--expiring-within <days> |
Warn when a qualifying @accepts lapses within this many days (0 = never warn). Default: acceptance.warn_days in .guardlink/config.json, else 14 — the same boundary the server register warns at. Never changes the exit code |
--min-coverage <percent> |
Fail when file coverage is below this percentage. Opt-in, and gates on its own without –strict: an empty model otherwise passes every check by having nothing to fail |
-h, --help |
display help for command |
guardlink unannotated
Section titled “guardlink unannotated”List source files with no GuardLink annotations
guardlink unannotated [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory to scan (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
-h, --help |
display help for command |
guardlink reanchor
Section titled “guardlink reanchor”Find @source blocks whose file:line no longer holds the symbol they name
guardlink reanchor [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory to scan (default: “.”) |
Options
| Option | Description |
|---|---|
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--apply |
Rewrite @source lines to the proposed positions (moved symbols only) |
-h, --help |
display help for command |
guardlink migrate
Section titled “guardlink migrate”Move annotations between source comments and .guardlink/annotations/ sidecars
guardlink migrate [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
--to <mode> |
Target mode: external (.gal sidecars) or inline (source comments) |
-p, --project <n> |
Project name (default: the name in .guardlink/config.json) |
--dry-run |
Report what would move without writing anything |
--allow-anchor-loss |
Proceed even when the migration discards symbol anchors (D48) |
-h, --help |
display help for command |
guardlink clear
Section titled “guardlink clear”Remove all GuardLink annotations from source files — start fresh
guardlink clear [options] [dir]Arguments
| Argument | Description |
|---|---|
dir |
Project directory (default: “.”) |
Options
| Option | Description |
|---|---|
--dry-run |
Show what would be removed without modifying files |
--include-definitions |
Also clear .guardlink/definitions files |
-y, --yes |
Skip confirmation prompt |
-h, --help |
display help for command |
guardlink gal
Section titled “guardlink gal”Display GuardLink Annotation Language (GAL) quick reference
guardlink gal [options]Options
| Option | Description |
|---|---|
-h, --help |
display help for command |