Skip to content
Generated from guardlink --help. Report problems against guardlink, not this page.

CLI reference

Every command, argument, and option in guardlink 2.7.1, from the package published to npm.

guardlink [options] [command]
Command Summary
guardlink init Initialize GuardLink in a project — creates .guardlink/ and updates agent instruction files
guardlink ai-bom Export agent configuration and declared reach as a CycloneDX 1.6 inventory
guardlink attest Import a local observed-reach document; compare declarations and human description pins
guardlink application-view Collect the selected application semantic model and versioned completeness/revision receipt
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 reach Check the declared @agents/@reaches/@effects/@gates against an optional code graph. With –drafts, print draft @agents/@effects for tool registrations that declare no reach. Prints text and writes nothing
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 no @accepts or unapproved @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 Rewrite the stamped GuardLink block in the agent instruction files that exist, and .guardlink/README.md
guardlink unannotated List the annotation worklist: files in scope with no GuardLink annotations, and why every other file is left out
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, self-contained HTML threat model dashboard
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

Accepted by every command.

Option Description
-V, --version output the version number
--application-manifest <file> Explicit selected application manifest for read-only projections
--no-agent-config Leave the repository’s coding-agent configuration out of the model (SPEC §5.6); .guardlink/config.json “agent_config”: {“enabled”: false} does the same per project
-h, --help display help for command

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
--refresh-scope Rewrite only the include list in an existing config.json from the languages present now
--dry-run Show what would be created without writing files
-h, --help display help for command

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

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)
--workspace Check linked sibling checkouts; fail if any sibling is unavailable or a reference is unresolved
--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 claims against a code graph, when one is installed and built: a @boundary access level a route contradicts, a route handler with no boundary to the outside, a boundary nothing crosses, a gate the graph finds no route through, an effect no agent reaches, a tool registration with no @agents. Warnings only, each a claim to check
-h, --help display help for command

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

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 no @accepts or unapproved @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

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

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

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

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

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

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

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

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

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

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

List the annotation worklist: files in scope with no GuardLink annotations, and why every other file is left out

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)
--json Print the whole worklist as JSON (guardlink.annotation-worklist/v1): worklist, annotated and excluded files, each with a reason
--excluded Also list each excluded file with its reason
-h, --help display help for command

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

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

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

Display GuardLink Annotation Language (GAL) quick reference

guardlink gal [options]

Options

Option Description
-h, --help display help for command