CLI Reference

Prerequisites

From the beebridge repo root (where beebridge.mjs lives):

npm run build:cli
node beebridge.mjs --help

If apps/cli/dist/index.js is missing, the root loader exits with a message to run npm run build:cli first.

Production vs development

By default, gateway start|restart and web start|restart run production scripts: npm run start:gateway (compiled dist/) and npm run start:web (next start). Run npm run build from the repo root first.

Pass --dev to use npm run dev:gateway (tsx) or npm run dev:web (next dev) instead — no production artifacts required for those.

Common commands

Command	Purpose
`gateway start` \| `restart`	Production gateway (`start:gateway`). `--dev` → `dev:gateway`. `--daemon` → background; logs under `.beebridge-daemon/gateway-<port>.log`
`web start` \| `restart`	Production web (`start:web`). `--dev` → `dev:web`. `--daemon`, `--open` (opens `/dashboard`)
`web settings`, `manager setup`	Open Settings in the browser; `--dev` optional
`stop`	SIGTERM anything on 4321 (gateway) and 3000 (web); override with `--gateway-port` / `--web-port`
`gateway token`	Print the current gateway auth token (same as `~/.beebridge/gateway-token` when auto-generated)
`onboard`	First-time PM auth / model setup
(no args) or `tui`	Keyboard-driven terminal UI

How to invoke

Form	Example
`node beebridge.mjs …`	`node beebridge.mjs gateway restart --daemon`
`npm run beebridge -- …`	`npm run beebridge -- gateway start --port 4321` (passes args after `--`)
`npm run …` shortcuts	See npm scripts below (same as `node beebridge.mjs …`)
Global `beebridge`	`npm link` at repo root, then `beebridge gateway restart --daemon`

Default Behavior

Running node beebridge.mjs with no subcommand launches the keyboard-driven terminal TUI. Same as node beebridge.mjs tui.

Environment Variables

Variable	Default	Purpose
`beebridge_HOME`	Repo root	Working directory for spawned gateway/web processes
`beebridge_GATEWAY_URL`	`http://localhost:4321`	Gateway HTTP base URL for API calls
`beebridge_GATEWAY_TOKEN`	(unset)	Bearer token; falls back to `GATEWAY_TOKEN`, then `~/.beebridge/gateway-token` if present
`PORT`	`4321` / `3000`	Listen port for gateway or web start commands

Daemon Mode (`-d` / `--daemon`)

gateway start, gateway restart, web start, and web restart all accept -d or --daemon. The CLI spawns the same npm script as foreground mode: production (start:gateway / start:web) unless you pass --dev (then dev:gateway / dev:web), detached from beebridge_HOME (repo root).

Examples

# Restart gateway on default port (4321), detached — logs under .beebridge-daemon/
node beebridge.mjs gateway restart --daemon

# Same with explicit port
node beebridge.mjs gateway restart --port 4321 --daemon

# Web UI in background on port 3000
node beebridge.mjs web start --daemon

# Restart web (kills process on port, then starts again)
node beebridge.mjs web restart --daemon

# Open browser when starting web in foreground (not used with --daemon)
node beebridge.mjs web start --open --port 3000

While detached:

Logs: .beebridge-daemon/gateway-<port>.log or .beebridge-daemon/web-<port>.log
PID file: .beebridge-daemon/gateway-<port>.pid or .beebridge-daemon/web-<port>.pid

gateway restart / web restart first stop whatever is listening on that port, then start again — useful after config changes.

npm scripts (repo root `package.json`)

These are thin wrappers around node beebridge.mjs …:

Script	Equivalent
`npm run gateway:start`	`node beebridge.mjs gateway start`
`npm run gateway:restart`	`node beebridge.mjs gateway restart`
`npm run gateway:start:daemon`	`node beebridge.mjs gateway start --daemon`
`npm run gateway:restart:daemon`	`node beebridge.mjs gateway restart --daemon`
`npm run web:start`	`node beebridge.mjs web start`
`npm run web:restart`	`node beebridge.mjs web restart`
`npm run web:start:daemon`	`node beebridge.mjs web start --daemon`
`npm run web:restart:daemon`	`node beebridge.mjs web restart --daemon`

Command Reference

`onboard`

Interactive first-time setup (PM auth, model, runtime).

Option	Description
`--install-daemon`	Include daemon install step
`-y`, `--yes`	Non-interactive with defaults

`job create`

Option	Description
`-g`, `--goal <goal>`	Required. Job description

`manager` — Project Manager AI

Subcommand	Options	Description
`plan`	`-g` goal, `-d` deadline, `-p` priority	Plan with goal
`ask`	`-g` goal	Create a job (alias)
`settings`	—	Print PM settings JSON
`setup`	`--tab` (`connection\|auth\|model\|workspace\|status`), `--port`, `--no-open`, `--dev`	Start web and open `/settings?tab=…` (`next start` unless `--dev`)

`manager auth`

Subcommand	Options	Description
`add`	`--provider`, `--mode`, `--secret`, `--label`	Add auth profile
`login`	`--provider`, `--label`, `--no-open`	OAuth/device login flow
`activate`	`--profile <id>`	Activate a profile
`remove`	`--profile <id>`	Delete a profile

`manager model`

Subcommand	Options	Description
`providers`	—	List provider catalog (JSON)
`set`	`--provider`, `--model`, `--allow`, `--fallback`	Set default model policy

`bee` — Worker Queue

Subcommand	Description
`run`	Run approved bee queue
`approvals`	List pending approvals
`approve -j <jobId>`	Approve a job

`flower`

Subcommand	Description
`status`	Flower / integration status

`gateway`

Runs npm run start:gateway (compiled gateway) from the repo root by default. Pass --dev for npm run dev:gateway (tsx). Default HTTP port 4321 (or PORT env / --port).

Subcommand	Options	Description
`start`	`--port <n>`, `--dev`, `-d` / `--daemon`	Foreground or background gateway
`restart`	Same	Stop process on port, then `start` again (e.g. pick up env changes)
`token`	—	Print current gateway Bearer token (see also `~/.beebridge/gateway-token`)

`web`

Runs npm run start:web (next start) by default. Pass --dev for npm run dev:web. Default web port 3000.

Subcommand	Options	Description
`start`	`-o` / `--open` (open `/dashboard`), `--port`, `--dev`, `-d` / `--daemon`	Next.js UI
`restart`	Same	Stop process on port, then start web again
`settings`	`--tab` (`connection\|auth\|model\|workspace\|status`), `--port`, `--no-open`, `--dev`	Same as `manager setup` — opens Settings

`tui`

Launch the terminal GUI explicitly.

Legacy Aliases

Command	Maps to
`project create -g`	`job create`
`task plan`	`manager plan`
`task run-approved`	`bee run`

Prerequisites

Production vs development

Common commands

How to invoke

Default Behavior

Environment Variables

Daemon Mode (-d / --daemon)

npm scripts (repo root package.json)

Command Reference

onboard

job create

manager — Project Manager AI

manager auth

manager model

bee — Worker Queue

flower

gateway

web

tui