Workforce CLI
Give an employee governed models and tools from the terminal, in a built-in chat or through their own AI tools
Applies to: Merge Gateway
The Workforce CLI (mfw) is the terminal path to the same governed model and tool access the desktop client sets up. An employee signs in once, and the CLI mints a Gateway credential scoped to that one machine. From there they can chat with their models and tools directly in the terminal, or point Claude Code, Codex and other AI tools at the same credential.
Reach for it when you want employees configured without deploying anything through your MDM: a pilot on a handful of machines, contractors on hardware you do not manage, or engineers who would rather run a command than wait for a device policy. When you do manage the fleet, the desktop client is the better default, because it configures machines with no employee action and can enforce policy locally, which the CLI cannot.
mfw is for employees getting governed access to models and tools. The Merge CLI (merge) is for developers building agents against Agent Handler. They authenticate separately and can be installed side by side on one machine.
Chatting from the terminal
Running mfw on its own opens a chat. On first run it signs the employee in and sets up the machine (both described below), then starts the conversation, so there are no environment variables to export and no other tool to install. It is the quickest way for an employee to try their access, and for you to confirm a rollout works end to end.
Every message goes to a model through AI Gateway with the employee’s credential, so their routing policy picks the model, their model allowlist and budget apply, and the request lands in the LLM call log. When the model needs one of the employee’s tools, the CLI calls it through Agent Handler as that employee, under the same tool access as every other surface, and hands the result back to the model in the same conversation. An employee provisioned for many connectors is not sent every tool up front: the model searches for the tools it needs and they are added as it finds them.
Inside the chat, /model shows the current model or pins one (/model auto returns to the routing policy), /tools lists what the model can call, /new starts a fresh conversation, and /help lists the rest. mfw chat "<prompt>" answers a single prompt and exits, for scripts.
The chat is not a replacement for Claude Code, Codex or Cursor: it has no access to local files or a shell. For those tools, see Pointing an AI tool at the credential.
Signing in
Running mfw does this automatically the first time. This runs an OAuth authorization-code flow with PKCE against your identity provider. A browser opens, the employee signs in, and the CLI receives the code on a loopback listener. There is no client secret to distribute and no key for an employee to copy out of a dashboard.
The listener binds a port in the range 9410 to 9419, which is deliberately separate from the range the Merge CLI uses, so an engineer running both does not hit a collision.
An employee who is signed into the Agent Handler console in the same browser can end up authenticating as that account instead. The two consoles hold separate sessions. If mfw setup reports that Merge Gateway is not set up for the organization, the login resolved to the wrong identity: sign out of the Agent Handler console, or use a separate browser profile, and run mfw login again.
Setting up the machine
Setup mints the employee’s Gateway credential for this machine. Running mfw does this automatically after the first sign-in.
The credential is per device, which is the property that matters for governance. Every machine an employee signs in on gets its own credential rather than sharing one, so you can revoke a single laptop without touching the employee’s other machines, and spend from that machine is attributed to the employee. It is the same credential model the desktop client uses, so a fleet running both is one population in your logs rather than two.
Access stays bound to identity. Deprovision the employee in your identity provider and the credential goes with the account.
Pointing an AI tool at the credential
mfw env prints export lines for the credential under the spellings AI tools read: ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN for Claude Code, OPENAI_BASE_URL and OPENAI_API_KEY for Codex and OpenAI-SDK tools, and MERGE_GATEWAY_* for the Gateway SDKs. mfw run -- <command> does the same for a single process. Tools launched this way send their model requests through AI Gateway, so the employee’s routing policy, budget, and logs apply. It also sets ANTHROPIC_API_KEY to empty on purpose: Claude Code prefers that variable over the auth token when both are set and would bypass the Gateway.
For tools, mfw mcp --write .mcp.json writes the MCP config Claude Code and Cursor read, pointing at the employee’s provisioned connectors with a short-lived token. An employee provisioned for many connectors can be offered thousands of tools; mfw mcp --connectors notion,github limits the list to those connectors, and mfw env sets ENABLE_TOOL_SEARCH=true so Claude Code loads tools on demand instead of all at once.
Following a prompt across both logs
Both commands also turn on Claude Code’s trace propagation by default. Claude Code then sends one W3C traceparent trace id on every model request and every MCP tool call it makes while answering a prompt. AI Gateway records it as client_trace_id on the LLM call log, and Agent Handler records the same value on the tool call log, so filtering each on that value gives you one prompt’s model requests and tool calls side by side. Claude Code only sends the header while its OpenTelemetry tracing is on with an otlp exporter, so mfw env sets the exporter too, pointed at the Gateway’s /v1/traces endpoint under the same credential; the Gateway accepts the spans and discards them. The built-in chat does the same with an X-Merge-Turn-Id per prompt, recorded as turn_id on both logs, and an X-Merge-Thread-Id per conversation, recorded as thread_id on the LLM call log.
Employees who already export their own OpenTelemetry variables keep them. Pass --no-trace to leave tracing alone.
What you configure first
The CLI does not change what an employee is allowed to reach. That comes from the same configuration as every other Workforce surface: identity through SCIM, models through AI Gateway, and tools through tool access. An employee whose organization has no Gateway configured cannot complete setup, which is the error described above.
Next
Deploy to a managed fleet instead with the Workforce desktop client.