Metadata-Version: 2.4
Name: merge-workforce
Version: 0.1.0
Summary: Merge for Workforce CLI (mfw) — models, tool-calling, and admin provisioning from the terminal.
Author-email: Merge <support@merge.dev>
License-Expression: MIT
Project-URL: Homepage, https://merge.dev
Project-URL: Repository, https://github.com/merge-api/merge-workforce-cli
Keywords: merge,workforce,cli,gateway,mcp,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer==0.12.5
Requires-Dist: click==8.1.8
Requires-Dist: httpx==0.27.2
Dynamic: license-file

# 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

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

[`pipx`][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+.

> Before the first PyPI release you can install straight from the repo:
> `pipx install git+ssh://git@github.com/merge-api/merge-workforce-cli.git`.

## Quickstart

```bash
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.

| Command | What it does |
|---|---|
| `mfw login` | Browser IdP login; stores a short-lived access token. |
| `mfw setup` | Provision this device's Gateway credential (per-device, revocable). |
| `mfw models` | List the models served for you. The id is what you pass as `--model`. |
| `mfw ask -m <id> "…"` | Send one prompt to a chosen model through the Gateway. |
| `mfw chat -m <id> "…"` | Run an agent that can call your provisioned tools (MCP tool loop). |
| `mfw mcp [--write .mcp.json]` | Emit an MCP config so an external client (Claude Code, Cursor) can use your tools. |
| `mfw run -- <cmd> …` | Run a command with the Gateway credential injected as env (OpenAI-compatible). |
| `mfw creds [--export]` | Show (or `export`) the provisioned Gateway credential. |
| `mfw whoami` / `mfw logout` | Show login state / clear the stored token. |

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.

## 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.
- **`mfw mcp`** hands your tools to an external MCP client (Claude Code, Cursor,
  any SDK agent). Write the config where the client reads it:

  ```bash
  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.

For OpenAI-SDK tools, `mfw run -- <command>` injects `OPENAI_API_KEY` /
`OPENAI_BASE_URL` pointed at the Gateway, so the tool routes through it unchanged.

## 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.

[pipx]: https://pipx.pypa.io/
