Gadriel Code — CLI Reference

Complete reference for the gadriel code command group (binary gadriel, v0.11.5).

gadriel code is the code-security surface: SAST, SCA (dependency CVEs), secrets, config, container, and API scanning. Every subcommand shares a set of global flags and a consistent exit-code contract (see Exit codes).

Related: configuration.md documents the .gadriel.toml file that supplies defaults for most of the flags below.

Usage: gadriel code [OPTIONS] <COMMAND>

Command summary

Command	Group	Purpose
`init`	Setup	Scaffold code-security into a repo (`.security/`, `.claude/`, hooks, MCP, CLAUDE.md, `.gitignore`, `.gadriel.toml`).
`install`	Setup	Deprecated. Thin shim for `init --skip-claude`.
`scan`	Scanning	Run a code-security scan (Layers 2/3/4). Most-used command.
`watch`	Scanning	File-save async validator (Layer 1); per-file secrets+SAST on save.
`findings`	Results	Read findings from `.security/findings.json`.
`fix`	Results	Triage a finding by ID: confirm real, dismiss as false positive, or AI-remediate.
`sbom`	Artifacts	Export SBOM (SPDX 2.3 + CycloneDX 1.4).
`report`	Artifacts	Per-framework compliance reports (Markdown/PDF) and the static HTML/JSON report bundle.
`dashboard`	Artifacts	Deprecated. Local web dashboard, superseded by `report`.
`mcp`	AI	Start the MCP server (JSON-RPC 2.0 over stdio) for AI coding agents.
`policies`	Infra	Manage the GVL rule corpus + OSV advisory snapshots.
`store`	Infra	RVF substrate operations (list/status/verify/rebuild/migrate/evict).
`learn`	Infra	Inspect the learning flywheel (priors, calibration, federation state).
`doctor`	Infra	Print the integration parity manifest for an AI-assistant platform.
`help`	—	Print help for the group or a subcommand.

Global options

Available on every gadriel code subcommand:

Flag	Description
`--json`	Output as JSON (overrides `--format`).
`-q`, `--quiet`	Minimal output for CI.
`-v`, `--verbose`	Verbose output.
`--no-color`	Disable colored output.
`--portal <PORTAL>`	Override the portal URL.
`--config <CONFIG>`	Use a specific config file instead of the default `.gadriel.toml` lookup.
`-h`, `--help`	Print help.
`-V`, `--version`	Print version.

Exit codes

The scanning and reporting commands share this contract (see per-command notes for detail):

Code	Meaning
`0`	Clean run — no findings/violations at or above the configured threshold.
`1`	Gate tripped — findings exceeded the `--fail-on` threshold (scan) / `PARTIAL` verdict (report).
`2`	Gate tripped harder — tooling error/crash (scan) / `FAIL` verdict (report).
`3`	Subcommand not yet available, or a true rendering/tooling failure (report).

Hooks are intended to not block on tooling errors — distinguish "scan ran and found issues" (exit 1) from "tool errored" (exit 2) in CI logic.

Setup

`init`

Initialize code-security in this repo — the W1 consolidated scaffold: .security/, .claude/, git hooks, MCP server registration, CLAUDE.md, .gitignore, and a starter .gadriel.toml. By default it also syncs the OSV vulnerability database for the ecosystems detected in the repo so the first gadriel code scan runs with CVE detection already enabled.

Usage: gadriel code init [OPTIONS]

Options

