> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # 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. If you're an employee setting up governed access to models rather than a developer building an agent, you want the [Workforce CLI](/merge-workforce/rollout/workforce-cli) (`mfw`) instead. The two install side by side. ## Install [pipx](https://pipx.pypa.io/) is the recommended installer. It keeps the CLI isolated from your other Python packages. ```bash pipx install merge-api ``` ```bash merge --version ``` `pip install merge-api` works too, but pipx avoids dependency conflicts when you upgrade. ## Pick an auth mode This section is about authenticating the CLI to Agent Handler. Connecting the third-party accounts your tools act on (Notion, Salesforce, and every other Connector) is a separate step that happens per account through a magic link. See [Authenticate a Connector](#authenticate-a-connector). 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. ```bash 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. ```bash 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. > **Warning** > > `~/.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. #### Claude Code ```bash 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. #### Cursor ```bash merge setup cursor ``` Appends a `## Merge CLI` section to `.cursorrules`. #### AGENTS.md (cross-tool) ```bash 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 list-skills` | List the skills available to you, optionally filtered by `--keyword`. | | `merge retrieve-skill ` | Fetch a skill's SKILL.md and manifest, or one bundled file via `--path`. | | `merge authenticate ` | Mint a magic link to connect a third-party account for a Connector. | | `merge agent signup` | Create an organization, Registered User, and starter Tool Pack with no human in the loop. See the [agent quickstart](/merge-agent-handler/setup/agent-quickstart). | | `merge agent whoami` | Print the signed-up agent's account ids. | | `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 ```bash merge search-tools "send a Slack message" ``` ```json { "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 ```bash merge execute-tool slack__post_message '{"input": {"channel": "#general", "text": "Hello!"}}' ``` ```json { "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 ```bash 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. ### Skills Skills are instruction bundles your organization publishes in Agent Handler: a `SKILL.md` that teaches an agent a multi-step workflow, plus any files it references. Tools give an agent actions; a skill tells it how to combine them for a task your team has already figured out, so retrieving one beats rediscovering the procedure every session. List what's available, with `--keyword` to filter by name or description: ```bash merge list-skills --keyword expense ``` ```json { "result": { "skills": [ { "slug": "expense-report", "name": "Expense Report", "description": "File an expense report.", "referenced_connectors": [] } ] }, "status": "success" } ``` Retrieve one by its slug. The response carries the `SKILL.md` body and a manifest of every file in the bundle: ```bash merge retrieve-skill expense-report ``` ```json { "result": { "slug": "expense-report", "name": "Expense Report", "skill_md": "# Expense Report\n\nUse hibob__submit_expense...", "manifest": ["SKILL.md", "templates/report.md"] }, "status": "success" } ``` Fetch a bundled file by the path the manifest lists, one file per call: ```bash merge retrieve-skill expense-report --path templates/report.md ``` Start with the `SKILL.md` body and fetch bundled files only when it points you at them; loading the whole bundle up front wastes context the same way `--schema full` does. An unknown slug returns `error_type: not_found`, so `merge list-skills` first when you're unsure of the name. ## Authenticate a Connector `merge login` authenticates you to Agent Handler. It does not connect the third-party accounts your tools run against. Each Connector is authenticated separately, the first time you use it, through a magic link the CLI hands back to you. This is a working CLI path, not a dashboard-only one. An agent that concludes "the CLI can't connect an account, only the dashboard can" is wrong, and the steps below are how it connects one without leaving the terminal. ### The signal that a Connector needs authentication A tool call against an unconnected Connector comes back unauthenticated. You'll see one of two shapes. A `validate_credential` call returns `success: false`: ```bash merge execute-tool notion__validate_credential '{"input": {}}' ``` ```json { "result": { "success": false, "message": "Notion authentication failed. Check your credentials and try again." }, "status": "success" } ``` A normal tool call returns an error with `error_type: reauth_required`. Either way the fix is the same: mint a magic link. ### Connect the account The direct route is the `authenticate` command, which takes the Connector slug and returns the magic link: ```bash merge authenticate notion ``` Under the hood it calls the Connector's `authenticate_` tool, which you can also execute yourself. Every Connector that requires authentication exposes one, for example `authenticate_notion`. It takes no parameters, so call it with a bare `{}` (no `input` envelope): ```bash merge execute-tool authenticate_notion '{}' ``` ```json { "result": { "message": "The user must authenticate with Notion. Share this link with the user to connect their account: https://ah-api.merge.dev/magic-link/•••••/. Once authenticated, you must refetch tools or restart your MCP connection.", "magic_link_url": "https://ah-api.merge.dev/magic-link/•••••/", "link_token": "ltk_•••••" }, "status": "success" } ``` Open `magic_link_url` in a browser, complete OAuth (or paste an API key) at the third party, and the credential is stored against your Registered User. If you're an agent working on someone's behalf, hand the URL to the user verbatim. The `message` field is written for exactly that. Then retry the original tool. There is no confirmation call to make and nothing to poll: once the credential exists, the `authenticate_` tool drops out of the catalog and the real tools work. If your client caches the tool list, refetch tools or restart the MCP connection so the new tools show up. ### Finding the authenticate tool `merge search-tools "connect notion"` will not surface `authenticate_notion`. Semantic search ranks the query against the Connector's data tools, not the auth verb, so the auth tool stays hidden behind an intent search. This is the trap most agents fall into. Two reliable ways to reach it: * **Call it by name.** The pattern is always `authenticate_`, where `` is the lowercase Connector slug: `authenticate_notion`, `authenticate_google-drive`, `authenticate_microsoft-teams`. The alias `__authenticate` works too. * **List the Connector's tools.** `merge list-tools --connector notion` shows `authenticate_notion` at the top, along with the tools it unlocks. > **Note** > > The `authenticate_` tool only appears while the Connector is unauthenticated for your Registered User. Once the account is connected it disappears, and you won't see it again unless the credential is later revoked. For the full magic link flow, including callback URLs and server-to-server code exchange, see [Magic Link](/merge-agent-handler/build/authentication/magic-link). ## 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:** ```json { "result": { "...": "..." }, "status": "success", "hint": "Tool executed successfully." } ``` **Error:** ```json { "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` | One of six causes, named in `data.reauth_reason` on the error | Call `authenticate_` to mint a magic link, unless the reason is `admin_action_required`, which needs an admin rather than the end user. See [Authenticate a Connector](#authenticate-a-connector) and the [reason table](/merge-agent-handler/resources/troubleshooting). | | `billing_limit_reached` | Monthly tool-call quota hit | Upgrade at [Settings → Billing](https://ah.merge.dev/settings/billing) | | `network_error` | Connection failed | Check internet; verify `--base-url` if non-default | For a fuller troubleshooting catalog, see [Troubleshooting](/merge-agent-handler/resources/troubleshooting). ## Next For the full workforce rollout the CLI belongs to (SSO, SCIM, and Group-based tool access), see [Agent Handler for employees](/merge-agent-handler/setup/agent-handler-for-employees).