Metadata-Version: 2.5
Name: merge-gateway
Version: 0.1.0
Summary: Merge Gateway CLI — route your coding agents (Claude Code, Codex) through Merge Gateway
Project-URL: Homepage, https://merge.dev
Project-URL: Repository, https://github.com/merge-api/merge-gateway-cli
Project-URL: Bug Tracker, https://github.com/merge-api/merge-gateway-cli/issues
Author-email: Merge <support@merge.dev>
License-Expression: MIT
Keywords: claude-code,cli,codex,gateway,llm,merge
Classifier: Development Status :: 3 - Alpha
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
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: click==8.4.2
Requires-Dist: httpx==0.28.1
Requires-Dist: tomlkit==0.15.1
Description-Content-Type: text/markdown

# merge-gateway-cli

`mgw` — the Merge Gateway CLI. Route your existing coding agents
(Claude Code, Codex) through [Merge Gateway](https://merge.dev) without editing
config files by hand.

## Install

```bash
pipx install merge-gateway   # recommended (isolated env)
pip install merge-gateway     # alternative
```

## What it does

1. `mgw login` — sign in through your browser (loopback + PKCE), storing a
   short-lived credential under `~/.mgw`.
2. `mgw setup <harness>` — mint a gateway API key and write the harness config
   (`claude-code` → `~/.claude/settings.json`, `codex` → `~/.codex/config.toml`).
3. `mgw doctor` — confirm the harness routes through the gateway.
4. `mgw keys list|rm` — manage the keys mgw minted; `mgw logout` clears local state.

## No human at the keyboard? `mgw agent signup`

An AI agent can set itself up without anyone opening a browser:

```bash
mgw agent signup            # creates an organization, saves a key, writes the harness config
mgw doctor                  # confirms the gateway routes
mgw agent whoami            # what the saved credential is for (validates it with the server)
mgw agent claim-url         # a fresh claim link for your user (revokes the previous one)
mgw agent forget            # drop the local credentials (nothing is revoked server-side)
```

`signup` prints a **claim URL**. The organization it created has nobody in it
and runs as a **sandbox** (a small lifetime budget, a daily request cap and a
cheap-model allowlist) until a person opens that link, signs up or logs in,
and becomes its admin — at which point the ordinary account flow (phone
verification, payment method) lifts the limits. The API key is written to
`~/.mgw/agent.json` with `0600` permissions and is never printed; pass `--json`
for machine-readable output (the key is excluded there too).

Signup is rate limited per address and fleet-wide; if it is refused, the
message says why. Re-running `signup` on a machine that already has agent
credentials is refused — use `whoami` to reuse them.

Set `MGW_CONTROL_PLANE_URL` / `MGW_GATEWAY_URL` to target a non-production
environment (e.g. `https://api-gateway-develop.merge.dev` for both).

## Development

We use [uv](https://docs.astral.sh/uv/).

```bash
uv sync --locked          # create .venv from the lockfile
make run ARGS="--version" # run the CLI
make tests                # run tests
make lint                 # ruff check + format check
```

See [AGENTS.md](./AGENTS.md) for repository conventions.