Flag	Description
`--force`	Overwrite all gadriel-owned files (interactive prompt confirms; pass `--yes` to skip).
`--upgrade`	Merge new settings into existing files; preserve user / other-tool customizations.
`--add-missing`	Add only missing files / keys; never modify existing ones.
`--skip-hooks`	Skip git hook installation (CI-only setups).
`--skip-claude`	Skip the `.claude/` scaffold (non-Claude users).
`--register-marketplace`	Opt-in: write the Gadriel marketplace URL into `.claude/marketplaces.json`.
`--attribution`	Opt-in: add a `Co-Authored-By: Gadriel` trailer to git config.
`--yes`	Skip every interactive confirmation prompt (CI / scripted use).
`--policies <POLICIES>`	Override the rule-corpus repo URL. Default: `https://github.com/Gadriel-ai/gadriel-code-policies`.
`--rev <REV>`	Pin a specific commit of the policies repo.
`--offline`	Skip network pull; use the vendored snapshot only.
`--skip-osv`	Skip the OSV sync during init (air-gapped / CI setups that sync separately).
`--ci <CI>`	CI providers to install. Repeatable / comma-separated. Valid: `github`, `gitlab`, `circleci`, `jenkins`, `all`. Default: `github`.
`--platform <PLATFORM>`	Target AI-assistant platform(s) to scaffold for. Repeatable / comma-separated. Values: `claude-code`, `cursor`, `windsurf`, `copilot`, `codex`, `jetbrains`, `claude-desktop`, `chatgpt`, `ai-studio`.
`--dry-run`	Plan the platform scaffold without writing files (with `--platform`).
`--uninstall`	Remove gadriel from the named platform configs (with `--platform`).

Example

bash
# Scaffold .security/ + .claude/, install GitHub CI, sync OSV, no prompts
gadriel code init --yes

# Non-Claude, multi-platform, offline scaffold
gadriel code init --skip-claude --platform cursor,codex --offline

`install`

(DEPRECATED) Use gadriel code init --skip-claude instead. Preserved as a thin shim that delegates to init --skip-claude so existing scripts keep working; it prints a one-line migration warning and accepts no flags of its own (only the global options).

Usage: gadriel code install [OPTIONS]

bash
gadriel code install    # → warns, then runs `init --skip-claude`

Scanning

`scan`

Run a code-security scan (Layers 2/3/4 via flags). This is the primary, most-used command. It writes findings to .security/findings.json (OCSF envelope) and re-renders the HTML report bundle unless told otherwise.

Usage: gadriel code scan [OPTIONS] [PATH]

Arguments

Argument	Description
`[PATH]`	Path to scan. Defaults to the current directory.

Key flags

Gating & exit behavior

Flag	Description
`--fail-on <FAIL_ON>`	Exit non-zero if any finding's severity is at or above the threshold. Ladder: `none < info < low < medium < high < critical`. Default `none` (never block). Exit codes: `0` clean, `1` threshold exceeded, `2` tooling error.
`--verdict-exit-zero`	Collapse a verdict-driven non-zero exit to `0`; a genuine tooling error still exits non-zero. Useful for reporting-only pipelines.
`--layer <LAYER>`	Which execution layer invoked this scan: `l1` (file-save watch), `l2` (pre-commit), `l3` (PR gate), `l4` (CI/CD). Case-insensitive. When omitted the layer is inferred (`--staged`→`l2`, CI env→`l4`, else `l2`). Drives audit-log attribution and the remediation-funnel KPI — it does not change which rules run.
`--staged`	Scan only the files staged for commit (`git diff --cached`). Core of a pre-commit gate. Exits `0` cleanly when not a git repo or nothing is staged.

Output

Flag	Description
`--format <FORMAT>`	Terminal summary format: `table` (default, human-readable) or `json` (passes `findings.json` through as-is).
`--output <PATH>`	Write the findings file to `<PATH>` instead of the default `.security/findings.json`. Parent dirs are created automatically.
`--output-format <FMT>`	Format of the written findings file (distinct from `--format`): `ocsf` (default), `json` (alias for `ocsf`), `sarif` (not yet supported — exits with a clear message).
`--columns <COLUMNS>`	Render the post-scan output as CSV with only the listed columns. Supported: `id`, `severity`, `title`, `description`, `scenario_id`, `recommendation`, `cwe`, `confidence`, `is_test_pattern`, `classification`, `validation_method`, `target`, `target_type`.
`--no-html`	Skip the auto-regeneration of `.security/reports/index.html` (+ `report.json`) at the end of the scan. Use in CI where the post-scan render is wasted work.

