forge-guard 0.3.5

# 📖 Forge Guard — Command Reference

> Complete documentation for all 22 `forge-guard` subcommands.

**Navigation:** [Back to README](README.md) · [Changelog](CHANGELOG.md) · [Roadmap](milestone-based-roadmap.md)

---

## Table of Contents

| # | Command | Description |
|---|---------|-------------|
| 1 | [`forge-guard audit`](#1-forge-guard-audit) | Run a comprehensive security audit |
| 2 | [`forge-guard deploy`](#2-forge-guard-deploy) | Deploy contracts with automatic security checks |
| 3 | [`forge-guard deploy-safe`](#3-forge-guard-deploy-safe) | Deploy with mandatory security pass requirement |
| 4 | [`forge-guard fuzz`](#4-forge-guard-fuzz) | Run fuzzing campaigns |
| 5 | [`forge-guard invariant`](#5-forge-guard-invariant) | Run invariant tests |
| 6 | [`forge-guard simulate`](#6-forge-guard-simulate) | Run deployment simulations |
| 7 | [`forge-guard gas`](#7-forge-guard-gas) | Analyze gas usage |
| 8 | [`forge-guard report`](#8-forge-guard-report) | Generate audit reports from existing results |
| 9 | [`forge-guard verify`](#9-forge-guard-verify) | Verify contract deployments |
| 10 | [`forge-guard doctor`](#10-forge-guard-doctor) | Analyze project health and configuration |
| 11 | [`forge-guard watch`](#11-forge-guard-watch) | Watch files for changes and re-audit |
| 12 | [`forge-guard ci`](#12-forge-guard-ci) | Generate CI/CD pipeline configurations |
| 13 | [`forge-guard benchmark`](#13-forge-guard-benchmark) | Run performance benchmarks |
| 14 | [`forge-guard scan`](#14-forge-guard-scan) | Scan dependencies for vulnerabilities |
| 15 | [`forge-guard upgrade-check`](#15-forge-guard-upgrade-check) | Analyze upgrade paths and proxy safety |
| 16 | [`forge-guard plugins`](#16-forge-guard-plugins) | Manage audit plugins |
| 17 | [`forge-guard chain`](#17-forge-guard-chain) | Configure chain settings |
| 18 | [`forge-guard sbom`](#18-forge-guard-sbom) | Generate a Software Bill of Materials (SBOM) |
| 19 | [`forge-guard install-hook`](#19-forge-guard-install-hook) | Install/uninstall git pre-commit hook |
| 20 | [`forge-guard security`](#20-forge-guard-security) | Configure security settings |
| 21 | [`forge-guard import`](#21-forge-guard-import) | Import findings from external analyzers (Slither, Mythril, Semgrep) |
| 22 | [`forge-guard notify`](#22-forge-guard-notify) | Send webhook notifications (Slack, Discord) |

---

## Shared Flags

These flags are available on most commands (noted per-command with ✅).

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--chain <NAME>` | `String` | `ethereum` | Target chain to audit for |
| `--project <PATH>` | `PathBuf` | `.` | Path to Foundry project root |
| `--json` | `bool` | `false` | Output as JSON |
| `--markdown` | `bool` | `false` | Output as Markdown |
| `--html` | `bool` | `false` | Output as HTML |
| `--strict` | `bool` | `false` | Fail on any MEDIUM+ finding |
| `--offline` | `bool` | `false` | Skip RPC calls |
| `--production` | `bool` | `false` | Production mode (extra checks) |
| `--report` | `bool` | `false` | Generate report files |
| `--parallelism <N>` | `usize` | `4` | Number of parallel workers |

---

## 1. `forge-guard audit`

Run a comprehensive security audit on Solidity smart contracts. The flagship command — runs 50+ vulnerability checks, generates findings, scores, and reports.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--full` | `bool` | `false` | Run all available checks (equivalent to `--exploit --gas`) |
| `--quick` | `bool` | `false` | Skip parser-heavy and expensive checks for ~5x faster results |
| `--summary` | `bool` | `false` | Show executive summary with PASS/FAIL verdict and action items |
| `--ai` | `bool` | `false` | Enable AI-powered auditing using configured LLM provider |
| `--ai-provider <PROVIDER>` | `String` | `openai` | AI provider: `openai`, `claude`, or `ollama` |
| `--ai-model <MODEL>` | `String` | `gpt-5` | AI model identifier (e.g., `gpt-5`, `claude-5-sonnet-20260701`) |
| `--ai-api-key <KEY>` | `Option<String>` | — | AI API key (reads `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` env var when empty) |
| `--ollama-endpoint <URL>` | `Option<String>` | — | Ollama endpoint URL (default: `http://localhost:11434`) |
| `--ai-full` | `bool` | `false` | Run a full AI audit (security + gas + logic auditors) |
| `--exploit` | `bool` | `false` | Include exploit path analysis |
| `--gas` | `bool` | `false` | Include gas analysis |
| `--all-chains` | `bool` | `false` | Audit across all supported chains (in parallel via Rayon) |
| `--max-parallel-chains <N>` | `usize` | `4` | Maximum number of chains to audit concurrently when `--all-chains` is set |
| `--sources <DIRS>` | `String` | `src` | Source directories to audit (comma-separated) |
| `--exclude <PATTERNS>` | `Option<String>` | — | Exclude patterns (comma-separated) |
| `--template <NAME>` | `Option<String>` | — | Audit template to use (`erc20`, `erc721`, `defi`, `bridge`, `upgradeable`) |
| `--list-templates` | `bool` | `false` | List available audit templates |
| `--suppressions <FILE>` | `Option<PathBuf>` | — | Suppression file (default `.forge-guard-suppressions`) |
| `--show-suppressed` | `bool` | `false` | Show suppressed findings (visually marked) instead of hiding them |
| `--generate-suppressions` | `bool` | `false` | Write a suppression file from current findings and exit |
| `--notify` | `bool` | `false` | Send webhook notifications after the audit |
| `--enable-history` | `bool` | `false` | Record the audit in the SQLite history database for trend tracking |

### Templates

Built-in audit templates adjust enabled checks, focus areas, and scoring thresholds:

| Template | Focus Areas | Description |
|----------|-------------|-------------|
| `erc20` | Token logic, approvals, supply | Standard ERC20 token audit with emphasis on transfer logic, allowance mechanisms, and supply consistency |
| `erc721` | NFT logic, metadata, royalties | NFT contract audit covering ownership tracking, metadata integrity, and royalty enforcement |
| `defi` | Lending, swaps, oracles, MEV | DeFi protocol audit focused on lending pools, AMM logic, price oracle manipulation, and MEV exposure |
| `bridge` | Cross-chain, message passing, validators | Bridge contract audit for cross-chain message verification, validator set management, and fund safety |
| `upgradeable` | Proxies, storage gaps, initializers | Upgradeable contract audit covering proxy patterns, storage collision prevention, and initializer safety |

Templates are **fully applied** to the audit:

- `enabled_checks` / `disabled_checks` — force-enable or disable specific check IDs in the security engine
- `focus_areas` — weighted 2× in the overall security score calculation
- `min_scores` — per-category minimum scores that gate production readiness

Templates are JSON files in `~/.forge-guard/templates/` and are user-customizable. A user template with the same name as a built-in overrides it. To create one:

```bash
mkdir -p ~/.forge-guard/templates
cat > ~/.forge-guard/templates/my-defi.json <<'EOF'
{
  "name": "my-defi",
  "description": "My DeFi focus template",
  "enabled_checks": ["FA-H-011", "FA-H-016"],
  "disabled_checks": [],
  "min_scores": { "exploit_resistance": 80 },
  "focus_areas": ["exploit_resistance", "security"]
}
EOF
forge-guard audit --template my-defi
```

### Examples

```bash
# Standard audit
forge-guard audit

# Quick audit (~5x faster)
forge-guard audit --quick

# Full audit with exploit paths and gas analysis
forge-guard audit --full

# Executive summary
forge-guard audit --summary

# Quick summary (fastest feedback)
forge-guard audit --quick --summary

# Cross-chain audit
forge-guard audit --chain arbitrum
forge-guard audit --all-chains

# AI-powered audit
forge-guard audit --ai
forge-guard audit --ai --ai-provider claude --ai-model claude-5-sonnet-20260701

# Output formats
forge-guard audit --json
forge-guard audit --markdown
forge-guard audit --json --report   # Save to file

# Strict mode (fail on any finding)
forge-guard audit --strict

# Use a template
forge-guard audit --template defi
forge-guard audit --list-templates

# Custom source directories
forge-guard audit --sources "src,contracts" --exclude "test,mock"
```

---

## 2. `forge-guard deploy`

Deploy contracts with automatic security checks. Runs an audit before deployment and blocks if vulnerabilities are found. Use `--force` to bypass the guard.

**Shared flags:** ✅

### Flags

| Argument/Flag | Type | Default | Description |
|---------------|------|---------|-------------|
| `contract` | `Option<String>` | — | Contract name to deploy |
| `--force` | `bool` | `false` | Bypass deployment guard (warnings still shown) |
| `--args <ARGS>` | `Option<String>` | — | Constructor arguments (comma-separated) |
| `--salt <SALT>` | `Option<String>` | — | Create2 salt for deterministic address |
| `--verify` | `bool` | `false` | Verify contract after deployment |
| `--notify` | `bool` | `false` | Send webhook notification after the deployment attempt |

### Examples

```bash
# Deploy with security guard
forge-guard deploy

# Deploy specific contract
forge-guard deploy MyContract

# Force deploy (bypasses security guard)
forge-guard deploy MyContract --force

# Deploy with constructor arguments
forge-guard deploy MyContract --args "0x1234,100"

# Create2 deployment
forge-guard deploy MyContract --salt 0xabc

# Deploy with auto-verification
forge-guard deploy MyContract --verify
```

---

## 3. `forge-guard deploy-safe`

Deploy with a mandatory security pass requirement — **cannot be bypassed** with `--force`. Contracts must pass all security checks to deploy.

**Shared flags:** ✅

### Flags

| Argument/Flag | Type | Default | Description |
|---------------|------|---------|-------------|
| `contract` | `Option<String>` | — | Contract name to deploy |
| `--args <ARGS>` | `Option<String>` | — | Constructor arguments (comma-separated) |
| `--verify` | `bool` | `false` | Verify contract after deployment |
| `--notify` | `bool` | `false` | Send webhook notification after the deployment attempt |

### Examples

```bash
# Safe deploy (blocked if vulnerabilities found)
forge-guard deploy-safe MyContract

# With constructor args
forge-guard deploy-safe MyContract --args "0x1234"
```

---

## 4. `forge-guard fuzz`

Run fuzzing campaigns against your smart contracts. Configurable run count, seeding, and test function filtering.

**Shared flags:** ✅

### Flags

| Argument/Flag | Type | Default | Description |
|---------------|------|---------|-------------|
| `contract` | `Option<String>` | — | Fuzz contract |
| `--runs <N>` | `u32` | `10000` | Number of fuzz runs |
| `--seed <N>` | `Option<u64>` | — | Fuzz seed for reproducible results |
| `--test <NAME>` | `Option<String>` | — | Test function filter |

### Examples

```bash
# Basic fuzzing
forge-guard fuzz

# Fuzz specific contract with 50k runs
forge-guard fuzz Vault --runs 50000

# Reproducible fuzzing with seed
forge-guard fuzz --seed 42

# Fuzz a specific test function
forge-guard fuzz Vault --test testFuzzDeposit
```

---

## 5. `forge-guard invariant`

Run invariant tests on your smart contracts. Supports configurable run depth and failure modes.

**Shared flags:** ✅

### Flags

| Argument/Flag | Type | Default | Description |
|---------------|------|---------|-------------|
| `contract` | `Option<String>` | — | Invariant contract |
| `--runs <N>` | `u32` | `1000` | Number of runs |
| `--depth <N>` | `u32` | `100` | Depth of calls per run |
| `--fail-on-revert` | `bool` | `false` | Fail test on any revert |

### Examples

```bash
# Basic invariant test
forge-guard invariant

# Custom runs and depth
forge-guard invariant --runs 2000 --depth 150

# Fail on revert
forge-guard invariant --fail-on-revert
```

---

## 6. `forge-guard simulate`

Run deployment simulations to analyze contract behavior before deploying. Includes MEV analysis capability.

**Shared flags:** ✅

### Flags

| Argument/Flag | Type | Default | Description |
|---------------|------|---------|-------------|
| `contract` | `Option<String>` | — | Contract to simulate deployment for |
| `--blocks <N>` | `u32` | `100` | Number of simulation blocks |
| `--deployer <ADDRESS>` | `Option<String>` | — | Simulate with specific deployer address |
| `--mev` | `bool` | `false` | Include MEV (sandwich, flash loan) analysis |

### Examples

```bash
# Basic simulation
forge-guard simulate

# With MEV analysis
forge-guard simulate --mev

# Custom block range and deployer
forge-guard simulate --blocks 200 --deployer 0x...
```

---

## 7. `forge-guard gas`

Analyze gas usage and get optimization suggestions. Can compare against previous reports.

**Shared flags:** ✅

### Flags

| Argument/Flag | Type | Default | Description |
|---------------|------|---------|-------------|
| `contract` | `Option<String>` | — | Check specific contract |
| `--diff <FILE>` | `Option<String>` | — | Compare with previous report |
| `--all` | `bool` | `false` | Report gas for all functions |
| `--warn-threshold <N>` | `u64` | `50000` | Minimum gas threshold for warnings |

### Examples

```bash
# Analyze gas for all contracts
forge-guard gas

# Analyze specific contract
forge-guard gas Vault

# Report all functions
forge-guard gas --all

# Compare with baseline
forge-guard gas --diff previous.json

# Custom warning threshold
forge-guard gas --warn-threshold 100000
```

---

## 8. `forge-guard report`

Generate audit reports from existing audit result JSON files. Supports multiple output formats.

**Shared flags:** ✅

### Flags

| Argument/Flag | Type | Default | Description |
|---------------|------|---------|-------------|
| `input` | `Option<PathBuf>` | — | Path to audit result JSON |
| `--format <FORMAT>` | `String` | `markdown` | Output report format (`json`, `markdown`, `html`) |
| `--output <PATH>` | `Option<PathBuf>` | — | Output file path |
| `--exploit-paths` | `bool` | `false` | Include exploit paths in report |
| `--summary` | `bool` | `false` | Summary only |
| `--history` | `bool` | `false` | Show score trends over time from the history database (SQLite) |
| `--regression` | `bool` | `false` | Highlight findings new since the last audit (regression diff) |

### Examples

```bash
# Generate markdown report from results
forge-guard report result.json

# JSON output
forge-guard report --format json

# HTML report
forge-guard report --format html

# Save to file
forge-guard report result.json --output audit_report.md

# Summary only
forge-guard report --summary

# Score trends over time (run forge-guard audit --enable-history first)
forge-guard report --history

# Findings new since the last audit
forge-guard report --regression
```

---

## 9. `forge-guard verify`

Verify contract deployments on block explorers. Supports on-chain bytecode matching and multiple explorer endpoints.

**Shared flags:** ✅

### Flags

| Argument/Flag | Type | Default | Description |
|---------------|------|---------|-------------|
| `address` | `Option<String>` | — | Contract address to verify |
| `name` | `Option<String>` | — | Contract name |
| `--api-key <KEY>` | `Option<String>` | — | Explorer API key |
| `--constructor-args <ARGS>` | `Option<String>` | — | Constructor arguments ABI-encoded |
| `--all` | `bool` | `false` | Check all deployments |

### Examples

```bash
# Verify a specific contract
forge-guard verify --address 0x... --name MyContract

# Bulk verify all deployments
forge-guard verify --all

# Verify on a different chain
forge-guard verify --address 0x... --name MyContract --chain base

# With constructor arguments
forge-guard verify --address 0x... --name Token --constructor-args 0x0001
```

---

## 10. `forge-guard doctor`

Analyze project health and configuration. Checks Foundry installation, Solidity version, project structure, dependencies, compiler settings, RPC connectivity, and security configuration.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--fix` | `bool` | `false` | Fix issues automatically where possible |
| `--verbose` | `bool` | `false` | Verbose output |
| `--check <CATEGORY>` | `Option<String>` | — | Check only specific category |
| `--sync` | `bool` | `false` | Sync forge-guard.toml settings from foundry.toml |
| `--dry-run` | `bool` | `false` | Preview config sync changes without writing (use with `--sync`) |
| `--diff` | `bool` | `false` | Show diff of what `--sync` would change (use with `--sync`) |

### Checks Performed

| Check | Description |
|-------|-------------|
| 🔍 Foundry installation | Verifies Foundry is installed and checks version |
| 🔍 Solidity version | Checks configured Solidity compiler version |
| 🔍 Project structure | Validates source directories, config files |
| 🔍 Dependency vulnerabilities | Scans for known vulnerable dependencies |
| 🔍 Compiler settings | Checks optimizer, EVM version, and other settings |
| 🔍 RPC connectivity | Tests RPC endpoint reachability (skipped in `--offline` mode) |
| 🔍 Security configuration | Validates security check settings |

### Examples

```bash
# Full health check
forge-guard doctor

# Verbose output
forge-guard doctor --verbose

# Auto-fix issues
forge-guard doctor --fix

# Check specific category
forge-guard doctor --check dependencies

# JSON output
forge-guard doctor --json

# Sync config from foundry.toml
forge-guard doctor --sync

# Preview sync changes without writing
forge-guard doctor --sync --dry-run

# Show diff of sync changes
forge-guard doctor --sync --diff
```

### Config Sync (`--sync`)

Reads `foundry.toml` and writes matching settings into `forge-guard.toml`:

- `src` → `src_dirs`
- `test` → `test_dirs`
- `libs` → `lib_dirs`
- `solc` → `solc_version`
- `remappings` → `remappings`

`--dry-run` previews changes without writing; `--diff` shows the current vs. new config side-by-side.

---

## 11. `forge-guard watch`

Watch files for changes and automatically re-audit. Configurable directory paths, debounce interval, and exclusion patterns.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--dirs <DIRS>` | `String` | `src` | Watch specific directories (comma-separated) |
| `--debounce-ms <N>` | `u64` | `500` | Debounce interval in milliseconds |
| `--exclude <PATTERNS>` | `Option<String>` | — | Exclude patterns (comma-separated) |
| `--full` | `bool` | `false` | Run full audit on change (includes exploit + gas) |

### Examples

```bash
# Watch default src directory
forge-guard watch

# Watch multiple directories
forge-guard watch --dirs src,contracts

# Custom debounce
forge-guard watch --debounce-ms 1000

# Exclude test files
forge-guard watch --exclude *.test.sol

# Run full audit on change
forge-guard watch --full
```

---

## 11b. `forge-guard dashboard`

Launch a local web dashboard that visualizes the last audit result. Serves a self-contained page with an overall score gauge, per-category score bars, severity distribution charts, a score-over-time trend chart (from the SQLite history DB, populated by `audit --enable-history`), and an interactive finding list (severity chips, text search, chain filter, expandable details). Updates live over WebSocket whenever the cached audit result changes; `--watch` re-audits on file changes and pushes the new result to connected clients.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--port <N>` | `u16` | `9090` | Port to bind the dashboard HTTP server on |
| `--host <HOST>` | `String` | `127.0.0.1` | Host interface to bind (use `0.0.0.0` to expose on your network) |
| `--watch` | `bool` | `false` | Re-audit on file changes and push updates over WebSocket |
| `--dirs <DIRS>` | `String` | `src` | Directories to watch (comma-separated, used with `--watch`) |
| `--debounce-ms <N>` | `u64` | `500` | Debounce interval in ms when `--watch` is set |
| `--open` | `bool` | `false` | Open the dashboard in the default browser |
| `--full` | `bool` | `false` | Run full audit on change (includes exploit + gas, used with `--watch`) |

### Examples

```bash
# Run an audit first, then serve the dashboard
forge-guard audit
forge-guard dashboard

# Custom port
forge-guard dashboard --port 8080

# Expose on your network
forge-guard dashboard --host 0.0.0.0

# Re-audit on file changes with live WebSocket updates
forge-guard dashboard --watch

# Watch specific directories and open the browser
forge-guard dashboard --watch --dirs src,contracts --open

# Record history for the Score Trend chart, then view it on the dashboard
forge-guard audit --enable-history
forge-guard dashboard
```

---

## 12. `forge-guard ci`

Generate CI/CD pipeline configuration files for various platforms. Creates ready-to-use workflow files.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--platform <PLATFORM>` | `String` | `github` | CI platform: `github`, `gitlab`, `bitbucket`, `azure` |
| `--output <PATH>` | `PathBuf` | `.github/workflows` | Output directory for CI configs |
| `--include-deploy` | `bool` | `false` | Include deployment pipeline |
| `--overwrite` | `bool` | `false` | Overwrite existing files |

### Examples

```bash
# Generate GitHub Actions workflow
forge-guard ci --platform github

# GitLab CI
forge-guard ci --platform gitlab

# With deployment pipeline
forge-guard ci --platform github --include-deploy

# Custom output directory
forge-guard ci --output .github/workflows

# Overwrite existing configs
forge-guard ci --overwrite
```

---

## 13. `forge-guard benchmark`

Run performance benchmarks to measure and compare analysis speed across modules.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--iterations <N>` | `u32` | `10` | Number of benchmark iterations |
| `--warmup <N>` | `u32` | `3` | Warmup iterations before measurement |
| `--compare <FILE>` | `Option<PathBuf>` | — | Compare with baseline results |
| `--save <FILE>` | `Option<PathBuf>` | — | Save benchmark results |
| `--module <NAME>` | `Option<String>` | — | Benchmark specific module (e.g., `source_discovery`) |

### Examples

```bash
# Run all benchmarks
forge-guard benchmark

# Custom iterations
forge-guard benchmark --iterations 50

# Benchmark specific module
forge-guard benchmark --module pattern_matching

# Compare with baseline
forge-guard benchmark --save results.json --compare baseline.json
```

---

## 14. `forge-guard scan`

Scan project dependencies for known vulnerabilities. Uses a 30+ entry vulnerability database covering OpenZeppelin, Solmate, Solady, Chainlink, Wormhole, LayerZero, forge-std, PRBMath, solc, and more.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--depth <N>` | `u32` | `1` | Scan depth (0=direct deps only, 1=direct + indirect, etc.) |
| `--update` | `bool` | `false` | Update vulnerability database from remote source |
| `--vulnerable-only` | `bool` | `false` | Output only packages with vulnerabilities |
| `--fail-fast` | `bool` | `false` | Fail immediately on any vulnerability |

### Examples

```bash
# Standard scan
forge-guard scan

# Deep scan (include indirect dependencies)
forge-guard scan --depth 2

# Update vulnerability database
forge-guard scan --update

# Show only vulnerable packages
forge-guard scan --vulnerable-only

# Fail on any vulnerability
forge-guard scan --fail-fast

# JSON output
forge-guard scan --json
```

---

## 15. `forge-guard upgrade-check`

Analyze upgrade paths and proxy safety. Checks storage collisions, UUPS upgrade paths, and proxy pattern correctness.

**Shared flags:** ✅

### Flags

| Argument/Flag | Type | Default | Description |
|---------------|------|---------|-------------|
| `proxy` | `Option<String>` | — | Proxy contract address |
| `implementation` | `Option<String>` | — | Implementation contract address |
| `--all` | `bool` | `false` | Check all proxies |
| `--storage-collision` | `bool` | `false` | Check storage collision between versions |
| `--uups` | `bool` | `false` | Check UUPS upgrade path |

### Examples

```bash
# Check specific proxy
forge-guard upgrade-check 0xproxy 0ximpl

# Check all proxies
forge-guard upgrade-check --all

# Storage collision analysis
forge-guard upgrade-check --storage-collision

# UUPS path check
forge-guard upgrade-check --uups
```

---

## 16. `forge-guard plugins`

Manage audit plugins. Supports listing, installing, removing, enabling, disabling, and creating plugin scaffolds. Plugins can be built-in Rust plugins or external binaries communicating via JSON IPC.

**Shared flags:** ✅

### Subcommands

| Subcommand | Description |
|------------|-------------|
| `list` | List installed plugins |
| `install <name> [source]` | Install a plugin from source (git URL or download URL) |
| `remove <name>` | Remove an installed plugin |
| `enable <name>` | Enable a plugin |
| `disable <name>` | Disable a plugin |
| `new <name>` | Create a new plugin scaffold with Rust template |

### Examples

```bash
# List installed plugins
forge-guard plugins list

# Create a new plugin scaffold
forge-guard plugins new my-custom-check

# Install from git
forge-guard plugins install my-check https://github.com/user/my-check.git

# Enable/disable
forge-guard plugins enable my-custom-check
forge-guard plugins disable my-custom-check

# Remove
forge-guard plugins remove my-custom-check
```

### Built-in Plugins

| Plugin | Version | Description |
|--------|---------|-------------|
| `forge-guard-example` | 0.1.0 | Example plugin showing the IPC protocol |
| `forge-guard-offline-guard` | 0.1.0 | Extra offline-mode security validations |

---

## 17. `forge-guard chain`

Configure chain settings. View supported chains, get chain info, add custom chains, and test RPC connectivity.

**Shared flags:** ✅

### Subcommands

| Subcommand | Description |
|------------|-------------|
| `list` | List all supported chains |
| `info <chain>` | Show details about a specific chain |
| `add <name> [rpc_url] [chain_id]` | Add a custom chain |
| `remove <name>` | Remove a custom chain |
| `test <chain> [rpc_url]` | Test chain RPC connectivity |

### Supported Chains

| Chain | Chain ID | Currency |
|-------|----------|----------|
| Ethereum | 1 | ETH |
| Base | 8453 | ETH |
| Arbitrum | 42161 | ETH |
| Optimism | 10 | ETH |
| Polygon | 137 | MATIC |
| BNB Chain | 56 | BNB |
| Avalanche | 43114 | AVAX |
| Scroll | 534352 | ETH |
| Linea | 59144 | ETH |
| Unichain | 130 | ETH |
| ZKSync | 324 | ETH |
| HyperEVM | 999 | HYPE |
| Monad | 10143 | MON |
| Sonic | 146 | S |
| Blast | 81457 | ETH |
| Mantle | 5000 | MNT |
| Robinhood | 31753 | ETH |

### Examples

```bash
# List all chains
forge-guard chain list

# Show chain info
forge-guard chain info polygon

# Add custom chain
forge-guard chain add my-chain https://rpc.my-chain.io 99999

# Remove custom chain
forge-guard chain remove my-chain

# Test RPC connectivity
forge-guard chain test ethereum
forge-guard chain test polygon https://polygon-rpc.com
```

---

## 18. `forge-guard sbom`

Generate a Software Bill of Materials (SBOM) for your Foundry project. Supported formats: CycloneDX 1.6 and SPDX 2.3.

Automatically discovers dependencies from `remappings.txt`, `foundry.toml`, and `lib/` directory. Detects solc compiler version, Foundry framework, and library versions via `package.json`, `Cargo.toml`, and git refs.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--format <FORMAT>` | `String` | `cyclonedx` | SBOM format: `cyclonedx` (or `cyc`, `cdx`) or `spdx` |
| `--output <PATH>` | `Option<PathBuf>` | — | Output file path (default: stdout) |
| `--ci` | `bool` | `false` | Also write `.github/workflows/sbom.yml` for automated SBOM publishing |

### Examples

```bash
# Generate CycloneDX SBOM (stdout)
forge-guard sbom

# SPDX format
forge-guard sbom --format spdx

# Save to file
forge-guard sbom --output sbom.json

# Format aliases work too
forge-guard sbom --format cdx

# Export a GitHub Actions workflow for supply-chain compliance
forge-guard sbom --ci
```

---

## 19. `forge-guard install-hook`

Install or uninstall a git pre-commit hook that automatically audits staged Solidity files before each commit. Blocks commits with HIGH or CRITICAL findings.

**No shared flags** — operates independently on the git repository.

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--uninstall` | `bool` | `false` | Uninstall the pre-commit hook instead of installing |
| `--force` | `bool` | `false` | Force install even if a hook already exists |
| `--project <PATH>` | `PathBuf` | `.` | Project root path |

### Hook Behavior

- **On commit**: Runs `forge-guard audit --quick` on all staged `.sol` files
- **Blocks**: Commits where any staged `.sol` file has HIGH or CRITICAL findings
- **Bypass**: Set `FORGE_GUARD_SKIP_HOOK=1` environment variable to skip the hook
- **Safety check**: Uninstall verifies the hook is a forge-guard hook before removing
- **Worktree support**: Handles `.git` file references (common in git worktrees/submodules)

### Examples

```bash
# Install pre-commit hook
forge-guard install-hook

# Force install (overwrite existing hook)
forge-guard install-hook --force

# Uninstall
forge-guard install-hook --uninstall

# Install in specific project
forge-guard install-hook --project /path/to/project
```

---

## 20. `forge-guard security`

Configure security settings. View current configuration, list all available checks, set thresholds, and enable/disable individual checks.

**Shared flags:** ✅

### Subcommands

| Subcommand | Description |
|------------|-------------|
| `config` | Show current security configuration |
| `threshold <score>` | Set minimum deployment score (0–100) |
| `enable <check>` | Enable a specific security check |
| `disable <check>` | Disable a specific security check |
| `list` | List all available security checks with severity levels |
| `info <check>` | Show detailed information about a specific check |

### Examples

```bash
# Show current config
forge-guard security config

# List all checks
forge-guard security list

# Check details
forge-guard security info Reentrancy

# Set threshold
forge-guard security threshold 85

# Enable/disable checks
forge-guard security enable "tx.origin Usage"
forge-guard security disable "Unsafe Assembly"
```

---

## 21. `forge-guard import`

Import findings from external security analyzers (Slither, Mythril, Semgrep) into Forge Guard's unified format. Tool-specific severity scales are mapped onto Forge Guard's 5-level scale, and findings can be deduplicated against Forge Guard's own audit results to produce a combined report.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--from <TOOL>` | `String` | `slither` | Analyzer to import from: `slither`, `mythril`, `semgrep` |
| `input` | `Option<PathBuf>` | — | Path to the analyzer's JSON results file |
| `--findings <FILE>` | `Option<PathBuf>` | — | Forge-guard audit JSON to deduplicate against (unified report) |
| `--output <FILE>` | `Option<PathBuf>` | — | Write the unified report (JSON) to a file |

### Severity Mapping

| Tool | Source field | Mapping |
|------|-------------|---------|
| Slither | `impact` (`High`/`Medium`/`Low`/`Informational`/`Optimization`) | → High/Medium/Low/Info |
| Mythril | `severity` or `type` | → High/Medium/Low/Info |
| Semgrep | `severity` (`ERROR`/`WARNING`/`INFO`) | → High/Medium/Low |

### Examples

```bash
# Import Slither results (terminal report)
forge-guard import --from slither slither_results.json

# Import Mythril results and deduplicate against the last forge-guard audit
forge-guard import --from mythril mythril_out.json --findings reports/audit.json

# Import Semgrep results as JSON
forge-guard import --from semgrep semgrep_results.json --json

# Write a unified report file
forge-guard import --from slither slither_results.json --findings reports/audit.json --output unified.json
```

### Supported JSON Schemas

Imported findings are tagged with a tool prefix in their ID (`SL-`, `MY-`, `SG-`), and deduplication (with `--findings`) matches on file + line + lowercase title. Only the fields below are read — anything else is ignored.

#### Slither (`slither . --json out.json`)

| Path | Used as |
|------|---------|
| `results.detectors[]` | One finding per detector |
| `.check` | Finding title & category (`slither:<check>`) |
| `.impact` | Severity (`High`/`Medium`/`Low`/`Informational`/`Optimization`) |
| `.description` | Finding description |
| `.markdown` | Recommendation |
| `.elements[0].source_mapping.filename_relative` (or `filename_absolute`) | File path |
| `.elements[0].source_mapping.line` | Line number |
| `.elements[0].source_mapping.content` | Code snippet |

```json
{
  "success": true,
  "results": {
    "detectors": [
      {
        "check": "reentrancy-eth",
        "impact": "High",
        "description": "Reentrancy in withdraw",
        "markdown": "Use checks-effects-interactions.",
        "elements": [
          {
            "type": "function",
            "name": "withdraw",
            "source_mapping": {
              "filename_relative": "contracts/Vault.sol",
              "line": 42,
              "content": "msg.sender.call{value: amount}(\"\");"
            }
          }
        ]
      }
    ]
  }
}
```

#### Mythril (`myth analyze ... -o mythril_out.json`)

| Path | Used as |
|------|---------|
| `issues[]` | One finding per issue |
| `.title` | Finding title |
| `.severity` or `.type` | Severity (`Critical`/`High`/`Medium`/`Low`) |
| `.description` | Finding description |
| `.function` | Category (`mythril:<function>`) |
| `.swc-id` | Reference (`SWC-<id>`) |
| `.source.filename` | File path |
| `.source.line` | Line number |
| `.source.source` | Code snippet |

```json
{
  "success": true,
  "issues": [
    {
      "title": "The contract executes an external call",
      "severity": "High",
      "swc-id": "107",
      "function": "withdraw",
      "source": {
        "filename": "contracts/Vault.sol",
        "line": 42,
        "source": "msg.sender.call{value: amount}(\"\");"
      }
    }
  ]
}
```

#### Semgrep (`semgrep scan --json`)

| Path | Used as |
|------|---------|
| `results[]` | One finding per result |
| `.check_id` | Category (`semgrep:<check_id>`), title fallback |
| `.extra.message` | Finding title |
| `.extra.severity` | Severity (`ERROR`/`WARNING`/`INFO`) |
| `.extra.lines` | Code snippet |
| `.extra.metadata.cwe` (array or string) | References (`CWE-...`) |
| `.path` | File path |
| `.start.line` | Line number |

```json
{
  "results": [
    {
      "check_id": "solidity.reentrancy",
      "path": "contracts/Vault.sol",
      "start": { "line": 42, "col": 1 },
      "extra": {
        "message": "External call before state update",
        "severity": "ERROR",
        "metadata": { "cwe": ["CWE-1077"] },
        "lines": "msg.sender.call{value: amount}(\"\");"
      }
    }
  ],
  "errors": []
}
```

---

## 22. `forge-guard notify`

Send audit summaries to Slack and Discord webhooks. Platform is auto-detected from the webhook URL, or set explicitly with `--kind`. Payloads include severity counts, overall score, risk level, and top findings.

> 💡 See [`examples/forge-guard.toml`](examples/forge-guard.toml) for a fully commented `[notifications.slack]` / `[notifications.discord]` configuration.

**Shared flags:** ✅

### Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--webhook <URL>` | `Option<String>` | — | Webhook URL (overrides `forge-guard.toml`) |
| `--kind <PLATFORM>` | `Option<String>` | — | Platform: `slack` or `discord` (auto-detected from URL when omitted) |
| `--findings <FILE>` | `Option<PathBuf>` | — | Forge-guard audit result JSON to summarize |
| `--title <TEXT>` | `String` | `Forge Guard Audit` | Notification title |
| `--message <TEXT>` | `Option<String>` | — | Extra free-form message text |
| `--severity <LEVEL>` | `Option<String>` | — | Minimum severity gate: `informational`, `low`, `medium`, `high`, `critical` |
| `--on-critical` | `bool` | `false` | Only notify when critical findings are present |
| `--on-high` | `bool` | `false` | Only notify when high (or higher) findings are present |
| `--dry-run` | `bool` | `false` | Print the exact payload without sending |

### Configuration

```toml
[notifications.slack]
webhook = "https://hooks.slack.com/services/T000/B000/XXXX"
min_severity = "high"

[notifications.discord]
webhook = "https://discord.com/api/webhooks/123/abc"
min_severity = "critical"
```

The `--notify` flag on `forge-guard audit`, `forge-guard deploy`, and `forge-guard deploy-safe` uses this configuration automatically. Blocked deployments always notify; successful runs respect `min_severity`.

### Examples

```bash
# Send a summarized audit result to a Slack webhook
forge-guard notify --findings reports/audit.json --webhook https://hooks.slack.com/services/T/B/X

# Discord embed, only when critical findings exist
forge-guard notify --findings reports/audit.json --on-critical

# Dry-run: print the payload without sending
forge-guard notify --findings reports/audit.json --dry-run

# Simple message
forge-guard notify --webhook https://hooks.slack.com/services/T/B/X --title "Nightly audit" --message "All checks passed"
```

---

## Appendix: Severity Levels

| Severity | Color | Blocks Deployment |
|----------|-------|-------------------|
| 🛑 Critical | Red | ✅ Yes |
| 🔴 High | Red | ✅ Yes |
| 🟡 Medium | Yellow | ❌ No (configurable) |
| 🔵 Low | Blue | ❌ No |
| ⚪ Info | White | ❌ No |

## Appendix: Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success — no findings blocking deployment |
| `1` | Failure — findings detected or command error |
| `2` | Invalid arguments |

---

*Generated from the Forge Guard codebase. For the latest updates, see the [CHANGELOG](CHANGELOG.md).*