CLI Reference

MergeWhy CLI

Record change evidence from any CI/CD pipeline. 35+ commands for attestations, artifacts, environments, deployments, compliance gates, drift detection, AI queries, and more. Now live on npm as mergewhy.

Installation Quick Start Commands CI Integration Environment Variables JSON Output Config File

Installation

npm (recommended)

npm install -g mergewhy

npx (no install)

npx mergewhy attest --type TEST_RESULTS --name "Unit Tests" --passed

Homebrew (coming soon)

brew install mergewhy/tap/mergewhy

Requires Node.js 18 or later. Zero runtime dependencies. 164 KB bundle.

Quick Start

Three commands to start recording change evidence:

1. Set your API key

export MERGEWHY_API_KEY="mw_your_api_key_here"
# Generate at: https://mergewhy.com/dashboard/settings

2. Record test results

mergewhy attest junit --results-dir ./test-reports --name "Unit Tests"

3. Gate your deployment

mergewhy gate --environment production --min-score 80 && ./deploy.sh

When running in CI (GitHub Actions, GitLab CI, Jenkins, etc.), repository, commit SHA, branch, and PR number are auto-detected.

Commands

Attestations

mergewhy attest

Record a generic attestation with type, name, and pass/fail status.

mergewhy attest --type TEST_RESULTS --name "Unit Tests" --passed
mergewhy attest --type SECURITY_SCAN --name "Trivy" --failed --evidence '{"vulns": 3}'

mergewhy attest junit

Parse JUnit XML test results and submit as a TEST_RESULTS attestation. Recursively finds all .xml files.

mergewhy attest junit --results-dir ./test-reports
mergewhy attest junit --results-dir ./build/reports --name "Integration Tests"

mergewhy attest snyk

Parse Snyk JSON or SARIF security scan results. Fails on critical/high vulnerabilities by default.

snyk test --json > snyk.json && mergewhy attest snyk --scan-results snyk.json
mergewhy attest snyk --scan-results snyk.sarif --fail-on critical

mergewhy attest sonar

Fetch SonarQube quality gate status and metrics. Passes if gate status is OK.

mergewhy attest sonar --sonar-url https://sonar.company.com --sonar-token $SONAR_TOKEN --project-key my-service

mergewhy attest jira

Extract Jira issue keys from git commits/branches, verify they exist in Jira.

mergewhy attest jira --jira-url https://myorg.atlassian.net --jira-email me@co.com --jira-token $JIRA_TOKEN

mergewhy attest pullrequest

Verify a pull request exists for the current commit. Supports GitHub, GitLab, Bitbucket, Azure DevOps.

mergewhy attest pullrequest github --github-token $GITHUB_TOKEN
mergewhy attest pullrequest gitlab --gitlab-token $GITLAB_TOKEN

mergewhy attest test

Auto-detect JUnit XML test results in common directories, or manually record pass/fail. Zero config — just run it after your tests.

mergewhy attest test
mergewhy attest test --dir ./build/test-results
mergewhy attest test --passed --name "Unit Tests"

mergewhy attest security

Auto-detect security scan results from Snyk, Trivy, Semgrep, or CodeQL (JSON and SARIF formats). Fails on critical/high findings.

mergewhy attest security
mergewhy attest security --file trivy-report.json
mergewhy attest security --passed --name "Container Scan"

mergewhy attest custom

Record a custom-typed attestation with arbitrary evidence data from a JSON file.

mergewhy attest custom --type perf-test --data results.json --passed
mergewhy attest custom --type license-check --evidence '{"approved": true}'

Artifacts

mergewhy artifact

Record a build artifact with its SHA-256 fingerprint for provenance tracking.

mergewhy artifact --name "api-server" --sha256 $(sha256sum dist/app.jar | cut -d' ' -f1)
mergewhy artifact --name "web" --sha256 abc123... --type docker --tag v1.2.3

mergewhy fingerprint

Calculate SHA-256 fingerprint of a file or directory. Deterministic hashing for reproducibility.

mergewhy fingerprint file ./build/app.jar
mergewhy fingerprint dir ./dist

mergewhy allow

Allowlist a third-party artifact for environment compliance. Requires a reason.

mergewhy allow --artifact-sha256 abc... --environment production --reason "Vendor image"
mergewhy allow list --environment production
mergewhy allow remove --artifact-sha256 abc... --environment production

Environments

mergewhy snapshot

Capture a runtime environment snapshot. Supports Docker, Kubernetes, ECS, Lambda, S3, Azure, filesystem paths.

mergewhy snapshot docker --environment production
mergewhy snapshot kubernetes --environment staging --namespace default
mergewhy snapshot path --path /opt/myapp --exclude "*.log"