OSV / SCA (dependency CVEs)

Flag	Description
`--no-osv`	Skip OSV-CVE consumption entirely. SCA still runs with non-CVE rules (license, health, manifest hygiene); GVL rules requiring the `osv` data source are skipped and a DEGRADED-mode banner is shown. Compatible with `--offline`.
`--osv-auto-sync <MODE>`	Control the lazy OSV auto-sync before SCA on first scan: `yes` (sync silently), `no` (skip, degraded), `prompt` (default — interactive `[Y/n]` on a TTY, falls through to `no` on a non-TTY).
`--non-interactive`	CI-friendly alias for `--osv-auto-sync=yes`.
`--offline`	Alias for `--osv-auto-sync=no`; skips every outbound HTTPS call the sync would issue, surfaces the DEGRADED banner.
`--osv-ecosystems <SET>`	Which OSV ecosystem shards to sync: `auto` (default, detect from manifests — smaller download), `all` (legacy single-blob `all.zip`), or a comma-separated allowlist (e.g. `pypi,npm`).
`--enrich-sbom-online`	Opt-in plumbing for online PyPI license enrichment; currently only stamps a `gadriel:license_source: "online-pypi-pending"` marker (no outbound call yet).

Deep scanning modes

Flag	Description
`--git-history`	Layer-4 git-history sweep — walk every commit and scan each blob for secrets. Requires `fetch-depth: 0` in CI; hard-fails on a shallow clone with remediation. Runs automatically at `--layer l4`; use `--no-git-history` to opt out there. Opt-in at other layers.
`--no-git-history`	Opt out of the automatic Layer-4 git-history sweep. No effect outside `--layer l4`.
`--no-workspace-taint`	Disable workspace-wide SAST taint analysis and fall back to per-file taint only (iter-91). By default directory scans build a workspace-wide taint coordinator across Python files to catch cross-file flows. Single-file invocations never use the workspace pass.
`--scan-iac`	EXPERIMENTAL — opt in to Infrastructure-as-Code scanning (Terraform `*.tf`, Kubernetes, CloudFormation, Helm). Off by default; expect false positives (precision unmeasured).
`--corroborate`	EXPERIMENTAL — drive already-installed external analyzers (gosec/bandit/eslint/spotbugs) and correlate their findings with gadriel's. Advisory only; never changes severity/confidence/gating. Absent = byte-identical to no corroboration.

Artifact isolation

Flag	Description
`--ephemeral`	Write all scan artifacts to a discarded TempDir instead of `.security/` (GAD-019). Use with `--output <path>` in CI that must not leave a `.security/` directory behind. Without `--output`, artifacts are written then immediately discarded (dry-run).

Exit codes

Code	Meaning
`0`	Clean scan — no findings at or above `--fail-on`.
`1`	Findings exceeded the threshold (security gate tripped).
`2`	Tooling error / crash (hooks should not block on this).

Examples

bash
# Full scan of a project directory
gadriel code scan ./my-project

# Pre-commit gate: only staged files, block on critical findings
gadriel code scan --staged --fail-on critical

# CI/CD scan: block on high+, machine output to a fixed artifact path, offline OSV
gadriel code scan --layer l4 --fail-on high \
  --output findings/findings.json --output-format ocsf --offline

# Ephemeral CI scan that leaves no .security/ behind
gadriel code scan --ephemeral --output findings/findings.json --no-html

# Experimental: IaC + external-tool corroboration
gadriel code scan ./infra --scan-iac --corroborate

# CSV summary for a spreadsheet
gadriel code scan --columns id,severity,title

`watch`

File-save async validator (Layer 1) — the L1-lite watcher (BUG-022). Runs Secrets + SAST per-file scans on save, 300ms-debounced, and merges results into .security/findings.json.

Usage: gadriel code watch [OPTIONS]

Only the global options apply.

bash
gadriel code watch

Results

`findings`

Read findings from .security/findings.json.

