CLI command reference¶

Wardline — semantic boundary enforcement for Python.

Entry point: wardline

Global Options¶

wardline scan¶

Run the static analysis scanner against Python files and emit SARIF output.

Usage: wardline scan [OPTIONS] [PATH]

Options:

Exit Codes:

Notes: - WARNING and SUPPRESS findings are non-blocking and do not affect the exit code. - CLI flags take precedence over wardline.toml settings when both are supplied. - The output is SARIF v2.1.0 unless --preview-phase2 is used.

Examples:

# Scan with auto-detected manifest
wardline scan src/

# Scan with explicit manifest and config, write SARIF to file
wardline scan src/ --manifest wardline.yaml --config wardline.toml -o scan.sarif

# CI: deterministic output, exit 1 on any findings
wardline scan src/ --verification-mode

# Enforce a coverage threshold
wardline scan src/ --max-unknown-raw-percent 5.0

# Use a pre-resolved manifest for faster scanning in monorepos
wardline scan src/ --resolved wardline.resolved.json

wardline explain¶

Show the taint resolution path for a named function. Useful for diagnosing why a function received a particular taint state and which rules apply.

Usage: wardline explain [OPTIONS] QUALNAME

Arguments:

Options:

Exit Codes:

Output includes: - File path where the function was found. - Resolved taint state and how it was determined (decorator, module_tiers entry, or fallback). - Rules evaluated at that taint state with severity and exceptionability. - Exception register status for each rule. - Overlay resolution (which overlay governs the file, if any). - Annotation fingerprint hash and baseline match status.

Examples:

wardline explain MyClass.process
wardline explain MyClass.process --path src/ --json
wardline explain validate_payload --manifest wardline.yaml --path src/

wardline manifest¶

Manifest validation and baseline management. Groups subcommands for working with wardline.yaml.

Usage: wardline manifest [OPTIONS] COMMAND [ARGS]...

Subcommands:

wardline manifest validate¶

Validate a wardline.yaml manifest against the JSON Schema. If no file is given, the manifest is auto-discovered from the current directory.

Usage: wardline manifest validate [OPTIONS] [FILE]

Arguments:

Options:

Exit Codes:

Examples:

wardline manifest validate
wardline manifest validate wardline.yaml
wardline manifest validate path/to/wardline.yaml

wardline manifest baseline¶

Write manifest baseline files (wardline.manifest.baseline.json and wardline.perimeter.baseline.json) from the current manifest. The --approve flag is required as a deliberate confirmation step.

Usage: wardline manifest baseline [OPTIONS] {update}

Arguments:

Options:

Exit Codes:

Examples:

wardline manifest baseline update --approve
wardline manifest baseline update --approve --manifest wardline.yaml

wardline manifest coherence¶

Run all 14 coherence checks against the manifest and code annotations. This is identical to wardline coherence (the top-level command is an alias).

See wardline coherence for full documentation.

wardline coherence¶

Run all 14 coherence checks against the manifest and code annotations. Checks cover tier topology, boundary declarations, contract bindings, exception governance, and validation scope.

Usage: wardline coherence [OPTIONS]

Options:

Exit Codes:

Coherence checks run:

Examples:

wardline coherence --manifest wardline.yaml --path src/
wardline coherence --manifest wardline.yaml --path src/ --gate
wardline coherence --manifest wardline.yaml --path src/ --json

wardline corpus¶

Corpus management commands. Groups subcommands for working with the test corpus of rule specimens.

Usage: wardline corpus [OPTIONS] COMMAND [ARGS]...

Subcommands:

wardline corpus verify¶

Verify corpus specimens (YAML files in the corpus directory) against scanner rules. Computes per-cell (rule × taint_state) precision and recall where sample size is at least 5. Known false negatives are tracked separately from true negatives.

Usage: wardline corpus verify [OPTIONS]

Options:

Exit Codes:

Examples:

wardline corpus verify
wardline corpus verify --corpus-dir corpus/specimens --analysis-level 2
wardline corpus verify --json

