Workforce CLI
Applies to: Merge Gateway
The Workforce CLI (mfw) is the terminal path to the same governed model access the desktop client sets up. An employee signs in once, and the CLI mints a Gateway credential scoped to that one machine.
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.
Signing in
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.
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. mfw chat, the CLI’s built-in agent, does the same with an X-Merge-Turn-Id per prompt, recorded as turn_id on both logs.
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.