Usage: gadriel code findings [OPTIONS]

Flag	Description
`--format <FORMAT>`	`table` (default) or `json` (passes `findings.json` through as-is).

bash
gadriel code findings
gadriel code findings --format json

`fix`

Triage a finding by ID — confirm it real, dismiss it as a false positive, or hand it to an AI agent for remediation. --false-positive and --confirm-real short-circuit the LLM path entirely (zero Claude calls): they write a Bayesian posterior update plus an audit-log entry and exit.

Usage: gadriel code fix [OPTIONS] [FINDING_ID]

Arguments

Argument	Description
`[FINDING_ID]`	Finding ID to remediate.

Options

Flag	Description
`--false-positive`	Record the finding as a confirmed false positive. Updates the per-repo Bayesian posterior so future findings for the same `(rule_id, destination, scope)` triple are demoted/suppressed. Mutually exclusive with `--confirm-real`.
`--confirm-real`	Record the finding as a confirmed real risk (increases α on the posterior). Mutually exclusive with `--false-positive`.
`--reason <TEXT>`	Human-readable rationale for a `--false-positive` dismissal. Written verbatim into the `.gadriel-waivers.toml` waiver entry and the audit-log note.
`--send-source`	Explicit consent to ship the finding's source excerpt to Anthropic when the live `ClaudeRunner` path is active. Without it, `fix` aborts before any outbound call. Mock runs (`GADRIEL_USE_MOCK_RUNNER=1`) ignore this flag.

Examples

bash
# AI-assisted remediation (default path)
gadriel code fix CODE-W1-L2-021

# Dismiss as a false positive with a rationale
gadriel code fix CODE-W1-L2-021 --false-positive \
  --reason "zero-copy idiom, not an interface cast"

# Confirm a real risk (feeds the per-repo prior)
gadriel code fix CODE-W1-L2-021 --confirm-real

Artifacts

`sbom`

Export an SBOM in SPDX 2.3 and/or CycloneDX 1.4.

Usage: gadriel code sbom [OPTIONS] [PATH]

Arguments

Argument	Description
`[PATH]`	Project root. Defaults to the current directory.

Options

Flag	Description
`--format <FORMAT>`	Which format(s) to write: `both` (default), `spdx`, `cyclonedx`.
`--diff <DIFF>`	Diff against the SBOM history snapshot at this git ref (e.g. `HEAD~1`, `v1.0.0`, a short SHA).

bash
gadriel code sbom
gadriel code sbom --format cyclonedx
gadriel code sbom --diff HEAD~1

`report`

Generate per-framework compliance reports (Markdown by default, optional typst PDF source), or emit the RVF World-Class static HTML / JSON report bundle (Wave 5). An executive (CISO) summary PDF is generated by default on every run.

Usage: gadriel code report [OPTIONS]

Options

