CLI Reference#

The Mergeproof CLI (@mergeproof/cli) is the primary interface for interacting with the Mergeproof protocol. Create bounties, submit PRs, report bugs, attest code quality, and manage your wallet -- all from the terminal.

Installation#

# Install globally
npm install -g @mergeproof/cli

# Or use without installing
npx @mergeproof/cli <command>

# Or within the monorepo
pnpm install
pnpm --filter @mergeproof/cli build

After installation, the mergeproof binary is available in your PATH.

Configuration#

Environment Variables#

Networks#

Wallet Management#

The CLI resolves wallets in this order:

1. MERGEPROOF_PRIVATE_KEY environment variable
2. Stored wallet at ~/.mergeproof/wallet.json
3. Auto-generates a new wallet (saved to ~/.mergeproof/wallet.json with 0600 permissions)

Global Options#

mergeproof [options] <command>

Command Reference#

mergeproof bounty -- Manage bounties#

bounty create#

Create a new bounty for a GitHub issue. Deposits funds into the EVM Escrow contract and registers the bounty on GenLayer.

mergeproof bounty create \
  --repo owner/repo \
  --issue 42 \
  --amount 100

The command:

1. Checks your token balance
2. Verifies the bounty ID is unique
3. Checks repository permissions
4. Deposits funds on EVM Escrow (bounty + attestation pool)
5. Creates the bounty on GenLayer
6. Posts a comment on the GitHub issue (if GITHUB_TOKEN is set)

bounty list#

List bounties with optional filtering and pagination.

mergeproof bounty list
mergeproof bounty list --status open --limit 10
mergeproof bounty list --offset 50 --limit 25

bounty info <bounty-id>#

Get detailed information about a specific bounty.

mergeproof bounty info bounty_a1b2c3d4e5f6g7h8

Displays: ID, repo, issue, amount, token, stake ratio, stake required, attestation pool, review window, status, owner, creation date, and current submission.

bounty configure <bounty-id>#

Update bounty configuration (owner only). Not available in v1 -- bounty parameters are immutable.

mergeproof pr -- Manage PR submissions#

pr submit#

Submit a PR for a bounty. Stakes the required amount (bounty amount * stake ratio) on the EVM Escrow.

mergeproof pr submit \
  --bounty bounty_a1b2c3d4e5f6g7h8 \
  --pr 15 \
  --commit abc123def456

The command:

1. Fetches bounty details and calculates stake
2. Checks existing stake (incremental staking supported)
3. Deposits any additional stake needed on EVM
4. Registers the submission on GenLayer
5. Posts to the GitHub PR (if GITHUB_TOKEN is set)

pr retry#

Retry a submission with a new commit after fixing bugs found during review.

mergeproof pr retry \
  --bounty bounty_a1b2c3d4e5f6g7h8 \
  --commit newcommithash123

If your stake was partially slashed from validated bugs, the retry command tops up the stake automatically.

pr claim#

Claim the bounty after the review window passes without critical issues.

mergeproof pr claim --bounty bounty_a1b2c3d4e5f6g7h8
mergeproof pr claim --bounty bounty_a1b2c3d4e5f6g7h8 --wait

pr abandon#

Abandon a submission. This forfeits your stake.

mergeproof pr abandon --bounty bounty_a1b2c3d4e5f6g7h8 --confirm

pr status [submission-id]#

Check the status of a submission. Accepts a submission ID directly or looks up the current submission for a bounty.

mergeproof pr status sub_12345
mergeproof pr status --bounty bounty_a1b2c3d4e5f6g7h8

Displays: submission ID, bounty ID, PR number, commit hash, attempt number (max 3), status, staked amount, current bounty value, total reduction, window start/end, and time remaining.

mergeproof bug -- Manage bug reports#

bug report#

Report a bug against an active submission. Requires a stake of 0.25% of the bounty amount.

