Metadata-Version: 2.4
Name: merge-api
Version: 0.1.0
Summary: CLI for Merge Agent Handler — search, discover, and execute tools from 122+ connectors
Author-email: Merge <support@merge.dev>
License-Expression: MIT
Project-URL: Homepage, https://merge.dev
Project-URL: Documentation, https://docs.merge.dev/merge-agent-handler/implementation-guides/merge-cli
Project-URL: Repository, https://github.com/merge-api/merge-cli
Project-URL: Bug Tracker, https://github.com/merge-api/merge-cli/issues
Project-URL: Changelog, https://github.com/merge-api/merge-cli/blob/main/CHANGELOG.md
Keywords: merge,cli,agent-handler,mcp,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

[![PyPI version](https://img.shields.io/pypi/v/merge-api.svg)](https://pypi.org/project/merge-api/)
[![Python versions](https://img.shields.io/pypi/pyversions/merge-api.svg)](https://pypi.org/project/merge-api/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

# merge-cli

CLI for [Merge Agent Handler](https://merge.dev) — search, discover, and execute tools from hundreds of connectors.

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

## Install

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

## Quick Start

### 1. Configure credentials

```bash
merge configure
```

Or set environment variables:

```bash
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

```bash
merge search-tools "send a Slack message"
```

```json
{
  "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. Get a tool's input schema

```bash
merge get-tool-schema slack__post_message
```

### 4. Execute a tool

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

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

## Commands

| Command | Description |
|---|---|
| `merge search-tools <intent>` | Semantic search for tools by natural language |
| `merge execute-tool <tool> <params>` | Execute a tool with JSON parameters |
| `merge list-tools` | List all available tools (compact by default) |
| `merge get-tool-schema <tool>` | Get the input schema for a specific tool |
| `merge configure` | Interactive credential setup |
| `merge setup <target>` | Generate AI agent config (claude-code, cursor, agents-md) |
| `merge update` | Self-update to latest version |

### Common Options

All API commands accept these flags:

| Flag | Env Variable | Description |
|---|---|---|
| `--api-key` | `MERGE_AH_API_KEY` | API key |
| `--tool-pack-id` | `MERGE_AH_TOOL_PACK_ID` | Tool pack ID |
| `--registered-user-id` | `MERGE_AH_REGISTERED_USER_ID` | Registered user ID |

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

## 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:

```json
{
  "agent_handler": {
    "api_key": "pk_...",
    "tool_pack_id": "your-tool-pack-uuid",
    "registered_user_id": "your-registered-user-id",
    "base_url": "https://ah-api.merge.dev"
  }
}
```

## Output Format

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

**Success response:**

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

**Error response:**

```json
{
  "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

```bash
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

```bash
merge setup cursor
```

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

### Any AI Agent (AGENTS.md)

```bash
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 the right tool
2. merge get-tool-schema <tool>  — get its input parameters
3. merge execute-tool <tool> '<json_params>' — execute with JSON params
```

## Troubleshooting

| Problem | Solution |
|---|---|
| `config_error` | Run `merge configure` or set `MERGE_AH_*` environment variables |
| `api_error` with 401 | Check your API key. Ensure test keys are used with test users and production keys with production users |
| `not_found` | Use `merge search-tools <intent>` or `merge list-tools` to discover available tools |
| `reauth_required` | The user needs to re-authenticate the connector in the Merge dashboard |
| `billing_limit_reached` | Upgrade the account at the billing URL in the error response |
| `network_error` | Check your internet connection and `--base-url` setting |

## Development

```bash
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](LICENSE)
