Fresh 2026

Merge CLI

Merge CLI reference: tool search, schema inspection, execution, OAuth and API-key auth modes, AI agent setup commands.

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)	API key (merge configure)
Best for	Interactive use on your own machine - local agents, exploration	Automation - CI, scripts, headless agents
Setup	One browser-based login	Paste API key + Tool Pack ID + Registered User ID
Where credentials live	~/.merge/config.json (OAuth tokens)	~/.merge/config.json (API key)
Token refresh	Automatic	N/A - keys don't expire
Tied to	Your dashboard user	A specific Registered User

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.

~/.merge/config.json contains your API key in plain text. Don't commit it; if it's on a shared machine, use env vars and chmod 600 the file at minimum.

Set up your AI agent

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

merge setup claude-code

Appends a ## Merge CLI section to CLAUDE.md (creates the file if absent) and adds Bash(merge *) permission to .claude/settings.json. Idempotent - safe to run multiple times.

merge setup cursor

Appends a ## Merge CLI section to .cursorrules.

merge setup agents-md

Appends to AGENTS.md - the cross-tool standard supported by Claude Code, Cursor, Codex, Aider, and others.

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

Commands

Command	What it does
merge search-tools	Semantic search for tools by natural language. Returns compact schemas.
merge execute-tool	Execute a tool with JSON parameters.
merge list-tools	List all available tools.
merge get-tool-schema	Get the full input schema for a specific tool.
merge configure	Interactive credential setup (API-key mode).
merge login / merge logout	OAuth-mode auth.
merge setup	Generate AI agent config (claude-code, cursor, agents-md).
merge update	Self-update to the latest version.

Search

merge search-tools "send a Slack message"

{
  "tools": [
    {
      "name": "slack__post_message",
      "description": "Post a message to a Slack channel",
      "input_schema": { "...": "..." }
    }
  ],
  "total_results": 1,
  "hint": "To execute: merge execute-tool  ''"
}

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!"}}'

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

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:

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

Error:

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

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

Common errors

Error type	Cause	Fix
config_error	No credentials configured	merge login or merge configure, or set MERGE_AH_* env vars
api_error (401)	Invalid API key, or test key with production resource	Check the key matches the resource's environment
not_found	Tool name doesn't exist	merge search-tools to find the right one
reauth_required	Connector OAuth token expired or revoked	Open the Registered User's Connectors and re-authenticate
billing_limit_reached	Monthly tool-call quota hit	Upgrade at Settings → Billing
network_error	Connection failed	Check internet; verify --base-url if non-default

For a fuller troubleshooting catalog, see Troubleshooting.

Next

Embed authentication for your end users with Link.