Merge CLI

The Merge CLI is a lightweight command-line tool for interacting with Agent Handler. Built specifically for AI coding agents - Claude Code, Cursor, Codex - that need progressive tool discovery without overwhelming the context window. Search returns compact schemas; execute runs the tool; the agent doesn’t have to load every tool in the catalog up front.

It’s also useful for humans. Quick exploration, scripted automation, sanity-checking a Tool Pack from a terminal.

Install

pipx is the recommended installer. It keeps the CLI isolated from your other Python packages.

$
pipx install merge-api

$
merge --version

pip install merge-api works too, but pipx avoids dependency conflicts when you upgrade.

Pick an auth mode

Two ways to authenticate. Pick one based on context.

OAuth (merge login). Opens a browser, completes OAuth, stores a token. Use this when you’re a developer building locally and want the CLI to act as you.

$
merge login

API key (merge configure). Interactive prompt that captures your API key, Tool Pack ID, and Registered User ID. Use this when the CLI needs to act as a specific Registered User - common in CI or when scripting against test data.

$
merge configure

If both modes are configured, OAuth takes precedence. To force API-key mode, unset the oauth section of ~/.merge/config.json or set the env vars (next section) explicitly.

Configuration precedence

Credentials resolve in this order, highest priority first:

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.

Env vars are the right path for CI. The config file is the right path for local development.

Set up your AI agent

merge setup writes the right CLI workflow instructions into your agent’s config file.

$
merge setup claude-code

After setup, your agent will use merge search-tools and merge execute-tool for any third-party action automatically.

Commands

Search

$
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
}

Useful flags:

• --Connector slack - narrow to one Connector. Repeatable.
• --max-results 5 - return up to N results (default 2, max 50).
• --schema compact|full|none - schema detail. Default is compact (descriptions stripped) to save context. Use full when you need every field’s description; none when you only need names.

Execute

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

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

Parameters always go in input. Fields the tool’s schema marks optional can be omitted.

List and inspect

$
merge list-tools                       # All tools, default compact
$
merge list-tools --Connector slack     # Filter to one Connector
$
merge list-tools --full                # Include full input schemas
$
merge get-tool-schema slack__post_message

merge list-tools is useful for exploration; for everyday agent use, search-tools is faster and produces less context to wade through.

Output format

Every command returns JSON to stdout. Warnings and progress messages go to stderr - agents that pipe stdout into JSON parsers won’t choke.

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": "What went wrong",
6
  "hint": "Suggested next step"
7
}

Errors exit with code 1. Wrap CLI invocations in your scripts accordingly.

Common errors

For a fuller troubleshooting catalog, see Troubleshooting.

Next

Embed authentication for your end users with Link.