Skip to main content

​
Installation

MergeGuide offers multiple installation methods to fit your workflow.

​
CLI Installation

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

ComponentRequirements
CLIPython 3.11+
VS Code ExtensionVS Code 1.85+
MCP ServerNode.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