Merge CLI

The Merge CLI is a lightweight command-line tool for interacting with Agent Handler. It provides semantic tool search, schema inspection, and tool execution — purpose-built for AI coding agents like Claude Code and Cursor that need progressive tool discovery without overwhelming the context window.

Prerequisites

1. Tool Pack ID: The ID of the tool pack to use. Found in the Agent Handler dashboard or via the GET /tool-packs endpoint.
2. Registered User ID: The ID of the user who will interact with your agent. Found in the dashboard or created via API.
3. Production Access Key: Your Merge Agent Handler API key for authentication.

Getting Started

$
pipx install merge-api

$
pip install merge-api

$
merge --version

$
merge configure

$
export MERGE_AH_API_KEY="pk_..."
$
export MERGE_AH_TOOL_PACK_ID="your-tool-pack-uuid"
$
export MERGE_AH_REGISTERED_USER_ID="your-registered-user-id"

$
merge setup claude-code

$
merge setup cursor

$
merge setup agents-md

$
merge search-tools "send a Slack message"

1
{
2
  "tools": [
3
    {
4
      "name": "slack__post_message",
5
      "description": "Post a message to a Slack channel",
6
      "input_schema": { ... },
7
    }
8
  ],
9
  "total_results": 1,
10
  "hint": "To execute: merge execute-tool <tool_name> '<json_params>'"
11
}

$
merge execute-tool slack__post_message '{"input": {"channel": "#general", "text": "Hello!"}}'

1
{
2
  "result": { "ok": true, "ts": "1234567890.123456" },
3
  "status": "success",
4
  "hint": "Tool executed successfully."
5
}

Commands

Key Options

• --connector <slug>: Filter search or list results by connector (e.g., slack, jira, github)
• --schema [compact|full|none]: Schema detail level for search results (default: compact)
• --full: Include full schemas when listing tools
• --compact: Show tool names with param names only when listing tools
• --max-results <n>: Limit number of search results (default: 2, max: 50)

Configuration

Credentials are resolved in this priority order (highest to lowest):

1. CLI flags: --api-key, --tool-pack-id, --registered-user-id, --base-url
2. Environment variables: MERGE_AH_API_KEY, MERGE_AH_TOOL_PACK_ID, MERGE_AH_REGISTERED_USER_ID, MERGE_AH_BASE_URL
3. Config file: ~/.merge/config.json

Example config file:

1
{
2
  "agent_handler": {
3
    "api_key": "pk_...",
4
    "tool_pack_id": "your-tool-pack-uuid",
5
    "registered_user_id": "your-registered-user-id"
6
  }
7
}

Using with AI Agents

The CLI outputs structured JSON to stdout with hint fields that guide agents on next steps. Warnings go to stderr so they never contaminate the JSON output.

The fastest way to configure your AI agent is the merge setup command:

Claude Code

$
merge setup claude-code

This automatically:

• Appends merge CLI workflow instructions to your CLAUDE.md (creates it if it doesn’t exist)
• Adds Bash(merge *) permission to .claude/settings.json

Safe to run multiple times — it won’t duplicate content.

Cursor

$
merge setup cursor

This appends merge CLI instructions to your .cursorrules (or creates it if it doesn’t exist).

Any AI Agent (AGENTS.md)

$
merge setup agents-md

This appends merge CLI instructions to your AGENTS.md (or creates it if it doesn’t exist) — the cross-tool standard supported by Claude Code, Cursor, Codex, Windsurf, and more.

Agent Workflow

Once configured, your agent follows this workflow:

1. merge search-tools "<intent>" — find the right tool (returns compact schemas)
2. merge execute-tool <tool> '<json_params>' — execute with JSON params

Search returns schemas by default, so agents can go straight from search to execute without a separate schema fetch.

Output Format

All commands return JSON with a consistent structure.

Success:

1
{
2
  "result": { ... },
3
  "status": "success",
4
  "hint": "Tool executed successfully."
5
}

Error:

1
{
2
  "result": null,
3
  "status": "error",
4
  "error_type": "api_error",
5
  "message": "Description of what went wrong",
6
  "hint": "Suggested next step"
7
}

Troubleshooting