merge-gateway 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- merge_gateway-0.1.0/.github/CODEOWNERS +1 -0
- merge_gateway-0.1.0/.github/dependabot.yml +9 -0
- merge_gateway-0.1.0/.github/pull_request_template.md +18 -0
- merge_gateway-0.1.0/.github/workflows/ci.yml +36 -0
- merge_gateway-0.1.0/.github/workflows/publish.yml +23 -0
- merge_gateway-0.1.0/.gitignore +19 -0
- merge_gateway-0.1.0/.python-version +1 -0
- merge_gateway-0.1.0/AGENTS.md +95 -0
- merge_gateway-0.1.0/CLAUDE.md +1 -0
- merge_gateway-0.1.0/Makefile +28 -0
- merge_gateway-0.1.0/PKG-INFO +84 -0
- merge_gateway-0.1.0/README.md +61 -0
- merge_gateway-0.1.0/mgw/__init__.py +3 -0
- merge_gateway-0.1.0/mgw/api.py +322 -0
- merge_gateway-0.1.0/mgw/auth/__init__.py +1 -0
- merge_gateway-0.1.0/mgw/auth/flow.py +77 -0
- merge_gateway-0.1.0/mgw/auth/login.py +65 -0
- merge_gateway-0.1.0/mgw/auth/loopback.py +110 -0
- merge_gateway-0.1.0/mgw/auth/pkce.py +23 -0
- merge_gateway-0.1.0/mgw/auth/store.py +130 -0
- merge_gateway-0.1.0/mgw/cli.py +35 -0
- merge_gateway-0.1.0/mgw/commands/__init__.py +1 -0
- merge_gateway-0.1.0/mgw/commands/agent.py +261 -0
- merge_gateway-0.1.0/mgw/commands/doctor.py +88 -0
- merge_gateway-0.1.0/mgw/commands/keys.py +90 -0
- merge_gateway-0.1.0/mgw/commands/login.py +24 -0
- merge_gateway-0.1.0/mgw/commands/logout.py +24 -0
- merge_gateway-0.1.0/mgw/commands/setup.py +95 -0
- merge_gateway-0.1.0/mgw/config.py +60 -0
- merge_gateway-0.1.0/mgw/harness/__init__.py +15 -0
- merge_gateway-0.1.0/mgw/harness/base.py +60 -0
- merge_gateway-0.1.0/mgw/harness/claude_code.py +65 -0
- merge_gateway-0.1.0/mgw/harness/codex.py +68 -0
- merge_gateway-0.1.0/mgw/provision.py +90 -0
- merge_gateway-0.1.0/pyproject.toml +54 -0
- merge_gateway-0.1.0/tests/__init__.py +0 -0
- merge_gateway-0.1.0/tests/conftest.py +27 -0
- merge_gateway-0.1.0/tests/test_agent_command.py +308 -0
- merge_gateway-0.1.0/tests/test_api.py +159 -0
- merge_gateway-0.1.0/tests/test_api_agent.py +115 -0
- merge_gateway-0.1.0/tests/test_auth_flow.py +101 -0
- merge_gateway-0.1.0/tests/test_auth_login.py +88 -0
- merge_gateway-0.1.0/tests/test_auth_pkce.py +38 -0
- merge_gateway-0.1.0/tests/test_auth_store.py +76 -0
- merge_gateway-0.1.0/tests/test_cli.py +21 -0
- merge_gateway-0.1.0/tests/test_config.py +49 -0
- merge_gateway-0.1.0/tests/test_doctor.py +149 -0
- merge_gateway-0.1.0/tests/test_harness_claude_code.py +124 -0
- merge_gateway-0.1.0/tests/test_harness_codex.py +105 -0
- merge_gateway-0.1.0/tests/test_keys.py +103 -0
- merge_gateway-0.1.0/tests/test_login_command.py +36 -0
- merge_gateway-0.1.0/tests/test_logout.py +29 -0
- merge_gateway-0.1.0/tests/test_provision.py +122 -0
- merge_gateway-0.1.0/tests/test_setup.py +128 -0
- merge_gateway-0.1.0/uv.lock +285 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
* @merge-api/gateway-engineering
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Python deps (uv.lock) are not covered here: Dependabot's classic
|
|
2
|
+
# package-ecosystem list doesn't include "uv", and uv's own docs point uv-lock
|
|
3
|
+
# users to Renovate. Bump Python deps with `uv lock --upgrade` (or add Renovate).
|
|
4
|
+
version: 2
|
|
5
|
+
updates:
|
|
6
|
+
- package-ecosystem: "github-actions"
|
|
7
|
+
directory: "/"
|
|
8
|
+
schedule:
|
|
9
|
+
interval: "weekly"
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
## What
|
|
2
|
+
|
|
3
|
+
<!-- One or two sentences: what this change does. -->
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
<!-- The motivation / linked issue. -->
|
|
8
|
+
|
|
9
|
+
## Testing
|
|
10
|
+
|
|
11
|
+
<!-- How you verified it. New/updated tests? `uv run pytest`? Manual steps? -->
|
|
12
|
+
|
|
13
|
+
## Checklist
|
|
14
|
+
|
|
15
|
+
- [ ] `uv run ruff format` and `uv run ruff check` pass
|
|
16
|
+
- [ ] `uv run pytest` passes
|
|
17
|
+
- [ ] New behavior is covered by tests (TDD)
|
|
18
|
+
- [ ] No secrets in code, logs, or fixtures
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
concurrency:
|
|
9
|
+
group: ci-${{ github.ref }}
|
|
10
|
+
cancel-in-progress: true
|
|
11
|
+
|
|
12
|
+
jobs:
|
|
13
|
+
lint:
|
|
14
|
+
runs-on: blacksmith-4vcpu-ubuntu-2404
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
|
|
17
|
+
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
|
|
18
|
+
with:
|
|
19
|
+
enable-cache: true
|
|
20
|
+
- run: uv sync --locked
|
|
21
|
+
- run: uv run ruff check .
|
|
22
|
+
- run: uv run ruff format --check .
|
|
23
|
+
|
|
24
|
+
test:
|
|
25
|
+
runs-on: blacksmith-4vcpu-ubuntu-2404
|
|
26
|
+
strategy:
|
|
27
|
+
matrix:
|
|
28
|
+
python-version: ["3.10", "3.11", "3.12", "3.13"]
|
|
29
|
+
steps:
|
|
30
|
+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
|
|
31
|
+
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
|
|
32
|
+
with:
|
|
33
|
+
enable-cache: true
|
|
34
|
+
python-version: ${{ matrix.python-version }}
|
|
35
|
+
- run: uv sync --locked
|
|
36
|
+
- run: uv run pytest -q
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
# Fires on a published GitHub Release, not on merge: cut a release to ship.
|
|
4
|
+
on:
|
|
5
|
+
release:
|
|
6
|
+
types: [published]
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
publish:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
environment: pypi
|
|
12
|
+
permissions:
|
|
13
|
+
contents: read
|
|
14
|
+
id-token: write
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
|
|
17
|
+
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
|
|
18
|
+
with:
|
|
19
|
+
enable-cache: true
|
|
20
|
+
- run: uv sync --locked
|
|
21
|
+
- run: uv run pytest -q
|
|
22
|
+
- run: uv build
|
|
23
|
+
- uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.12
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Guidance for AI coding agents (Claude Code, Codex, and others) working in this
|
|
4
|
+
repository. `CLAUDE.md` is a symlink to this file, so every tool reads the same
|
|
5
|
+
source.
|
|
6
|
+
|
|
7
|
+
## Project overview
|
|
8
|
+
|
|
9
|
+
`mgw` is the Merge Gateway CLI. It gives developers a seamless way to route
|
|
10
|
+
their existing coding agents (Claude Code, Codex) through Merge Gateway:
|
|
11
|
+
|
|
12
|
+
1. `mgw login` — browser-based sign-in to the control plane using a
|
|
13
|
+
loopback + PKCE OAuth flow; stores a short-lived credential locally.
|
|
14
|
+
2. `mgw setup <harness>` — mints an `mg_` gateway API key and writes the
|
|
15
|
+
harness config (`~/.claude/settings.json` for Claude Code,
|
|
16
|
+
`~/.codex/config.toml` for Codex).
|
|
17
|
+
3. `mgw doctor` — probes the gateway to confirm the harness is routed.
|
|
18
|
+
4. `mgw status` — reports login + harness configuration state.
|
|
19
|
+
5. `mgw agent signup|whoami|claim-url|forget` — the no-human path: the agent
|
|
20
|
+
creates a zero-member, capped organization via `POST /agent/signup` on the
|
|
21
|
+
control plane, stores the key in `~/.mgw/agent.json`, and hands its user a
|
|
22
|
+
claim URL. Mirrors `merge agent signup` in merge-cli so the two CLIs can
|
|
23
|
+
consolidate later.
|
|
24
|
+
|
|
25
|
+
Full design lives in the `merge-gateway` repo:
|
|
26
|
+
`docs/superpowers/specs/2026-07-22-cli-harness-onboarding-design.md`.
|
|
27
|
+
|
|
28
|
+
This CLI is a sibling to `merge-api/merge-cli` (the Agent Handler CLI). Both are
|
|
29
|
+
Python, share the same OAuth authorization server, and are structured so they
|
|
30
|
+
can be consolidated into one CLI later — keep patterns aligned where practical.
|
|
31
|
+
|
|
32
|
+
## Development commands
|
|
33
|
+
|
|
34
|
+
We use [uv](https://docs.astral.sh/uv/) for everything.
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
uv sync --locked # install deps into .venv from the lockfile
|
|
38
|
+
make run ARGS="--version" # run the CLI (uv run mgw ...)
|
|
39
|
+
make tests # uv run pytest -q
|
|
40
|
+
make fmt # uv run ruff format .
|
|
41
|
+
make lint # uv run ruff check . && ruff format --check .
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Architecture
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
mgw/
|
|
48
|
+
__init__.py # package + __version__
|
|
49
|
+
cli.py # top-level Click group + command registration
|
|
50
|
+
config.py # ~/.mgw/settings.json overrides (env > file > default)
|
|
51
|
+
commands/ # login, logout, setup, doctor, keys, agent
|
|
52
|
+
harness/ # config writers: claude-code (JSON), codex (TOML)
|
|
53
|
+
tests/ # pytest, mirrors the package layout
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Planned modules, added as implementation proceeds:
|
|
57
|
+
|
|
58
|
+
- `mgw/api.py` — thin control-plane HTTP client (httpx) for key minting
|
|
59
|
+
- `mgw/harness/` — one writer per supported harness
|
|
60
|
+
|
|
61
|
+
## Repo rules
|
|
62
|
+
|
|
63
|
+
- **Test-first (TDD).** Write the failing test, watch it fail, then write the
|
|
64
|
+
minimal code to pass. No production code without a failing test first.
|
|
65
|
+
- **Format and lint before committing:** `make fmt` and `make lint` must pass
|
|
66
|
+
(ruff is both formatter and linter here).
|
|
67
|
+
- **Keep comments and descriptions concise.** Docstrings, Makefile target
|
|
68
|
+
descriptions, workflow step names, and PR text should say what's needed in as
|
|
69
|
+
few words as possible — one tight sentence over a paragraph, and don't restate
|
|
70
|
+
what the code or name already conveys.
|
|
71
|
+
- **Prefer the standard library; justify every dependency.** The runtime deps
|
|
72
|
+
are intentionally few — `click` (command surface), `httpx` (HTTP; matches
|
|
73
|
+
merge-cli), and `tomlkit` (round-trip Codex `config.toml` without clobbering
|
|
74
|
+
the user's comments). Adding a dependency needs a reason in the PR.
|
|
75
|
+
- **Pin everything.** Runtime and dev deps are pinned to exact versions
|
|
76
|
+
(`==`) in `pyproject.toml`, and `uv.lock` hash-pins the full transitive tree —
|
|
77
|
+
commit it. GitHub Actions are pinned to full commit SHAs with a version
|
|
78
|
+
comment (e.g. `actions/checkout@<sha> # v4.2.2`); Dependabot proposes bumps.
|
|
79
|
+
No mutable major-tag action refs, no unpinned modules.
|
|
80
|
+
- **No secrets in the repo or logs.** Never print tokens or the `mg_` key.
|
|
81
|
+
Credentials live under `~/.mgw`, files written mode `0600`.
|
|
82
|
+
- **Thin client:** the durable contract is the control-plane API + the harness
|
|
83
|
+
config-file formats, not this CLI's internals. Keep commands small and keep
|
|
84
|
+
the harness writers behind a clear interface so new harnesses are additive.
|
|
85
|
+
- **Branching:** single `main` trunk — branch off `main`, open PRs into `main`.
|
|
86
|
+
There is no `develop` branch (a CLI releases from tags, not branch pushes).
|
|
87
|
+
Releases will be cut by tagging `main` (`vX.Y.Z` stable, `vX.Y.Z-rc.N`
|
|
88
|
+
pre-release) and published to PyPI.
|
|
89
|
+
- **Distribution:** PyPI package `merge-gateway` (command `mgw`), installable
|
|
90
|
+
via `uv tool install` / `pipx` / `pip`. `.github/workflows/publish.yml` runs
|
|
91
|
+
tests, `uv build`s and publishes with trusted publishing when a GitHub
|
|
92
|
+
**Release** is published — merging to `main` does not publish. Bump
|
|
93
|
+
`__version__` and `pyproject.toml` together, tag `vX.Y.Z`, cut the release.
|
|
94
|
+
- **Config writers must be safe:** always back up an existing config file and
|
|
95
|
+
merge (never clobber) before writing; re-running `setup` must be idempotent.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
AGENTS.md
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
.PHONY: help sync fmt lint tests run build clean
|
|
2
|
+
|
|
3
|
+
help: ## Show this help
|
|
4
|
+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
|
|
5
|
+
awk 'BEGIN {FS = ":.*?## "}; {printf " %-10s %s\n", $$1, $$2}'
|
|
6
|
+
|
|
7
|
+
sync: ## Install deps into .venv from the lockfile
|
|
8
|
+
uv sync --locked
|
|
9
|
+
|
|
10
|
+
fmt: ## Format code
|
|
11
|
+
uv run ruff format .
|
|
12
|
+
|
|
13
|
+
lint: ## Lint (ruff check + format check)
|
|
14
|
+
uv run ruff check .
|
|
15
|
+
uv run ruff format --check .
|
|
16
|
+
|
|
17
|
+
tests: ## Run the test suite
|
|
18
|
+
uv run pytest -q
|
|
19
|
+
|
|
20
|
+
run: ## Run the CLI, e.g. make run ARGS="--version"
|
|
21
|
+
uv run mgw $(ARGS)
|
|
22
|
+
|
|
23
|
+
build: ## Build the wheel/sdist
|
|
24
|
+
uv build
|
|
25
|
+
|
|
26
|
+
clean: ## Remove build and cache artifacts
|
|
27
|
+
rm -rf dist build .pytest_cache .ruff_cache
|
|
28
|
+
find . -type d -name __pycache__ -prune -exec rm -rf {} +
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: merge-gateway
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Merge Gateway CLI — route your coding agents (Claude Code, Codex) through Merge Gateway
|
|
5
|
+
Project-URL: Homepage, https://merge.dev
|
|
6
|
+
Project-URL: Repository, https://github.com/merge-api/merge-gateway-cli
|
|
7
|
+
Project-URL: Bug Tracker, https://github.com/merge-api/merge-gateway-cli/issues
|
|
8
|
+
Author-email: Merge <support@merge.dev>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
Keywords: claude-code,cli,codex,gateway,llm,merge
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Requires-Dist: click==8.4.2
|
|
20
|
+
Requires-Dist: httpx==0.28.1
|
|
21
|
+
Requires-Dist: tomlkit==0.15.1
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# merge-gateway-cli
|
|
25
|
+
|
|
26
|
+
`mgw` — the Merge Gateway CLI. Route your existing coding agents
|
|
27
|
+
(Claude Code, Codex) through [Merge Gateway](https://merge.dev) without editing
|
|
28
|
+
config files by hand.
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
pipx install merge-gateway # recommended (isolated env)
|
|
34
|
+
pip install merge-gateway # alternative
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## What it does
|
|
38
|
+
|
|
39
|
+
1. `mgw login` — sign in through your browser (loopback + PKCE), storing a
|
|
40
|
+
short-lived credential under `~/.mgw`.
|
|
41
|
+
2. `mgw setup <harness>` — mint a gateway API key and write the harness config
|
|
42
|
+
(`claude-code` → `~/.claude/settings.json`, `codex` → `~/.codex/config.toml`).
|
|
43
|
+
3. `mgw doctor` — confirm the harness routes through the gateway.
|
|
44
|
+
4. `mgw keys list|rm` — manage the keys mgw minted; `mgw logout` clears local state.
|
|
45
|
+
|
|
46
|
+
## No human at the keyboard? `mgw agent signup`
|
|
47
|
+
|
|
48
|
+
An AI agent can set itself up without anyone opening a browser:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
mgw agent signup # creates an organization, saves a key, writes the harness config
|
|
52
|
+
mgw doctor # confirms the gateway routes
|
|
53
|
+
mgw agent whoami # what the saved credential is for (validates it with the server)
|
|
54
|
+
mgw agent claim-url # a fresh claim link for your user (revokes the previous one)
|
|
55
|
+
mgw agent forget # drop the local credentials (nothing is revoked server-side)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`signup` prints a **claim URL**. The organization it created has nobody in it
|
|
59
|
+
and runs as a **sandbox** (a small lifetime budget, a daily request cap and a
|
|
60
|
+
cheap-model allowlist) until a person opens that link, signs up or logs in,
|
|
61
|
+
and becomes its admin — at which point the ordinary account flow (phone
|
|
62
|
+
verification, payment method) lifts the limits. The API key is written to
|
|
63
|
+
`~/.mgw/agent.json` with `0600` permissions and is never printed; pass `--json`
|
|
64
|
+
for machine-readable output (the key is excluded there too).
|
|
65
|
+
|
|
66
|
+
Signup is rate limited per address and fleet-wide; if it is refused, the
|
|
67
|
+
message says why. Re-running `signup` on a machine that already has agent
|
|
68
|
+
credentials is refused — use `whoami` to reuse them.
|
|
69
|
+
|
|
70
|
+
Set `MGW_CONTROL_PLANE_URL` / `MGW_GATEWAY_URL` to target a non-production
|
|
71
|
+
environment (e.g. `https://api-gateway-develop.merge.dev` for both).
|
|
72
|
+
|
|
73
|
+
## Development
|
|
74
|
+
|
|
75
|
+
We use [uv](https://docs.astral.sh/uv/).
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
uv sync --locked # create .venv from the lockfile
|
|
79
|
+
make run ARGS="--version" # run the CLI
|
|
80
|
+
make tests # run tests
|
|
81
|
+
make lint # ruff check + format check
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
See [AGENTS.md](./AGENTS.md) for repository conventions.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# merge-gateway-cli
|
|
2
|
+
|
|
3
|
+
`mgw` — the Merge Gateway CLI. Route your existing coding agents
|
|
4
|
+
(Claude Code, Codex) through [Merge Gateway](https://merge.dev) without editing
|
|
5
|
+
config files by hand.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pipx install merge-gateway # recommended (isolated env)
|
|
11
|
+
pip install merge-gateway # alternative
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## What it does
|
|
15
|
+
|
|
16
|
+
1. `mgw login` — sign in through your browser (loopback + PKCE), storing a
|
|
17
|
+
short-lived credential under `~/.mgw`.
|
|
18
|
+
2. `mgw setup <harness>` — mint a gateway API key and write the harness config
|
|
19
|
+
(`claude-code` → `~/.claude/settings.json`, `codex` → `~/.codex/config.toml`).
|
|
20
|
+
3. `mgw doctor` — confirm the harness routes through the gateway.
|
|
21
|
+
4. `mgw keys list|rm` — manage the keys mgw minted; `mgw logout` clears local state.
|
|
22
|
+
|
|
23
|
+
## No human at the keyboard? `mgw agent signup`
|
|
24
|
+
|
|
25
|
+
An AI agent can set itself up without anyone opening a browser:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
mgw agent signup # creates an organization, saves a key, writes the harness config
|
|
29
|
+
mgw doctor # confirms the gateway routes
|
|
30
|
+
mgw agent whoami # what the saved credential is for (validates it with the server)
|
|
31
|
+
mgw agent claim-url # a fresh claim link for your user (revokes the previous one)
|
|
32
|
+
mgw agent forget # drop the local credentials (nothing is revoked server-side)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`signup` prints a **claim URL**. The organization it created has nobody in it
|
|
36
|
+
and runs as a **sandbox** (a small lifetime budget, a daily request cap and a
|
|
37
|
+
cheap-model allowlist) until a person opens that link, signs up or logs in,
|
|
38
|
+
and becomes its admin — at which point the ordinary account flow (phone
|
|
39
|
+
verification, payment method) lifts the limits. The API key is written to
|
|
40
|
+
`~/.mgw/agent.json` with `0600` permissions and is never printed; pass `--json`
|
|
41
|
+
for machine-readable output (the key is excluded there too).
|
|
42
|
+
|
|
43
|
+
Signup is rate limited per address and fleet-wide; if it is refused, the
|
|
44
|
+
message says why. Re-running `signup` on a machine that already has agent
|
|
45
|
+
credentials is refused — use `whoami` to reuse them.
|
|
46
|
+
|
|
47
|
+
Set `MGW_CONTROL_PLANE_URL` / `MGW_GATEWAY_URL` to target a non-production
|
|
48
|
+
environment (e.g. `https://api-gateway-develop.merge.dev` for both).
|
|
49
|
+
|
|
50
|
+
## Development
|
|
51
|
+
|
|
52
|
+
We use [uv](https://docs.astral.sh/uv/).
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
uv sync --locked # create .venv from the lockfile
|
|
56
|
+
make run ARGS="--version" # run the CLI
|
|
57
|
+
make tests # run tests
|
|
58
|
+
make lint # ruff check + format check
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
See [AGENTS.md](./AGENTS.md) for repository conventions.
|