wardline corpus publish¶

Generate wardline.conformance.json by combining corpus verification results with a self-hosting SARIF scan output. This file is consumed by wardline scan to report conformance gaps in the SARIF run properties.

Usage: wardline corpus publish [OPTIONS]

Options:

Exit Codes:

Examples:

# First produce a self-hosting SARIF, then publish conformance
wardline scan src/ -o scan.sarif
wardline corpus publish --sarif scan.sarif
wardline corpus publish --sarif scan.sarif -o wardline.conformance.json --analysis-level 3

wardline exception¶

Manage the wardline exception register (wardline.exceptions.json). Exceptions suppress specific rule findings at named locations with documented rationale and reviewer sign-off.

Usage: wardline exception [OPTIONS] COMMAND [ARGS]...

Subcommands:

wardline exception add¶

Add a new exception to the register. All fields are required. Use --governance-path expedited for time-sensitive approvals (subject to the 15% expedited ratio threshold).

Usage: wardline exception add [OPTIONS]

Options:

Exit Codes:

Examples:

wardline exception add \
  --rule PY-WL-001 \
  --location "src/app/views.py::create_record" \
  --taint-state EXTERNAL_RAW \
  --rationale "Manually validated upstream; downstream consumers sanitise." \
  --reviewer "alice" \
  --expires 2027-06-01

wardline exception grant¶

Grant a new exception. Functionally identical to add but explicitly stamps the analysis_level field to indicate which level of taint analysis the exception was reviewed under.

Usage: wardline exception grant [OPTIONS]

Options: Same as wardline exception add.

Exit Codes: Same as wardline exception add.

wardline exception expire¶

Mark an existing exception as expired by its exception ID.

Usage: wardline exception expire [OPTIONS] EXC_ID

Arguments:

Options:

Exit Codes:

Examples:

wardline exception expire exc-a1b2c3d4
wardline exception expire exc-a1b2c3d4 --reason "Finding resolved in v2.1"

wardline exception refresh¶

Refresh exception fingerprints after code changes to re-anchor exceptions to their new AST context. Required when code at an excepted location changes.

Usage: wardline exception refresh [OPTIONS] [IDS]...

Arguments:

Options:

Exit Codes:

Examples:

wardline exception refresh exc-a1b2c3d4 --actor alice --rationale "Renamed function only"
wardline exception refresh --all --confirm --actor alice --rationale "Bulk refresh after refactor"
wardline exception refresh exc-a1b2c3d4 --dry-run --actor alice --rationale "Checking context"

wardline exception review¶

List exceptions that need attention — expired exceptions, agent-originated exceptions awaiting human review, and exceptions with high recurrence counts.

Usage: wardline exception review [OPTIONS]

Options:

Exit Codes:

Examples:

wardline exception review
wardline exception review --json

wardline exception preview-drift¶

Preview which exceptions would change taint state (drift) if the analysis were run at L3 taint propagation. Does not modify anything.

Usage: wardline exception preview-drift [OPTIONS]

Options:

Exit Codes:

Examples:

wardline exception preview-drift --path src/ --manifest wardline.yaml
wardline exception preview-drift --path src/ --analysis-level 3 --json

wardline exception migrate¶

Migrate exception taint_state values to match the taint states produced by the current analysis. Requires --confirm to actually modify the exception register.

Usage: wardline exception migrate [OPTIONS]

Options:

Exit Codes:

Examples:

# Dry-run: preview what would change
wardline exception migrate --path src/ --actor alice

# Perform the migration
wardline exception migrate --path src/ --actor alice --confirm

wardline fingerprint¶

Annotation fingerprint baseline management. Tracks changes to wardline decorator annotations over time, enabling detection of unapproved annotation removal.

Usage: wardline fingerprint [OPTIONS] COMMAND [ARGS]...

Subcommands:

wardline fingerprint update¶

