# Bridge command line reference

> Every command, flag and environment variable of the DiceyTable MCP bridge, plus the ports it uses, where it keeps your key, and how versions work.

- Question: What commands and flags does the DiceyTable bridge accept?
- Source: https://diceytable.com/docs/ai-agents/reference/bridge-cli
- Last verified: 2026-10-09

The bridge is the small program that links your AI agent to a DiceyTable tab. Its npm package is
`@diceytable/mcp-bridge`, and the command it installs is `diceytable-mcp-bridge`. With `npx`, run it like this:

```sh
npx -y @diceytable/mcp-bridge@1 [command] [options]
```

Your MCP client starts the bridge for you, so most people only ever type `login` and `doctor`. This page lists
everything else for when you need it. To set the bridge up the first time, see
[install the DiceyTable MCP bridge](https://diceytable.com/docs/ai-agents/setup/install).

## Commands

| Command | What it does |
|---|---|
| *(none)*, or `serve` | Runs the MCP server over stdio. Your MCP client starts this; you never run it by hand. It stops when the client closes its input. |
| `login` | Reads an access key at a hidden prompt, or from the first line of input (`echo dtpat_… \| npx -y @diceytable/mcp-bridge@1 login`). It checks the key with DiceyTable and saves it for the API in `--api`. Then it prints the account, the key's name, its permissions and its expiry date. Exits with status 1 if the key is malformed or refused. |
| `logout` | Removes the saved key for `--api`, or every saved key with `--all`. Warns you if `DICEYTABLE_TOKEN` is still set. |
| `status` | Shows which key is in use (its name and first characters, never the whole key), where it came from, the account, and whether a hub is running on `--port`. |
| `doctor` | Checks your Node.js version, each hub port, the key, whether the API answers, your clock, and the allowed folders. Then it prints browser hints. Exits with status 1 when any check fails. |
| `help`, `--help`, `-h` | Prints usage, every flag and every environment variable. |
| `version`, `--version`, `-v` | Prints the bridge version. |

An unknown command or flag prints an error and exits with status 2.

## Flags

A flag that takes a value accepts `--flag value` or `--flag=value`. A flag on the command line wins over its
environment variable.

| Flag | Environment variable | Default | What it does |
|---|---|---|---|
| `--port <n>` | `DICEYTABLE_BRIDGE_PORT` | `47621` | The hub port on your computer. If another program holds it, the bridge tries the next one, up to 47625. The site can reach only **47621 to 47625**, so a port outside that range never connects. `doctor` warns about it. |
| `--relay` | | off | Use **only** DiceyTable's relay server. The bridge opens no hub on your computer. |
| `--no-relay` | | off | Never open the relay. Tabs must reach the hub on your computer, so Safari can't pair. You can't pass both `--relay` and `--no-relay`. |
| `--dev` | | off | Also accept tabs from a local development site (`http://127.0.0.1:5173` and `http://localhost:5173`), and point the connect link at that site. Unless you pass `--api` or set `DICEYTABLE_API`, it also switches the API to `http://127.0.0.1:8787`. |
| `--allow-origin <origin>` | | | Also accept tabs from this exact origin, such as a preview build (`https://pr-12.onrender.com`). Repeatable. It must be a bare origin with no path, query or password. It must use `https`, except `http` for a loopback address. |
| `--allow-dir <dir>` | | | Also allow local files in this folder, for `asset_import` with `localPath` and for screenshot `saveTo`. Repeatable. A relative path starts from the working folder. The folder your MCP client started in is always allowed. |
| `--api <url>` | `DICEYTABLE_API` | `https://api.diceytable.com` (`http://127.0.0.1:8787` with `--dev`) | The DiceyTable API address. It must use `https`, except `http` for a loopback address. Keys are saved per API, so `login` with a different `--api` saves a separate key. |
| `--client-name <name>` | | your MCP client's own name | The agent name DiceyTable shows in the consent dialog, the indicator and Settings. The bridge keeps the first 64 characters. The AI badge other players see shows at most 32. |
| `--log-level <level>` | `DICEYTABLE_LOG_LEVEL` | `info` | `silent`, `error`, `warn`, `info` or `debug`. Logs go to **stderr** only, because stdout carries the MCP messages. |
| `--all` | | | For `logout` only: remove the keys for every API. |
| `--help` | | | Same as the `help` command. |
| `--version` | | | Same as the `version` command. |

## Environment variables

| Variable | Meaning |
|---|---|
| `DICEYTABLE_TOKEN` | Your access key (`dtpat_…`). It **wins over the saved key**, except for a loopback API (`127.0.0.1` or `localhost`). There it is not sent unless `DICEYTABLE_TOKEN_ALLOW_DEV=1`, so a real key never goes to whatever program is listening on that port. Set it through your client's variable syntax, never as plain text in a shared config. See [API keys](https://diceytable.com/docs/ai-agents/setup/api-keys). |
| `DICEYTABLE_TOKEN_ALLOW_DEV` | `1` lets `DICEYTABLE_TOKEN` be sent to a loopback API. Leave it unset unless the key really belongs to that local server. |
| `DICEYTABLE_BRIDGE_PORT` | Same as `--port`. |
| `DICEYTABLE_API` | Same as `--api`. |
| `DICEYTABLE_LOG_LEVEL` | Same as `--log-level`. |

## Where does the bridge save my key?

`login` saves one key per API address in a credentials file:

| System | File |
|---|---|
| Windows | `%APPDATA%\diceytable\credentials.json` |
| macOS and Linux | `~/.config/diceytable/credentials.json` (or under `$XDG_CONFIG_HOME` if you set it). Only your user can read the file or its folder. |

The bridge writes nothing else to disk, except images you ask it to save with `saveTo`.

## Which ports does the bridge use?

![The first bridge holds port 47621 as the hub; other bridges relay through it, and tabs scan ports 47621 to 47625](https://diceytable.com/assets/build/bridge-cli--hub-ports-ce3SBlPY.svg "**Ports.** The first bridge becomes the hub; the rest share it.")

| Connection | Direction | What it is for |
|---|---|---|
| `ws://127.0.0.1:47621` (to 47625) | Tabs connect **in** | The hub. It listens on `127.0.0.1` only, so other computers can't reach it. It checks every tab's origin against an exact list. Messages are capped at 8 MB. |
| `https://api.diceytable.com/api/agent/*` | The bridge connects **out** | Checking your key, starting and ending a session, a heartbeat every 30 seconds, and URL imports. |
| `wss://api.diceytable.com/agent-relay` | The bridge connects **out** | The relay. It opens once a session exists, unless you pass `--no-relay`. Messages are capped at 2 MB, so screenshots shrink to about 400 KB over it. |

**Several bridges at once.** Every MCP client runs its own bridge. The first one to need the port becomes the
**hub**. Each later bridge checks that the port really belongs to a DiceyTable hub, then connects through it as a
**relay client**. If the hub's client closes, the others race to take over the port in under a second, and tabs
reconnect by themselves. No bridge outlives its MCP client. [How the bridge works](https://diceytable.com/docs/ai-agents/concepts/how-it-works)
explains the hub and the relay in plain words.

## Which bridge version do I need?

Any 1.x bridge works with the site today. `@1` in the `npx` line always fetches the newest 1.x release.

- The npm major version (`@1`) matches the major version of the protocol the bridge and the site speak. If they don't
  match, the tab says *"Your DiceyTable bridge is too old"* (or *too new*) and names the `npx` line to run.
- Smaller protocol additions are agreed when the tab connects, so any 1.x bridge works with any 1.x site.
- Tools are matched **by name**. If the site has a tool your bridge doesn't know, the agent can still reach it with
  [`page_call_tool`](https://diceytable.com/docs/ai-agents/reference/tools/sessions#pagecalltool). If your bridge lists a tool the site lacks, the call
  returns `tool-unavailable` and names the site version it needs.
- After a new major version ships, the site keeps accepting the old one for at least 90 days.
- Each release's changes are in the package's `CHANGELOG.md`.

## Related

- [Fix an agent that won't connect](https://diceytable.com/docs/ai-agents/troubleshooting/connection): `doctor` warnings, ports and version
  errors.
- [Which local files an agent can read](https://diceytable.com/docs/ai-agents/concepts/local-file-access): what `--allow-dir` opens up.
- [AI agent limits and quotas](https://diceytable.com/docs/ai-agents/reference/limits): every size and rate cap in one place.