mergeproof bug report \
  --bounty bounty_a1b2c3d4e5f6g7h8 \
  --commit abc123def456 \
  --severity major \
  --description "SQL injection in login handler"

The bounty must be in in_review status. The command deposits 0.25% of the bounty as stake, then submits the report to GenLayer.

bug validate <bug-id>#

Validate a bug report (bounty owner only). Marks the bug as valid (rewards the hunter) or invalid (slashes the hunter's stake).

# Accept the bug as valid
mergeproof bug validate bug_12345 --valid

# Reject the bug
mergeproof bug validate bug_12345 --invalid

# Accept but rescope severity
mergeproof bug validate bug_12345 --valid --severity minor

Exactly one of --valid or --invalid is required.

bug list <submission-id>#

List all bug reports for a submission.

mergeproof bug list sub_12345

Displays severity (with color-coded icons), bug ID, description, reporter, and validation status.

bug info <bug-id>#

Get details for a single bug report. Not yet implemented -- use bug list instead.

mergeproof attest -- Manage code attestations#

attest submit#

Attest that a submission's code is bug-free. Stakes 1% of the bounty amount.

mergeproof attest submit --bounty bounty_a1b2c3d4e5f6g7h8

Risk/reward:

• If no valid bugs are found: get your stake back + 0.5% of bounty from the attestation pool
• If valid bugs are found: your stake is slashed

The bounty must be in in_review status and have a non-zero attestation pool.

attest list <bounty-id>#

List all attestations for a bounty.

mergeproof attest list bounty_a1b2c3d4e5f6g7h8

Displays attestor GitHub username, wallet address, and attestation timestamp.

mergeproof identity -- GitHub identity verification#

identity start#

Generate a verification challenge string to link your wallet to your GitHub account.

mergeproof identity start

Post the returned challenge string to one of:

1. Your GitHub bio
2. A profile README (github.com/<username>/<username>)
3. A public gist

identity verify#

Complete verification after posting the challenge to GitHub.

mergeproof identity verify --github yourname

identity status#

Check your current identity verification status.

mergeproof identity status

Displays whether your wallet is linked, the associated GitHub username, and verification timestamp.

identity dev-register#

Register an identity without GitHub verification. Only works in local development.

mergeproof identity dev-register --github testuser

mergeproof wallet -- Wallet and token management#

wallet balance#

Check your ETH and token balances.

mergeproof wallet balance
mergeproof wallet balance --token 0x1234...abcd

wallet info#

Show wallet address, contract addresses, and balances.

mergeproof wallet info

Displays: network, wallet address, ETH balance, token balance, escrow address, token address, and registry address.

wallet send#

Send ETH or ERC20 tokens.

# Send ETH
mergeproof wallet send --to 0xRecipient --amount 0.1

# Send ERC20 tokens
mergeproof wallet send --to 0xRecipient --amount 50 --token 0xTokenAddress

wallet import <private-key>#

Import an existing private key. Overwrites any existing stored wallet.

mergeproof wallet import 0xYourPrivateKeyHere

wallet export#

Display your private key. Requires interactive confirmation.

mergeproof wallet export

If the wallet is configured via MERGEPROOF_PRIVATE_KEY, the command reports that instead.

wallet faucet#

Request test tokens from the faucet. Only works on local and staging networks.

mergeproof wallet faucet

mergeproof config -- Configuration#

config show#

Display the resolved configuration: network, RPC endpoints, contract addresses, wallet info, and wallet source.

mergeproof config show

JSON Output Mode#

Pass --json to any command for machine-readable output. All commands emit structured JSON to stdout.

mergeproof --json bounty list --status open

Success response:

{
  "success": true,
  "message": "Bounty created",
  "data": {
    "bounty_id": "bounty_a1b2c3d4",
    "repo": "myorg/myapp",
    "issue": 42,
    "amount": "100",
    "evm_tx": "0x...",
    "genlayer_tx": "0x..."
  }
}

Error response:

{
  "success": false,
  "error": "Bounty not found",
  "error_code": "NOT_FOUND",
  "retriable": false
}

Error codes:

Non-interactive environments (CI, pipes) require -y or --yes for commands that prompt for confirmation.

Example Workflows#

1. Full Bounty Lifecycle#

# Set up your wallet
export MERGEPROOF_PRIVATE_KEY=0xYourKey
export MERGEPROOF_NETWORK=staging

# Link your GitHub identity
mergeproof identity start
# Post the challenge to your GitHub bio, then:
mergeproof identity verify --github yourname

# Create a bounty on an issue
mergeproof bounty create \
  --repo myorg/myapp \
  --issue 42 \
  --amount 100 \
  --stake-ratio 10 \
  --window 72

# (Developer fixes the issue in a PR)

# Submit your PR
mergeproof pr submit \
  --bounty bounty_a1b2c3d4e5f6g7h8 \
  --pr 15 \
  --commit abc123def456

# Wait for the 72-hour review window...

# Claim the bounty after the window closes
mergeproof pr claim \
  --bounty bounty_a1b2c3d4e5f6g7h8 \
  --wait

2. Bug Hunting Workflow#

# Find open bounties
mergeproof bounty list --status in_review

# Inspect a bounty
mergeproof bounty info bounty_a1b2c3d4e5f6g7h8

# Report a bug (stakes 0.25% of bounty)
mergeproof bug report \
  --bounty bounty_a1b2c3d4e5f6g7h8 \
  --commit abc123def456 \
  --severity critical \
  --description "Buffer overflow in parser allows arbitrary code execution" \
  --evidence "https://gist.github.com/yourbugpoc"

# Check bug report status
mergeproof pr status --bounty bounty_a1b2c3d4e5f6g7h8

3. Attestation Workflow#

# Find bounties in review
mergeproof bounty list --status in_review

# Review the code, then attest (stakes 1% of bounty)
mergeproof attest submit --bounty bounty_a1b2c3d4e5f6g7h8

# Check attestations
mergeproof attest list bounty_a1b2c3d4e5f6g7h8

4. AI Agent Integration#

# All commands support --json for programmatic use
BOUNTY_ID=$(mergeproof --json bounty create \
  --repo myorg/myapp \
  --issue 42 \
  --amount 100 \
  -y | jq -r '.data.bounty_id')

echo "Created bounty: $BOUNTY_ID"

# List bounties as JSON
mergeproof --json bounty list --status open | jq '.bounties[] | .id'

# Check status programmatically
STATUS=$(mergeproof --json pr status --bounty "$BOUNTY_ID" | jq -r '.status')

Troubleshooting#

"No wallet configured"#

Set MERGEPROOF_PRIVATE_KEY or run any command to auto-generate a wallet at ~/.mergeproof/wallet.json.

"BountyRegistry contract not deployed"#

Set MERGEPROOF_BOUNTY_REGISTRY to the deployed contract address, or switch networks:

mergeproof --network staging bounty list

"Escrow contract not configured"#

Set MERGEPROOF_ESCROW_ADDRESS or ensure you're on a network with pre-configured contracts.

"Insufficient balance"#

Check your balance and get test tokens on local/staging:

mergeproof wallet balance
mergeproof wallet faucet   # local/staging only

"Cannot prompt for confirmation in non-interactive mode"#

Add -y or --yes to skip confirmation prompts in CI/scripts:

mergeproof bounty create --repo org/repo --issue 1 --amount 100 -y

Transaction failures#

Set DEBUG=1 to see full GenLayer transaction receipts:

DEBUG=1 mergeproof pr submit --bounty <id> --pr 5 --commit abc123

GitHub comments not posting#

Ensure GITHUB_TOKEN is set with repo scope. Disable posting with:

export MERGEPROOF_POST_TO_GITHUB=false