Merge for Workforce CLI (mfw)

A command-line tool for Merge for Workforce employees: log in with your IdP, get a Gateway credential, and use your provisioned models and tools from the terminal.

Install

pipx install merge-workforce   # recommended (isolated env, puts `mfw` on PATH)
pip install merge-workforce    # alternative

pipx keeps the tool in its own environment and avoids the "externally-managed-environment" error a plain pip install hits on modern Python. One-time setup: brew install pipx && pipx ensurepath (macOS) or python3 -m pip install --user pipx && pipx ensurepath (Linux). Update later with pipx upgrade merge-workforce. Requires Python 3.10+.

To install an unreleased/dev build straight from the repo instead: pipx install git+ssh://git@github.com/merge-api/merge-workforce-cli.git.

Quickstart

mfw login --gateway-url https://ah-api.merge.dev   # opens your browser to sign in
mfw setup                                          # provision this device's Gateway credential
mfw models                                         # list the models you can use
mfw ask  -m openai/gpt-4o-mini "hello"             # one prompt to a chosen model
mfw chat -m openai/gpt-4o-mini "use my tools to …" # an agent that can call your provisioned tools

Set MFW_GATEWAY_URL once and you can drop --gateway-url from every command.

You must be a provisioned employee. mfw setup mints your key only once your admin has activated Merge for Workforce and your group has a Gateway project. If setup returns "your admin has not finished setting up Merge Gateway for your group yet", that setup isn't complete — it's not a CLI error.

Commands

Run mfw --help, or mfw <command> --help for details on any one.

The Gateway routes and bills every call and enforces your allowlist, so a model or tool you aren't provisioned for comes back as a request error, never a silent fallback.

Admin operations (mfw admin)

For workforce admins — these provision and manage the org from the terminal. They require the manage_workforce role and run against your mfw login token, so no mfw setup is needed (admin commands don't use the Gateway credential). Without the role they return a permission error.

mfw admin groups                                    # list the org's groups (id + name)
mfw admin employees                                 # list employees (id, name, origin id)

# add an employee to a group, then remove one (removal revokes their Gateway keys)
mfw admin add-employee --group <group-id> --name "Jane Doe" --origin-id "jane@corp.com"
mfw admin remove-employee <employee-id>

# a group's model allowlist — a full replace (repeat -m), or clear it
mfw admin set-models <group-id> -m anthropic/claude-haiku-4-5-20251001 -m amazon/nova-micro
mfw admin set-models <group-id> --unrestricted      # allow every model

Run mfw admin --help, or mfw admin <command> --help, for details on any one.

Usage with AI agents

Two ways to give an AI agent your provisioned models and tools, both governed by your org:

• mfw chat is a built-in agent — it drives a model through the Gateway and calls your provisioned tools over MCP, no other client needed. Every prompt carries one X-Merge-Turn-Id on its model requests and its tool calls, so the Gateway request log and the Agent Handler tool call log join on turn_id.

• mfw mcp hands your tools to an external MCP client (Claude Code, Cursor, any SDK agent). Write the config where the client reads it:

  mfw mcp --write .mcp.json     # Claude Code picks this up from the project root
  

  The config points the client at the backend's MCP endpoint with a short-lived token, so the agent calls tools as you, exactly as the console governs them. Re-run when the token lapses.

• mfw env and mfw run point an AI tool at the Gateway. Both set the credential under its Merge, OpenAI-SDK (OPENAI_API_KEY / OPENAI_BASE_URL) and Anthropic-SDK (ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN) spellings, so Claude Code, Codex, or any SDK tool routes through the Gateway unchanged:

  eval "$(mfw env)" && claude        # this shell
  mfw run -- claude                  # one process
  

  By default both also turn on Claude Code's trace propagation (CLAUDE_CODE_ENABLE_TELEMETRY, CLAUDE_CODE_ENHANCED_TELEMETRY_BETA, CLAUDE_CODE_PROPAGATE_TRACEPARENT, OTEL_TRACES_EXPORTER=otlp with the Gateway's /v1/traces as the OTLP endpoint). With those set, every model request and every MCP tool call in one prompt carries the same trace id, which Gateway logs as client_trace_id and Agent Handler logs on the tool call, so one prompt joins across both logs. Variables you already export win; pass --no-trace to skip that block entirely.

How it works

• Login is OAuth 2.0 Authorization Code + PKCE with a loopback redirect (RFC 8252): the public client merge-workforce-cli (no secret on the laptop), your browser → <gateway>/o/authorize/ → IdP login + consent → code returns to http://localhost:{9410-9419}/callback → exchanged at <gateway>/o/token/. The access token is stored in ~/.mfw/credentials.json (0600).
• Setup exchanges that token for a per-device Gateway API key (~/.mfw/gateway_credential.json), the same per-device path the desktop client uses — independently revocable, with spend attributed to you.
• Models are the maintained /v1/responses surface; chat connects your provisioned tools over the backend's OAuth-authed /mcp/ endpoint and runs the function-calling loop for you.