CLI Reference

Complete reference for the MergeGuide command-line interface

CLI Reference

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

Installation

pip install mergeguide

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

# Check with verbose output
mergeguide check --verbose

# Output as JSON
mergeguide check --format json

# Fail only on errors (ignore warnings)

Options:

Option	Description
--staged	Check staged changes only (default)
--all	Check all uncommitted changes
--format <fmt>	Output format: text, json, sarif
--verbose	Show detailed violation info

mergeguide auth

Manage authentication.

# Login via browser
mergeguide login

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

# Check auth status
mergeguide config list

# Logout
mergeguide login --clear

mergeguide policies

Manage and inspect policies.

# List available policies
mergeguide policies

# Show policy details
mergeguide policies  # List all active policies

# Sync policies for offline use
mergeguide policies  # Policies are synced automatically

# Validate local policy file
mergeguide check --policy ./my-policy.yaml  # Validate a custom policy

mergeguide config

Manage configuration.

# Show current config
mergeguide config list

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

# Set default output format
mergeguide config set format json

# Initialize project config
mergeguide init

mergeguide hooks

Manage Git hooks.

# Install pre-commit hook
mergeguide hooks install

# Uninstall hooks
mergeguide hooks uninstall

# Test hook without committing
mergeguide check --staged  # Test hook behavior

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

Variable	Description
MERGEGUIDE_API_KEY	API key for authentication
MERGEGUIDE_ORG	Default organization ID
MERGEGUIDE_API_URL	Custom API endpoint
MERGEGUIDE_CONFIG	Path to config file
MERGEGUIDE_OFFLINE	Enable offline mode

Exit Codes

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

Examples

CI/CD Integration

# GitHub Actions
- name: MergeGuide Check
  run: |
    pip install mergeguide
    mergeguide check --format sarif > results.sarif

# GitLab CI
mergeguide-check:
  script:
    - pip install mergeguide

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 login --clear
rm -rf ~/.mergeguide/credentials

# Re-authenticate
mergeguide login

Network Issues

# Check connectivity
mergeguide config list

# Use offline mode
mergeguide policies  # Policies are synced automatically

Debug Mode

# Enable debug logging
MERGEGUIDE_DEBUG=1 mergeguide check