mergewhy environment

Manage environments: create, list, view deployment log, diff snapshots.

mergewhy environment create --name production --type k8s
mergewhy environment list
mergewhy environment log --name production --limit 20
mergewhy environment diff --name prod --from snap_1 --to snap_2

Deployments & Gates

mergewhy deploy

Record a deployment event. Status defaults to SUCCESS. Supports artifact linking.

mergewhy deploy --environment production --repo owner/repo --commit abc123
mergewhy deploy --environment staging --status failure --artifact-sha256 abc...

mergewhy gate

Check deployment gate. Exits 0 if evidence score meets threshold, exits 1 if not. Use in CI to block deploys.

mergewhy gate --environment production --min-score 80 && ./deploy.sh
mergewhy gate --env staging --min-score 60

mergewhy approve

Approval workflow: request approval, record decisions, check status before deploying.

mergewhy approve request --artifact-sha256 abc... --environment production
mergewhy approve report --artifact-sha256 abc... --environment production --approver "cto@co.com"
mergewhy approve check --artifact-sha256 abc... --environment production && deploy.sh

mergewhy expect

Pre-announce a deployment so MergeWhy can track whether it actually occurs.

mergewhy expect --environment production --artifact-sha256 abc...
mergewhy expect --environment staging --artifact-sha256 abc... --description "Release v2.1"

Pipelines, Flows & Trails

mergewhy pipeline

Record a CI/CD pipeline run with name, status, duration, and optional steps.

mergewhy pipeline --name "Build & Test" --status success --duration 120
mergewhy pipeline --name "Deploy" --status failure --url https://ci.example.com/123

mergewhy flow

Manage delivery flows (software delivery pipelines). Create, list, get details.

mergewhy flow create --name "Payment Service" --description "Core payments"
mergewhy flow list
mergewhy flow get --name "Payment Service"

mergewhy trail

Track end-to-end delivery trails. Create trails, add attestations, mark complete.

mergewhy trail create --name "Release v2.1" --repo owner/repo
mergewhy trail attest --trail-id abc123 --type TEST_RESULTS --name "E2E" --passed
mergewhy trail complete --trail-id abc123

Assertions & Compliance

mergewhy assert

Assert compliance. Exit 0 = compliant, exit 1 = not. Use as CI gate.

mergewhy assert artifact --sha256 abc... --environment production
mergewhy assert snapshot --environment production
mergewhy assert pullrequest github --repository owner/repo --commit abc123
mergewhy assert approval --sha256 abc... --environment production

mergewhy evaluate

Evaluate trail compliance against flow template requirements.

mergewhy evaluate trail --flow "Payment Service"
mergewhy evaluate trail --flow "Payment Service" --trail "Release v2.1"

mergewhy search

Search for artifacts, DERs, or attestations by SHA-256 fingerprint or commit SHA.

mergewhy search --fingerprint a1b2c3d4...
mergewhy search --commit abc123 --type attestation

mergewhy status

Show comprehensive compliance status for a repo or commit. Combines search + gate. Exits 1 if gate fails.

mergewhy status --repo owner/repo --commit abc123
mergewhy status --repo owner/repo --min-score 80

mergewhy ask

Ask a natural-language question about change evidence. Powered by AI analysis of your compliance data.

mergewhy ask "what changed in production last week?"
mergewhy ask "which PRs are missing security scans?" --repo owner/repo

mergewhy drift

Detect drift between expected and actual environment state. Exits 1 if drift detected.

mergewhy drift --environment production
mergewhy drift --environment staging --repo owner/repo

Resource Management

mergewhy get

Get details of a resource. Subcommands: artifact, flow, trail, approval, environment.

mergewhy get artifact --sha256 a1b2c3...
mergewhy get flow --name "Payment Service"
mergewhy get environment --name production

mergewhy list

List resources with filtering and pagination. Subcommands: artifacts, flows, trails, approvals, environments, attestation-types.

mergewhy list artifacts --repo owner/repo --limit 20
mergewhy list flows
mergewhy list environments

mergewhy attestation-type

Manage custom attestation type schemas. Define your own evidence types.

mergewhy attestation-type create --name "perf-test" --schema schema.json
mergewhy attestation-type list

mergewhy archive

Archive flows or environments. Requires --force or interactive confirmation.

mergewhy archive flow --name "Old Service" --force
mergewhy archive environment --name legacy-staging

mergewhy rename

Rename flows or environments.

mergewhy rename flow --name "Old Name" --new-name "New Name"
mergewhy rename environment --name staging --new-name staging-v2

CI Integration

The CLI auto-detects 9 CI providers and populates repository, commit, branch, and PR number automatically.

GitHub Actions