Flag	Description
`--compliance <COMPLIANCE>`	Framework slug, comma-separated list, or `all`. Slugs: `eu-ai-act`, `nist-ai-rmf`, `soc2`, `hipaa`, `pci-dss`, `owasp-llm-top10`, `owasp-agentic`, `iso-42001`, `cmmc-level-1`, `cyber-insurance-readiness`. Defaults to `[report].frameworks` in `.gadriel.toml` when omitted.
`--all-frameworks`	Emit reports for all six core frameworks. Alias: `--all-pillars`.
`--format <LIST>`	Comma-separated output formats: `pdf`, `markdown`, `html`, plus aliases `both` (= pdf,markdown) and `all` (= pdf,markdown,html). Default when omitted and neither `--pdf`/`--markdown` is set: `pdf,html`. Mutually exclusive with the `--pdf`/`--markdown` booleans.
`--pdf`	Legacy boolean: also emit a typst PDF source (and compile if `typst` is on PATH).
`--markdown`	Legacy boolean: emit Markdown.
`--output-dir <DIR>`	Override the compliance output dir (default `.security/compliance/`).
`--output <DIR>`	Override the HTML / JSON output dir (default `.security/reports/`). No effect on the compliance dispatch.
`--sections <SECTIONS>`	Comma-separated HTML sections to render (default: all). Valid: `findings`, `compliance`, `drift`, `trends`, `audit`, `home`.
`--json`	Emit the full structured payload to `.security/reports/report.json`. May combine with HTML or be used alone.
`--executive`	Accepted no-op (alias `--ciso`) — the executive summary is on by default. Pass `--no-executive` to opt out.
`--no-executive`	Skip the executive (CISO) summary PDF.
`--economics-model <MODEL>`	Model for the executive economics estimate: `sonnet` (default), `opus`, `haiku`. Only meaningful with the executive summary.
`--with-exposure-estimate`	Include an illustrative, clearly-labeled "potential exposure avoided" band (industry-average; not a Gadriel measurement). Off by default.
`--fail-on <FAIL_ON>`	Exit-code behavior: `verdict` (default — 1=PARTIAL, 2=FAIL, 3=fatal) or `render-only` (exit 0 for any verdict; 3 only for true rendering failures).
`--verdict-exit-zero`	Collapse a verdict-driven non-zero exit (PARTIAL→1, FAIL→2) to `0`; a rendering failure still exits `3`. Equivalent to `--fail-on render-only`.

Exit codes

Code	Meaning
`0`	Report generated, no policy violations (or `render-only`).
`1`	`PARTIAL` verdict.
`2`	`FAIL` verdict.
`3`	Fatal rendering/tooling failure (missing `findings.json`, framework YAML not found, typst failure, …).

Examples

bash
# EU AI Act report — PDF + HTML (default)
gadriel code report --compliance eu-ai-act

# SOC 2, PDF only
gadriel code report --compliance soc2 --format pdf

# All six frameworks, PDF + HTML
gadriel code report --all-frameworks

# HTML bundle, only two sections
gadriel code report --format html --sections findings,compliance

# JSON dump only
gadriel code report --json

`dashboard`

[DEPRECATED — use report] Open the local web dashboard, bound to 127.0.0.1. Superseded by the static HTML report; kept functional pending removal.

Usage: gadriel code dashboard [OPTIONS]

Flag	Description
`--port <PORT>`	TCP port (default `8765`). Bind IP is hard-wired to `127.0.0.1`.
`--no-browser`	Skip the browser auto-launch.
`--security-dir <SECURITY_DIR>`	Override the `.security/` directory the dashboard reads from.

bash
gadriel code dashboard --port 8080 --no-browser

AI

`mcp`

Start the MCP server (JSON-RPC 2.0 over stdio). Exposes an 8-tool surface — validate_buffer, validate_file, findings_for_path, fix_finding, dismiss_false_positive, submit_ai_findings, start_remediation_campaign, campaign_advance — to AI coding agents (Claude Code, Cursor, and other MCP-capable assistants). Reads JSON-RPC requests from stdin, writes responses to stdout, logs to stderr. See MCP Tools Reference for each tool's params and returns.

Usage: gadriel code mcp [OPTIONS]

Flag	Description
`--auth-token <AUTH_TOKEN>`	Name of the env var to read the auth token from (default `GADRIEL_TOKEN`). Reserved for future HTTP/SSE transports; stdio is unauthenticated.
`--license-check`	License-check toggle. Default `true`; set `false` to bypass (used by tests).
`--tier2`	Opt into Tier-2 host-LLM semantic analysis. Default OFF. A bare flag forces it on for this invocation; absence defers to `GADRIEL_TIER2` / `GADRIEL_TIER2_ENABLED` env or `[tier2].enabled` in config.

bash
gadriel code mcp
gadriel code mcp --tier2

Infrastructure

`policies`

Manage the GVL rule corpus + advisory snapshots. Currently only the --osv flag is wired (manual OSV snapshot sync); other policies subcommands are stubbed.

Usage: gadriel code policies [OPTIONS]

