> ## Documentation Index
> Fetch the complete documentation index at: https://jonathansantilli-codegate-92.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# scan

> Scan a directory, file, or URL target for AI tool configuration risks. Runs Layers 1–2 (offline, deterministic) by default, with optional Layer 3 deep scan.

`codegate scan [target]` runs the multi-layer analysis pipeline against a target and reports findings. Layers 1 and 2 are offline-first and deterministic. Layer 3 deep scan is opt-in with `--deep`.

<Note>
  Layers 1 and 2 never make network calls. The scan target is inspected locally against the static knowledge base. Layer 3 (`--deep`) is the only mode that may fetch remote metadata or invoke a local AI agent.
</Note>

## Scan targets

The `[target]` argument accepts:

* **Directory** — scans all discovered AI tool config files under the directory (default: `.`)
* **File** — scans a single config file directly
* **URL** — clones or fetches the remote resource and scans the result; use `--skill` to select a single skill from a multi-skill index repo

```bash theme={null}
codegate scan .
codegate scan ./path/to/project
codegate scan ~/.config/claude/claude_desktop_config.json
codegate scan https://github.com/owner/repo --skill security-review
```

## Flags

<ParamField path="--deep" type="boolean" default="false">
  Enable Layer 3 dynamic analysis. Discovers eligible external resources and local instruction files, prompts for per-resource consent, and optionally invokes a local AI meta-agent (Claude Code, Codex CLI, or OpenCode) for deeper inspection. No network calls are made without explicit consent.
</ParamField>

<ParamField path="--remediate" type="boolean" default="false">
  Enter remediation mode after the scan completes. Guides you through available fixes interactively. Backups are written to `.codegate-backup/` before any file is modified.
</ParamField>

<ParamField path="--fix-safe" type="boolean" default="false">
  Automatically apply fixes for unambiguous critical findings without interactive prompts. Use with `--dry-run` to preview what would change.
</ParamField>

<ParamField path="--dry-run" type="boolean" default="false">
  Show proposed remediation changes without writing anything to disk.
</ParamField>

<ParamField path="--patch" type="boolean" default="false">
  Generate patch-style output for proposed fixes, suitable for review workflows.
</ParamField>

<ParamField path="--no-tui" type="boolean" default="false">
  Disable the TUI dashboard and interactive prompts. Use this flag in CI or when piping output.
</ParamField>

<ParamField path="--format" type="string" default="terminal">
  Output format. Valid values: `terminal`, `json`, `sarif`, `markdown`, `html`.

  `sarif` output is designed for GitHub Code Scanning and other security tooling.
</ParamField>

<ParamField path="--output" type="string">
  Write the report to a file path instead of stdout.
</ParamField>

<ParamField path="--verbose" type="boolean" default="false">
  Show extended output in `terminal` format. Has no effect on other output formats.
</ParamField>

<ParamField path="--config" type="string">
  Path to a specific global config file. Overrides the default `~/.codegate/config.json` location.
</ParamField>

<ParamField path="--force" type="boolean" default="false">
  Skip interactive confirmations, including deep scan consent prompts and remediation consent. In non-interactive or CI environments, deep scan actions are skipped unless `--force` is provided.
</ParamField>

<ParamField path="--include-user-scope" type="boolean" default="false">
  Force-include user/home AI tool config paths for this run. Useful when the config file has `scan_user_scope: false` but you want a one-off full scan.
</ParamField>

<ParamField path="--collect" type="string">
  Collection scope mode. Valid values: `default`, `project`, `user`, `explicit`, `all`. The flag is repeatable to combine modes.
</ParamField>

<ParamField path="--collect-kind" type="string">
  Restrict collection to specific artifact kinds. Valid values: `workflows`, `actions`, `dependabot`. The flag is repeatable.
</ParamField>

<ParamField path="--strict-collection" type="boolean" default="false">
  Treat parse failures in collected inputs as high-severity findings instead of warnings.
</ParamField>

<ParamField path="--persona" type="string" default="regular">
  Audit sensitivity level. Valid values: `regular`, `pedantic`, `auditor`.
</ParamField>

<ParamField path="--runtime-mode" type="string" default="offline">
  Runtime mode for optional online audits. Valid values: `offline`, `online`, `online-no-audits`.
</ParamField>

<ParamField path="--workflow-audits" type="boolean" default="false">
  Enable the CI/CD audit pack for GitHub Actions workflows, actions, and Dependabot inputs. Checks include unpinned action references, high-risk triggers, overly broad permissions, template expression injection, and known vulnerable action references (online mode only).
</ParamField>

<ParamField path="--skill" type="string">
  Select one skill directory when scanning a skills-index repo URL that contains multiple skills.
</ParamField>

<ParamField path="--reset-state" type="boolean" default="false">
  Clear the persisted scan-state baseline file (`~/.codegate/scan-state.json`) and exit immediately. Use this to reset rug-pull detection history.
</ParamField>

## Examples

```bash theme={null}
# Basic scan of the current directory
codegate scan .

# Output as JSON to stdout
codegate scan . --format json

# Output as SARIF to a file (for GitHub Code Scanning)
codegate scan . --format sarif --output codegate.sarif

# Enable Layer 3 deep scan
codegate scan . --deep

# Deep scan including user/home config surfaces
codegate scan . --deep --include-user-scope

# Deep scan skipping consent prompts
codegate scan . --deep --force

# Enter guided remediation after scan
codegate scan . --remediate

# Auto-fix unambiguous critical findings
codegate scan . --fix-safe

# Preview remediation changes and generate a patch
codegate scan . --remediate --dry-run --patch

# Workflow audit pack with project scope, auditor persona, and online mode
codegate scan . --workflow-audits --collect project --persona auditor --runtime-mode online

# Workflow audit pack restricted to workflow files only
codegate scan . --workflow-audits --collect project --collect-kind workflows

# Treat collection parse failures as high-severity findings
codegate scan . --workflow-audits --strict-collection

# Scan a remote URL and select a specific skill
codegate scan https://github.com/owner/repo --skill security-review

# Reset scan-state baseline and exit
codegate scan . --reset-state
```

## Exit codes

| Code | Meaning                                                |
| ---- | ------------------------------------------------------ |
| `0`  | No unsuppressed findings                               |
| `1`  | Findings exist below the configured severity threshold |
| `2`  | Findings at or above the configured severity threshold |
| `3`  | Scanner or runtime error                               |