CLI reference

Every beamd command, grouped by role, with the global flags and JSON output that drive scripts and agents.

beamd is one binary with two roles' worth of commands — the client commands you run on your laptop, and the edge commands an operator runs on the server. Run beamd help for the built-in summary, or beamd <command> --help for a command's flags.

Client commands

What developers run day to day.

Command	What it does
`beamd open <port>`	Expose a local port as a public URL. Foreground by default; `-d` detaches.
`beamd close <name>`	Remove a detached tunnel. Idempotent.
`beamd run [name] -- <cmd>`	Run a dev server and expose it in one step. See Wrap a dev server.
`beamd list`	List detached tunnels.
`beamd status`	Show account + scope + agent + connection status.
`beamd login`	Authenticate against an edge.
`beamd logout`	Remove an account.
`beamd accounts`	List the edges you're logged into (`*` marks current).
`beamd orgs` (alias `scopes`)	List the orgs the current account can act in.
`beamd default [scope]`	Show or set your default scope.
`beamd whoami`	Show the resolved account + scope.
`beamd check`	Verify credentials against the edge — no tunnel, no agent.
`beamd reload`	Restart the background agent with fresh credentials.
`beamd mcp`	Run the MCP stdio server. See MCP server.
`beamd version`	Print the version.

Edge commands

What an operator runs on the server — see Self-hosting.

Command	What it does
`beamd serve`	Run the edge server (reads `/etc/beamd/beamd.yaml` by default).
`beamd init`	Interactively write a `beamd.yaml` + an empty `tokens.json`.
`beamd add-developer`	Issue a token for a slug, provision DNS + cert, and print the token.
`beamd provision-dev`	Write DNS + pre-warm a cert for a slug (low-level; `add-developer` wraps it).

Common flags

Most client commands accept these:

Flag	Applies to	Effect
`--as <name>`	`open`, `run`	Literal subdomain label.
`--from <source>`	`open`, `run`	Derive the label (`port`·`dir`·`repo`·`branch`·`worktree`). See Naming.
`-d`, `--detach`	`open`	Hand the tunnel to the background agent and return immediately.
`--server <edge>`	most client commands	One-off edge override (or set `BEAMD_SERVER`).
`--scope <org>`	`open`, `run`, …	One-off scope override (hosted).
`--config <path>`	client + `serve`	Use a dedicated config file. For client automation it holds `{server, token}`; for the edge it's the server config path. See Embed in your app.
`--json`	`open`, `list`, `close`, `status`	Machine-readable output (see below).

Bare-port shorthand

beamd <port> is shorthand for beamd open <port>:

beamd 3000          # same as: beamd open 3000

JSON output

Add --json to open / list / close / status to get exactly one JSON object or array and nothing else — the path scripts and agents should use:

beamd open 3000 --as api -d --json
# {"url":"https://api.beam.example.com","name":"api","port":3000,"slug":"","baseDomain":"beam.example.com"}

Always read the url field rather than assembling the host yourself — it's correct whether the edge is flat or namespaced. More patterns in Examples & recipes and the Agent local API.