The MergeGuide CLI ships as the Python package mergeguide and installs a single
mergeguide executable.
Requires Python 3.11 or newer. See Install the 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 | Check files against policies. |
init | One-shot first-run setup (config, auth, MCP server, hooks). |
bootstrap | Install Semgrep, install git hooks, emit MCP config. |
policies | List available policies. |
completions | Generate a shell completion script. |
doctor | Diagnose configuration and connectivity. |
login | Authenticate with the dashboard. |
install | Install or uninstall the agent PreToolUse hook. |
verify-evidence | Verify a signed evidence artifact. |
auth | Authentication subcommands (login, whoami, logout). |
config | Manage configuration. |
hooks | Manage git hooks. |
sbom | Generate a Software Bill of Materials. |
scan | Run the vulnerability and IaC scanners. |
mergeguide check
Check files against policies.
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. |
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.
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.ai). |
--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.
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.
mergeguide completions
Generate a shell completion script for bash, zsh, or fish.
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.
mergeguide login
Authenticate with the dashboard. This is a top-level alias for
mergeguide auth login.
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.
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.
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. |
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. |
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). |
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. |
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. |
| 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.
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.
