Skip to main content

​
CLI Reference

The MergeGuide CLI provides policy checking, management, and integration capabilities.

​
Installation

npm install -g @mergeguide/cli

​
Commands

​
mergeguide check

Analyze code changes against policies. 
# Check staged changes (default)
mergeguide check

# Check specific files
mergeguide check src/api/*.ts

# Check a commit range
mergeguide check --range HEAD~3..HEAD

# Check with verbose output
mergeguide check --verbose

# Output as JSON
mergeguide check --format json

# Fail only on errors (ignore warnings)
mergeguide check --strict
Options:
OptionDescription
--stagedCheck staged changes only (default)
--allCheck all uncommitted changes
--range <range>Check specific commit range
--format <fmt>Output format: text, json, sarif
--verboseShow detailed violation info
--strictExit 1 only on failures, not warnings
--offlineUse cached policies (no network)

​
mergeguide auth

Manage authentication. 
# Login via browser
mergeguide auth login

# Login with API key
mergeguide auth login --api-key <key>

# Check auth status
mergeguide auth status

# Logout
mergeguide auth logout

​
mergeguide policies

Manage and inspect policies. 
# List available policies
mergeguide policies list

# Show policy details
mergeguide policies show <policy-id>

# Sync policies for offline use
mergeguide policies sync

# Validate local policy file
mergeguide policies validate ./my-policy.yaml

​
mergeguide config

Manage configuration. 
# Show current config
mergeguide config show

# Set organization
mergeguide config set org <org-id>

# Set default output format
mergeguide config set format json

# Initialize project config
mergeguide config init

​
mergeguide hooks

Manage Git hooks. 
# Install pre-commit hook
mergeguide hooks install

# Uninstall hooks
mergeguide hooks uninstall

# Test hook without committing
mergeguide hooks test

​
Configuration File

Create .mergeguide.yaml in your repository root: 
# Organization (optional - uses default from auth)
org: my-org

# Policy overrides
policies:
  no-hardcoded-secrets:
    enabled: true
    severity: error
  no-console-in-production:
    enabled: true
    severity: warning

# File patterns to ignore
ignore:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - "node_modules/**"
  - "dist/**"
  - ".git/**"

# Custom policy paths
custom_policies:
  - ./policies/*.yaml

# Check behavior
check:
  fail_on_warnings: false
  max_file_size: 1MB

​
Environment Variables

VariableDescription
MERGEGUIDE_API_KEYAPI key for authentication
MERGEGUIDE_ORGDefault organization ID
MERGEGUIDE_API_URLCustom API endpoint
MERGEGUIDE_CONFIGPath to config file
MERGEGUIDE_OFFLINEEnable offline mode

​
Exit Codes

CodeMeaning
0Success (all checks passed)
1Failure (policy violations found)
2Error (configuration/network issue)

​
Examples

​
CI/CD Integration

# GitHub Actions
- name: MergeGuide Check
  run: |
    npm install -g @mergeguide/cli
    mergeguide check --format sarif > results.sarif

# GitLab CI
mergeguide-check:
  script:
    - npm install -g @mergeguide/cli
    - mergeguide check --strict

​
Pre-commit Hook

#!/bin/sh
mergeguide check --staged

​
JSON Output Processing

# Check and process with jq
mergeguide check --format json | jq '.violations[] | select(.severity == "error")'

​
Troubleshooting

​
Authentication Issues

# Clear cached credentials
mergeguide auth logout
rm -rf ~/.mergeguide/credentials

# Re-authenticate
mergeguide auth login

​
Network Issues

# Check connectivity
mergeguide auth status

# Use offline mode
mergeguide policies sync
mergeguide check --offline

​
Debug Mode

# Enable debug logging
MERGEGUIDE_DEBUG=1 mergeguide check