> ## Documentation Index > Fetch the complete documentation index at: https://docs.mergeguide.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Complete reference for the MergeGuide command-line interface — every command, group, and flag. The MergeGuide CLI ships as the Python package `mergeguide` and installs a single `mergeguide` executable. ```bash theme={null} pip install mergeguide ``` Requires Python 3.11 or newer. See [Install the CLI](/install/cli) for details. ## Global options These apply to `mergeguide` before any subcommand: | Option | Description | | ----------------- | ------------------------------------------------- | | `-q`, `--quiet` | Minimal output — only violations and errors. | | `-v`, `--verbose` | Debug output (cache status, timing, and similar). | | `--version` | Print the version and exit. | | `--help` | Show help for the command and exit. | ## Command overview The CLI has nine top-level commands and five command groups: | Command | What it does | | ------------------------------------------------ | ----------------------------------------------------------- | | [`check`](#mergeguide-check) | Check files against policies. | | [`init`](#mergeguide-init) | One-shot first-run setup (config, auth, MCP server, hooks). | | [`bootstrap`](#mergeguide-bootstrap) | Install Semgrep, install git hooks, emit MCP config. | | [`policies`](#mergeguide-policies) | List available policies. | | [`completions`](#mergeguide-completions) | Generate a shell completion script. | | [`doctor`](#mergeguide-doctor) | Diagnose configuration and connectivity. | | [`login`](#mergeguide-login) | Authenticate with the dashboard. | | [`install`](#mergeguide-install) | Install or uninstall the agent PreToolUse hook. | | [`verify-evidence`](#mergeguide-verify-evidence) | Verify a signed evidence artifact. | | [`auth`](#mergeguide-auth) | Authentication subcommands (login, whoami, logout). | | [`config`](#mergeguide-config) | Manage configuration. | | [`hooks`](#mergeguide-hooks) | Manage git hooks. | | [`sbom`](#mergeguide-sbom) | Generate a Software Bill of Materials. | | [`scan`](#mergeguide-scan) | Run the vulnerability and IaC scanners. | *** ## `mergeguide check` Check files against policies. ```bash theme={null} mergeguide check [OPTIONS] [PATHS]... ``` `PATHS` are files or directories to check. With no paths, `check` reads git-staged changes (or from stdin). | Option | Description | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-f`, `--format [text\|json\|sarif\|markdown]` | Output format. | | `-o`, `--output PATH` | Write output to a file. | | `-p`, `--policy PATH` | Additional policy file(s) to use. | | `--no-defaults` | Don't use the default policies. | | `--fail-on-warning` | Exit with an error if warnings are found. | | `--staged` | Check only git-staged files (for pre-commit hooks). | | `--hook-mode` | Concise output for git hooks (no spinner). | | `--advisory` | Report findings but always exit 0 (never block). | | `--no-semgrep` | Disable Semgrep scanning. | | `--semgrep-timeout INTEGER` | Semgrep scan timeout in seconds (default 300). | | `--local` | Run locally without submitting results to the dashboard. | | `--show-low-confidence` | Show low-confidence findings in text output. | | `--tier [free\|team\|enterprise]` | Organization tier used for absence-of-controls gating (default `free`). | | `--frameworks TEXT` | Comma-separated framework IDs to scope the default rule corpus to (for example `soc2-type2,pci-dss-v4`). When supplied, only rules mapped to at least one of these frameworks fire. | ```bash theme={null} mergeguide check src/ --format json mergeguide check --staged --fail-on-warning mergeguide check src/ --frameworks soc2-type2,pci-dss-v4 ``` ## `mergeguide init` One-shot first-run orchestrator. After `pip install mergeguide`, run `init` to preflight your environment, write config, authenticate, install the MCP server via `npx`, register it in your project's `.mcp.json`, and install git hooks. Every step is idempotent. ```bash theme={null} mergeguide init [OPTIONS] ``` | Option | Description | | ------------------------------------ | ----------------------------------------------------------- | | `--global` | Initialize globally in `~/.mergeguide` (config scope only). | | `--api-key TEXT` | API key for authentication; prompts if omitted. | | `--api-url TEXT` | Dashboard URL (default `https://portal.mergeguide.com`). | | `--skip-auth` | Config only — skip the dashboard auth step. | | `--skip-mcp-server` | Skip installing the `@mergeguide/mcp-server` npm package. | | `--skip-agent-hook` | Skip installing the agent PreToolUse hook. | | `--skip-git-hooks` | Skip installing git hooks. | | `--agent-hook-scope [user\|project]` | PreToolUse hook scope (default `user`). | | `--force` | Overwrite non-MergeGuide hook entries. | ## `mergeguide bootstrap` Install Semgrep, install git hooks, and emit MCP config in one step. Each step is best-effort and idempotent. ```bash theme={null} mergeguide bootstrap [OPTIONS] ``` | Option | Description | | ------------------------- | ------------------------------------------ | | `--skip-semgrep` | Skip the Semgrep install step. | | `--skip-hooks` | Skip the git hooks install step. | | `--write-mcp-config FILE` | Write the MCP config snippet to this path. | ## `mergeguide policies` List the policies available to you. ```bash theme={null} mergeguide policies ``` ## `mergeguide completions` Generate a shell completion script for `bash`, `zsh`, or `fish`. ```bash theme={null} mergeguide completions bash >> ~/.bashrc mergeguide completions zsh >> ~/.zshrc mergeguide completions fish > ~/.config/fish/completions/mergeguide.fish ``` ## `mergeguide doctor` Diagnose MergeGuide configuration and connectivity. Run this first when something isn't working. ```bash theme={null} mergeguide doctor ``` ## `mergeguide login` Authenticate with the dashboard. This is a top-level alias for [`mergeguide auth login`](#mergeguide-auth). ```bash theme={null} mergeguide login [OPTIONS] ``` | Option | Description | | ---------------- | -------------------------------------------------------------- | | `--api-key TEXT` | API key for authentication (alternative to interactive login). | | `--api-url TEXT` | Dashboard URL. | ## `mergeguide install` Install or uninstall the MergeGuide PreToolUse hook for an AI agent runtime. ```bash theme={null} mergeguide install --agent-hook [claude-code|cursor|codex-cli|copilot-chat|all] [OPTIONS] ``` | Option | Description | | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `--agent-hook [claude-code\|cursor\|codex-cli\|codex\|copilot-chat\|copilot\|all]` | Runtime to install the hook for (required). `all` installs for every detected runtime. | | `--uninstall` | Symmetrically uninstall the agent hook. | | `--scope [project\|user]` | Install scope (default `project`). | | `--force` | Replace an existing entry even on marker drift. | ## `mergeguide verify-evidence` Verify a signed MergeGuide evidence artifact. Exits 0 if valid, 1 if invalid/tampered, 2 if malformed, and 3 if a required network step was unreachable. ```bash theme={null} mergeguide verify-evidence [OPTIONS] ARTIFACT ``` | Option | Description | | ---------------------------------------- | ----------------------------------------------------------------- | | `--json` | Emit machine-readable JSON. | | `--skip-transparency` | Skip live transparency-log re-verification (air-gapped use only). | | `--rekor-url TEXT` | Override the transparency-log base URL. | | `--public-key-source [bundle\|endpoint]` | Where to source the public key (default `bundle`, fully offline). | | `--dashboard-url TEXT` | Dashboard base URL, used with `--public-key-source=endpoint`. | | `--key-cache-dir DIRECTORY` | Public-key cache directory. | | `--timeout FLOAT` | Per-request timeout in seconds (default 8.0). | *** ## `mergeguide auth` Authentication subcommands. | Subcommand | Description | | ------------- | ------------------------------------------ | | `auth login` | Authenticate with the dashboard. | | `auth whoami` | Show the currently authenticated identity. | | `auth logout` | Clear local credentials. | ```bash theme={null} mergeguide auth login --api-key mg_xxxxxxxxxxxxxxxx mergeguide auth whoami mergeguide auth logout ``` ## `mergeguide config` Manage MergeGuide configuration. | Subcommand | Description | | -------------- | --------------------------------- | | `config list` | List current configuration. | | `config get` | Get a configuration value. | | `config set` | Set a configuration value. | | `config unset` | Remove a configuration value. | | `config path` | Show the configuration file path. | ```bash theme={null} mergeguide config list mergeguide config set org acme-corp mergeguide config path ``` ## `mergeguide hooks` Manage git hooks for local policy enforcement. | Subcommand | Description | | ------------------------ | ---------------------------------------------------------------- | | `hooks install` | Install MergeGuide git hooks (single repo or fleet via `--all`). | | `hooks uninstall` | Remove MergeGuide git hooks. | | `hooks status` | Show the status of installed hooks. | | `hooks check-commit-msg` | Validate a commit message file. | | `hooks bypasses` | Show the audit log of hook bypasses. | `hooks install` options: | Option | Description | | ------------------------------------------------------------------ | -------------------------------------------------------- | | `--force` | Overwrite existing hooks. | | `--hook-type [all\|pre-commit\|pre-push\|commit-msg\|post-commit]` | Hook type to install. | | `--all DIRECTORY` | Fleet install across every git repo under a root. | | `--dry-run` | With `--all`, report what would be done without writing. | | `--max-depth INTEGER` | With `--all`, max recursion depth (default 5). | ```bash theme={null} mergeguide hooks install --hook-type pre-commit mergeguide hooks status ``` ## `mergeguide sbom` Generate a Software Bill of Materials from your dependency manifests. | Subcommand | Description | | --------------- | --------------------------------------- | | `sbom generate` | Generate an SBOM from manifest files. | | `sbom formats` | List the supported SBOM output formats. | `sbom generate` options: | Option | Description | | --------------------------------------------------------------------------- | ----------------------------------------- | | `-f`, `--format [cyclonedx-json\|cyclonedx-xml\|spdx-json\|spdx-tag-value]` | Output format (default `cyclonedx-json`). | | `-o`, `--output PATH` | Write to a file (default stdout). | | `-n`, `--name TEXT` | Project/component name. | | `--version TEXT` | Project/component version. | | `-d`, `--description TEXT` | Project description. | | `--include-dev` | Include dev dependencies. | ```bash theme={null} mergeguide sbom generate . --format spdx-json -o sbom.json mergeguide sbom formats ``` ## `mergeguide scan` Run the specialized security scanners. | Subcommand | Description | | ----------- | -------------------------------------------------------- | | `scan vuln` | Scan manifest files for known vulnerabilities (OSV). | | `scan iac` | Scan infrastructure-as-code files for misconfigurations. | Both subcommands share these options: | Option | Description | | ------------------------------------ | -------------------------------------------------- | | `-p`, `--path PATH` | Directory to scan (default current directory). | | `-f`, `--format [text\|json\|sarif]` | Output format (default `text`). | | `--fail-on [none\|high\|critical]` | Exit 1 at this severity or above (default `none`). | `scan iac` supports Terraform, CloudFormation, Kubernetes, and Helm. ```bash theme={null} mergeguide scan vuln --path ./my-project --fail-on critical mergeguide scan iac main.tf --format sarif ``` ## Exit codes | Code | Meaning | | ---- | ----------------------------------- | | `0` | Success — no blocking findings. | | `1` | Policy violations found. | | `2` | Configuration or environment error. | `verify-evidence` and the `scan` subcommands use their own exit-code conventions — see each command above.