Compute annotation fingerprints for all decorated functions under --path and write wardline.fingerprint.json next to the manifest.

Usage: wardline fingerprint update [OPTIONS]

Options:

Exit Codes:

Examples:

wardline fingerprint update --manifest wardline.yaml --path src/
wardline fingerprint update --manifest wardline.yaml --path src/ --json

wardline fingerprint diff¶

Compare current annotations against the stored baseline. Reports added, removed, and modified annotation fingerprints. Groups changes by artefact class (policy vs enforcement).

Usage: wardline fingerprint diff [OPTIONS]

Options:

Exit Codes:

Examples:

wardline fingerprint diff --manifest wardline.yaml --path src/
wardline fingerprint diff --manifest wardline.yaml --path src/ --gate
wardline fingerprint diff --manifest wardline.yaml --path src/ --since 2026-01-01 --json

wardline regime¶

Governance regime health commands. Provides a read-only status dashboard and active verification checks.

Usage: wardline regime [OPTIONS] COMMAND [ARGS]...

Subcommands:

wardline regime status¶

Display a read-only governance health dashboard assembled from existing artefacts (manifest, exception register, fingerprint baseline, scanner config). Does not run analysis or modify any files.

Usage: wardline regime status [OPTIONS]

Options:

Exit Codes:

Dashboard sections: governance profile, analysis level, active/disabled rules, exception counts (active, expired, agent-originated, expedited ratio), fingerprint baseline coverage, and manifest ratification status.

Examples:

wardline regime status --manifest wardline.yaml --path src/
wardline regime status --manifest wardline.yaml --path src/ --json

wardline regime verify¶

Run 12 active governance verification checks covering manifest validity, coherence, exception register integrity, annotation change tracking, and ratification currency. Use --gate to make failures block CI.

Usage: wardline regime verify [OPTIONS]

Options:

Exit Codes:

Verification checks:

Examples:

wardline regime verify --manifest wardline.yaml --path src/
wardline regime verify --manifest wardline.yaml --path src/ --gate
wardline regime verify --manifest wardline.yaml --path src/ --gate --strict
wardline regime verify --manifest wardline.yaml --path src/ --json

wardline report¶

Static report generation commands. Use these to produce repo-browsable status snapshots without running a server.

Usage: wardline report [OPTIONS] COMMAND [ARGS]...

Subcommands:

wardline report overview¶

Generate a static snapshot of the current Wardline status and gaps. Markdown is the primary in-repo output because GitHub renders it directly in the repository browser; HTML and JSON are available as companion formats.

Usage: wardline report overview [OPTIONS]

Options:

Exit Codes:

Output sections: - Snapshot metadata - Overall status summary - Blocking obligations and release projection - Governance status - Coherence summary - Conformance gaps - SARIF findings summary

Examples:

# Print a GitHub-friendly Markdown snapshot to stdout
wardline report overview

# Commit the current status snapshot into docs/verification/
wardline report overview --output docs/verification/current-status.md

# Generate companion HTML and JSON artifacts
wardline report overview --format html --output docs/verification/current-status.html
wardline report overview --format json --output docs/verification/current-status.json

wardline resolve¶

Resolve all overlays and produce wardline.resolved.json. The resolved file pre-computes boundary merges, rule overrides, and optional field declarations so that wardline scan --resolved can skip overlay processing at scan time.

Usage: wardline resolve [OPTIONS]

Options:

Exit Codes:

Output format: JSON with format_version: "0.2". Contains resolved tiers, module tiers, merged rule overrides with provenance, boundaries (with overlay scope and path), optional fields, governance signals from overlays, overlay discovery summary, scanner config snapshot, and manifest metadata.

Examples:

# Emit to stdout
wardline resolve --manifest wardline.yaml

# Write to file for use with wardline scan --resolved
wardline resolve --manifest wardline.yaml -o wardline.resolved.json

# Resolve from a monorepo subdirectory
wardline resolve --manifest wardline.yaml --path /repo/services/api -o resolved.json