Skip to main content

​
Installation

MergeGuide offers multiple installation methods to fit your workflow.

​
CLI Installation

npm install -g @mergeguide/cli
Verify installation: 
mergeguide --version

​
pip

pip install mergeguide

​
Homebrew (macOS)

brew tap mergeguide/tap
brew install mergeguide

​
Binary Downloads

Download pre-built binaries from the GitHub Releases page.
PlatformArchitectureDownload
macOSApple Siliconmergeguide-darwin-arm64
macOSIntelmergeguide-darwin-x64
Linuxx64mergeguide-linux-x64
Windowsx64mergeguide-windows-x64.exe

​
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
CLINode.js 18+ or Python 3.9+
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
mergeguide policies sync --offline

# Run checks offline
mergeguide check --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 EACCES errors: 
# Option 1: Use npx (no global install needed)
npx @mergeguide/cli check

# Option 2: Configure npm prefix
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @mergeguide/cli

​
SSL Certificate Errors

If behind a corporate proxy: 
# Set custom CA certificate
export NODE_EXTRA_CA_CERTS=/path/to/certificate.pem
mergeguide check

​
Version Conflicts

Check for conflicting installations: 
which mergeguide
npm list -g @mergeguide/cli
pip show mergeguide

​
Next Steps