merge-cli

CLI for Merge Agent Handler — search, discover, and execute thousands of tools.

Designed for AI agents (Claude Code, Cursor) that need progressive tool discovery without clogging the context window.

Install

pipx install merge-api   # recommended (isolated env)
pip install merge-api     # alternative

Quick Start

Option A: Login via browser (recommended)

merge login

Opens your browser to authenticate via OAuth. After consent, tokens are saved locally. No API key or tool pack ID needed.

Option B: Configure with API key

Note: merge configure is on a deprecation path. Use merge login instead.

merge configure

Or set environment variables:

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"

2. Search for tools

merge search-tools "send a Slack message"

{
  "tools": [
    {
      "name": "slack__post_message",
      "description": "Post a message to a Slack channel",
      "input_schema": { "type": "object", "properties": { "channel": { "type": "string" }, "text": { "type": "string" } } },
    }
  ],
  "total_results": 1,
  "hint": "To execute: merge execute-tool <tool_name> '<json_params>'"
}

3. Execute a tool

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

{
  "result": { "ok": true, "ts": "1234567890.123456" },
  "status": "success",
  "hint": "Tool executed successfully."
}

Commands

Common Options

All API commands accept these flags:

| --base-url | MERGE_AH_BASE_URL | Base URL override |

Authentication

Two auth modes, auto-detected:

If both are configured, OAuth takes priority.

Configuration

Priority (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:

{
  "agent_handler": {
    "api_key": "pk_...",
    "tool_pack_id": "your-tool-pack-uuid",
    "registered_user_id": "your-registered-user-id"
  },
  "oauth": {
    "access_token": "...",
    "refresh_token": "...",
    "client_id": "merge-cli"
  }
}

Output Format

All commands output JSON to stdout. Warnings go to stderr.

Success response:

{
  "result": { ... },
  "status": "success",
  "hint": "Tool executed successfully."
}

Error response:

{
  "result": null,
  "status": "error",
  "error_type": "api_error",
  "message": "Description of what went wrong",
  "hint": "Suggested next step"
}

Error types: config_error, api_error, network_error, invalid_params, not_found, reauth_required, billing_limit_reached

Usage with AI Agents

The fastest way to set up any AI agent is the merge setup command:

Claude Code

merge setup claude-code

This appends merge CLI instructions to your CLAUDE.md (or creates it if it doesn't exist) and adds Bash(merge *) 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.

Manual Setup

If you prefer manual configuration, add this to your agent's system prompt or project instructions:

For any task involving third-party services (Slack, Jira, GitHub, Salesforce, etc.),
use the `merge` CLI. Do not call APIs directly.

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

Troubleshooting

Development

git clone https://github.com/merge-api/merge-cli.git
cd merge-cli
pip install -e ".[dev]"
pytest                    # run tests
ruff check .              # lint
ruff format --check .     # format check

License

MIT