CLI reference

The MergeGuide CLI ships as the Python package mergeguide and installs a single mergeguide executable.

pip install mergeguide

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.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.

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 policies

`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 doctor

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.

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.

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.

Get started

Provisioning & account

Setup & installation

Configuration

Operation

Navigation

Integrations & CI/CD

Compliance

Methodology

Troubleshooting & FAQ

Reference

Global options

Command overview

`mergeguide check`

`mergeguide init`

`mergeguide bootstrap`

`mergeguide policies`

`mergeguide completions`

`mergeguide doctor`

`mergeguide install`

`mergeguide verify-evidence`

`mergeguide auth`

`mergeguide config`

`mergeguide hooks`

`mergeguide sbom`

`mergeguide scan`

Exit codes

​Global options

​Command overview

​mergeguide check

​mergeguide init

​mergeguide bootstrap

​mergeguide policies

​mergeguide completions

​mergeguide doctor

​mergeguide login

​mergeguide install

​mergeguide verify-evidence

​mergeguide auth

​mergeguide config

​mergeguide hooks

​mergeguide sbom

​mergeguide scan

​Exit codes

Global options

Command overview

`mergeguide check`

`mergeguide init`

`mergeguide bootstrap`

`mergeguide policies`

`mergeguide completions`

`mergeguide doctor`

`mergeguide login`

`mergeguide install`

`mergeguide verify-evidence`

`mergeguide auth`

`mergeguide config`

`mergeguide hooks`

`mergeguide sbom`

`mergeguide scan`

Exit codes