Installation

Detailed installation instructions for all MergeGuide components

Installation

MergeGuide offers multiple installation methods to fit your workflow.

CLI Installation

pip (Recommended)

pip install mergeguide

Or with pipx for isolated CLI installation:

pipx install mergeguide

Verify installation:

mergeguide --version

Requires Python 3.11+. For best results, install Semgrep alongside MergeGuide for full dual-layer scanning (regex + AST analysis).

VS Code Extension

Install from the VS Code Marketplace:

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
3. Search for “MergeGuide”
4. Click Install

Or install via command line:

code --install-extension mergeguide.mergeguide-vscode

MCP Server

For AI coding assistants (Claude, Cursor, etc.):

npm install -g @mergeguide/mcp-server

See MCP Server Guide for configuration.

System Requirements

Component	Requirements
CLI	Python 3.11+
VS Code Extension	VS Code 1.85+
MCP Server	Node.js 18+

Network Requirements

MergeGuide requires outbound HTTPS access to:

• api.mergeguide.ai - API endpoints
• auth.mergeguide.ai - Authentication
• portal.mergeguide.ai - Dashboard (optional)

Offline Mode

For air-gapped environments, MergeGuide supports offline policy evaluation:

# Download policies for offline use

# Run checks offline

Note: Offline mode requires policies to be pre-synced and does not support real-time policy updates.

Troubleshooting Installation

Permission Errors (npm)

If you encounter permission errors:

# Option 1: Use pipx (recommended — installs in isolated environment)
pipx install mergeguide

# Option 2: Install with --user flag
pip install --user mergeguide

SSL Certificate Errors

If behind a corporate proxy:

# Set custom CA certificate
export REQUESTS_CA_BUNDLE=/path/to/certificate.pem
mergeguide check

Version Conflicts

Check your installation:

which mergeguide
pip show mergeguide
mergeguide --version

Next Steps

• Run Your First Check
• Configure Authentication