Flag	Description
`--osv`	Sync the OSV advisory snapshot from the configured mirror.
`--force`	Force a re-fetch even when the local snapshot is fresh.

bash
gadriel code policies --osv
gadriel code policies --osv --force

`store`

RVF substrate operations — list, verify, rebuild, and migrate the .rvf files under the per-machine and per-repo store roots.

Usage: gadriel code store [OPTIONS] <COMMAND>

Subcommand	Purpose
`list`	List every `.rvf` file in the per-machine and per-repo stores.
`status`	Alias for `list`.
`verify`	Verify every `.rvf` file (signature for envelopes, witness chain for everything else). Exits non-zero if any entry fails verification.
`rebuild`	Rebuild the RVF companion for a specific store kind from the sidecar JSON.
`migrate`	Migrate legacy NDJSON / JSONL store directories into the RVF substrate.
`evict`	FIFO-evict every evictable store down to its `DEFAULT_EVICTION_LIMIT`. Dry-run by default.

`store list` / `store status`

Flag	Description
`--format <FORMAT>`	`table` (default) or `json`.

bash
gadriel code store list
gadriel code store status --format json

`store verify`

Exits non-zero on any verification failure.

bash
gadriel code store verify

`store rebuild`

Flag	Description
`--kind <KIND>`	Required. Which store kind to rebuild. Currently implemented: `audit-embeddings` and `priors`. The values `skills`, `fingerprint`, `transitions`, `trajectories`, and `episodes` are accepted but not yet implemented (they exit with a "not yet implemented" message).

bash
gadriel code store rebuild --kind audit-embeddings

`store migrate`

Ships audit-log + timeseries imports; other kinds deferred. The --backfill flag additionally synthesises S-01/S-02 rows from .security/history/<YYYY-MM-DD>/ snapshots (idempotent across re-runs).

Flag	Description
`--backfill`	Synthesise `ScanRun` (S-01) + `FindingsHistoryRow` (S-02) rows from every `.security/history/<date>/findings.json` snapshot. Without it, the backfill path is dry-run only.
`--from-date <YYYY-MM-DD>`	Inclusive lower bound on the snapshot date.
`--to-date <YYYY-MM-DD>`	Inclusive upper bound on the snapshot date.

bash
gadriel code store migrate --backfill --from-date 2026-01-01

`store evict`

Records a StoreEvicted event in S-08 capturing per-store drop counts. Dry-run unless --apply.

Flag	Description
`--apply`	Commit the eviction (without it, reports what would be evicted, no on-disk changes).
`--format <FORMAT>`	`table` (default) or `json`.

bash
gadriel code store evict            # dry-run
gadriel code store evict --apply    # commit

`learn`

Inspect the learning flywheel — learned priors, calibration-table version, and federation opt-in state.

Usage: gadriel code learn [OPTIONS] <COMMAND>

Subcommand	Purpose
`status`	Show the repo's learned priors, calibration-table version, and federation opt-in state.

bash
gadriel code learn status
gadriel code learn status --json

`doctor`

Print the integration parity manifest for an AI-assistant platform — MCP/hooks/rules support and version gates.

Usage: gadriel code doctor [OPTIONS] --platform <PLATFORM>

Flag	Description
`--platform <PLATFORM>`	Required. Platform to inspect: `claude-code`, `cursor`, `windsurf`, `copilot`, `codex`, `jetbrains`, `claude-desktop`, `chatgpt`, `ai-studio`.

bash
gadriel code doctor --platform claude-code
gadriel code doctor --platform cursor --json

`help`

Print help for the gadriel code group or any subcommand.

bash
gadriel code help
gadriel code help scan

Deprecations at a glance

Deprecated	Replacement
`gadriel code install`	`gadriel code init --skip-claude`
`gadriel code dashboard`	`gadriel code report` (static HTML bundle)

Notes

Some subcommands not shown by --help are still reachable by name and exit 3 when not yet available.
Set PREFLIGHT_OFFLINE=1 to run any command in local-only mode (no token required). </content>