.github/workflows/ci.yml

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npm test -- --reporter=junit --outputFile=test-results.xml

      # Record test results
      - run: npx mergewhy attest junit --results-dir ./ --name "Unit Tests"
        env:
          MERGEWHY_API_KEY: ${{ secrets.MERGEWHY_API_KEY }}

      # Run security scan
      - run: npx snyk test --json > snyk.json || true
      - run: npx mergewhy attest snyk --scan-results snyk.json
        env:
          MERGEWHY_API_KEY: ${{ secrets.MERGEWHY_API_KEY }}

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4

      # Gate deployment on evidence score
      - run: npx mergewhy gate --environment production --min-score 80
        env:
          MERGEWHY_API_KEY: ${{ secrets.MERGEWHY_API_KEY }}

      - run: ./deploy.sh

      # Record deployment
      - run: npx mergewhy deploy --environment production
        env:
          MERGEWHY_API_KEY: ${{ secrets.MERGEWHY_API_KEY }}

GitLab CI

.gitlab-ci.yml

stages:
  - test
  - deploy

test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test -- --reporter=junit --outputFile=test-results.xml
    - npx mergewhy attest junit --results-dir ./ --name "Unit Tests"
  variables:
    MERGEWHY_API_KEY: $MERGEWHY_API_KEY

deploy:
  stage: deploy
  image: node:20
  script:
    - npx mergewhy gate --environment production --min-score 80
    - ./deploy.sh
    - npx mergewhy deploy --environment production
  variables:
    MERGEWHY_API_KEY: $MERGEWHY_API_KEY
  only:
    - main

Jenkins

Jenkinsfile

pipeline {
  agent any
  environment {
    MERGEWHY_API_KEY = credentials('mergewhy-api-key')
  }
  stages {
    stage('Test') {
      steps {
        sh 'npm ci && npm test'
        sh 'npx mergewhy attest junit --results-dir ./test-reports'
      }
    }
    stage('Gate') {
      steps {
        sh 'npx mergewhy gate --environment production --min-score 80'
      }
    }
    stage('Deploy') {
      steps {
        sh './deploy.sh'
        sh 'npx mergewhy deploy --environment production'
      }
    }
  }
}

Supported CI Providers

GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, Bitbucket Pipelines, TeamCity, Travis CI, and AWS CodeBuild. When running in any of these environments, --repo, --commit, --branch, and --pr are auto-populated from environment variables.

Environment Variables

Variable	Required	Description
MERGEWHY_API_KEY	Yes	API key for authentication. Generate at `/dashboard/settings`
MERGEWHY_API_URL	No	API base URL. Defaults to `https://mergewhy.com`. Set for self-hosted instances.
GITHUB_TOKEN	No	Used by `attest pullrequest github`. Auto-available in GitHub Actions.
GITLAB_TOKEN	No	Used by `attest pullrequest gitlab`.
SONAR_URL	No	SonarQube server URL for `attest sonar`.
SONAR_TOKEN	No	SonarQube authentication token.
JIRA_URL	No	Jira instance URL for `attest jira`.
JIRA_EMAIL / JIRA_TOKEN	No	Jira credentials for issue verification.

JSON Output

All commands support machine-readable JSON output for scripting and CI integration:

mergewhy gate --environment production --min-score 80 --output json
mergewhy search --commit abc123 --output json
mergewhy status --repo owner/repo --output json

Config File

Create a .mergewhy.json in your repository root to set defaults for all CLI commands:

.mergewhy.json

{
  "apiUrl": "https://mergewhy.com",
  "defaultEnvironment": "production",
  "gate": {
    "minScore": 80,
    "requiredAttestations": ["TEST_RESULTS", "SECURITY_SCAN"]
  },
  "attest": {
    "junit": {
      "resultsDir": "./test-reports",
      "name": "Unit Tests"
    },
    "snyk": {
      "failOn": "critical"
    }
  },
  "deploy": {
    "environments": {
      "production": {
        "requireApproval": true,
        "minScore": 90
      },
      "staging": {
        "minScore": 60
      }
    }
  }
}

CLI flags always override config file values. The API key is never stored in the config file — always use the MERGEWHY_API_KEY environment variable.

Additional Commands

mergewhy --version — Print the CLI version

mergewhy --help — Show all commands and usage examples

mergewhy completion bash — Generate shell completion scripts (bash, zsh, fish, powershell)

mergewhy sbom --file sbom.cdx.json — Submit an SPDX or CycloneDX Software Bill of Materials

mergewhy tag --resource-type artifact --resource-id abc --tags "team:payments" — Tag resources with metadata labels

mergewhy policy create --name "prod-gate" --file policy.yaml — Manage compliance policies