Command line

Every bogen command, from bogen --help and the code behind it. From a checkout the command is node packages/server/dist/cli.js.

Commands that talk to the server (open, mcp, snapshot, import, export-folder, import-folder, git, live, phone, and peer except deploy) start it in the background when it is not running, unless BOGEN_URL points elsewhere. --port (or -p) picks the port for any of them, and --token the token of a server that needs one.

Running the server

bogen serve

bogen serve [--port 29990] [--host <addr> --token <secret>] [--tailnet]

Runs the server in the foreground until Ctrl+C. Prints its address and data folder.

Option	What it does
`--port`, `-p`	The port. Default 29990, or `BOGEN_PORT`.
`--host <addr>`	Listen on this address instead of `127.0.0.1`. Any address beyond this machine needs a token.
`--token <secret>`	Require `Authorization: Bearer <secret>` (or `/?token=<secret>` once in a browser). `BOGEN_TOKEN` works too.
`--tailnet`	Also listen on this machine's Tailscale address, for device sync.
`--insecure-allow-any-host`	Let `peer pair` and `peer add` use addresses outside the tailnet. For testing.
`--dev`	For working on Bogen itself, with the editor's development server.

bogen start, stop, status

bogen start [--port 29990] [--host <addr>]
bogen stop
bogen status

start runs the server in the background and prints its version, address and process id. When a user service bogen.service is installed, it starts that service instead. stop stops the background server. status prints the address, version, process id, number of files and active agents, and says when the running server is another build than the command or a paired device runs another version. It exits 3 when the server is not running.

bogen open

Opens the editor in your browser, starting the server if needed. With a token, the address carries it.

bogen mcp

MCP over stdio, for agents. It relays to the server's /mcp, starts the server if needed, and keeps calls going across a reconnect. This is the command bogen install registers.

Agents

bogen install

bogen install <claude-code|codex|cursor|vscode|opencode|gemini|zed>... | --all

Adds Bogen to MCP clients, and for Claude Code and Codex writes the Bogen skill. --all (or all) sets up every client found on this machine and skips the rest. Prints one line per client: ok, skip or FAIL, and exits 1 if one failed. See Agents.

bogen uninstall

bogen uninstall <client>...

Takes Bogen out of the named clients, skill included. A skill file Bogen did not write stays.

bogen live

bogen live <dev server url> --dir <project folder>

Opens a dev server on this machine in live site mode: pick elements and have claude or codex edit the project's source. The address must be plain http on localhost or 127.0.0.1, and --dir the folder of one project.

Checking the setup

bogen doctor

bogen doctor [--json]

Checks the whole setup and prints the fix for each problem. Changes nothing. Exits 1 when a check failed. With the phone on, it also checks the phone listener, its port in tailscale serve, the allowed logins, and whether the tailnet policy lets each of your phones reach that port. See Troubleshooting.

Capture and import

bogen snapshot

bogen snapshot <url> [--file <id>] [--page <name>] [--name <artboard>] [--width 1440] [--height 900] [--scheme dark|light] [--no-fonts]
bogen snapshot --site <url> [--widths 1440,768,390] [--schemes dark,light] [--limit 30] [--file <id>] [--name <file name>] [--no-fonts]

Copies a page, or a whole site with one page per route, onto the canvas as editable layers. A single page prints its result as JSON; a site prints its progress and a report, and exits 1 when it failed. See Snapshot.

Option	What it does
`--file <id>`	Add to this file. Without it, a new file.
`--page <name>`	One page: the page in that file.
`--name <name>`	One page: the artboard's name. A site: the new file's name.
`--width`, `--height`	One page: the viewport, 200 to 4000. Defaults 1440 and 900.
`--scheme dark\|light`	One page: the colour scheme.
`--site <url>`	Capture the whole site.
`--widths`	A site: widths, comma separated. Default 1440.
`--schemes`	A site: `dark`, `light` or both. Default dark.
`--limit`	A site: the most routes. Default 30, at most 200.
`--no-fonts`	Do not keep the page's self-hosted fonts.

bogen import figma

bogen import figma <file url> [--token <figma token>] [--save-token] [--name <file name>]

Imports a Figma file or frame through Figma's REST API with your personal access token, from --token, FIGMA_TOKEN, or one saved before. --save-token keeps it in config.json, readable by you only. See Import from Figma.

Design folders and Git

bogen export-folder, import-folder, diff

bogen export-folder <file id or name> <folder>
bogen import-folder <folder> [--name <name>]
bogen diff <folder A> <folder B> [--json]

Write a file as a folder of text, make a new file from such a folder, and show what changed between two folders. See History.

bogen git

bogen git init <file> <dir>
bogen git commit <file> [<dir>] [--message <text>]
bogen git log <file> [<dir>] [--limit <n>]
bogen git restore <file> [<dir>] [--rev <commit>]

Keeps a file's design folder in a real Git repository. init makes or uses the repository and binds the file to it; afterwards <dir> can be left out. -m is short for --message. log shows 50 commits unless --limit says otherwise. Bogen runs no prompts or hooks and never pushes.

Devices

bogen peer

bogen peer pair [--name <this device>] [--json]
bogen peer add <url> --token <t> [--name <n>]
bogen peer list [--json]
bogen peer status [--json]
bogen peer remove <id>
bogen peer tailnet <on|off>
bogen peer deploy <ssh-host> [--dry-run] [--port <port>]

Command	What it does
`pair`	Turns on the Tailscale listener and prints what the other device runs to pair with this one. `--name` names this device.
`add`	Pairs with another device, both ways. The token can come from `BOGEN_PEER_TOKEN` instead of `--token`.
`list`	Paired devices with their ids.
`status`	This device and each paired one: state, last sync, pending changes, bytes in and out, last error, version, and who has a file open there.
`remove`	Stops syncing with a device.
`tailnet`	Turns the Tailscale listener on or off, and saves it.
`deploy`	Copies this build to another Omarchy device over ssh, installs it, restarts it and reports its version. `--dry-run` changes nothing.

See Devices.

bogen phone

bogen phone on [--login <a,b>] [--https-port 29443] [--phone-port 29991] [--json]
bogen phone off
bogen phone pair [--json]
bogen phone list [--json]
bogen phone remove <id>
bogen phone status [--json]

Command	What it does
`on`	Starts the phone listener on 127.0.0.1:29991 and saves that, so the service starts it again after a restart. Runs `tailscale serve --bg --https=29443 http://127.0.0.1:29991` unless that port already goes there, and leaves it alone if another app uses it. Prints the address, a QR code of it, and what your tailnet policy has to allow. `--login` sets which Tailscale logins may connect; by default only the owner of this computer. `--https-port` and `--phone-port` pick other ports.
`off`	Stops the listener, saves that, and takes this one port out of `tailscale serve`. Paired phones stay paired.
`pair`	Makes a pairing code that works once, for ten minutes, and prints it with a QR code of the address.
`list`	Paired phones with their ids and when each was last seen.
`remove`	Revokes a phone. Its token stops working and its open connections close at once.
`status`	On or off, the address, `tailscale serve`, the allowed logins, the paired phones, and whether the tailnet policy lets your phones in.

See iPhone and iPad.

Omarchy

bogen omarchy install [--dry-run] [--no-service] [--no-plugin] [--no-hypr] [--tailnet]
bogen omarchy uninstall [--dry-run]

Runs the Omarchy installer or uninstaller that comes with this build. See Omarchy.

Other

Command	What it does
`bogen version`, `--version`, `-v`	Prints the version with its build, such as `0.1.0+4448e40`.
`bogen help`, `--help`, `-h`, or no command	Prints the usage.

Environment

Variable	What it does
`BOGEN_HOME`	The data folder. Default `$XDG_DATA_HOME/bogen`, else `~/.local/share/bogen`.
`BOGEN_PORT`	The port. Default 29990.
`BOGEN_URL`	For `mcp`, `status` and `open`: use a server elsewhere, without starting one.
`BOGEN_TOKEN`	Bearer token, instead of `--token`.
`BOGEN_BROWSER`	Path to a Chromium-based browser.
`BOGEN_NO_SANDBOX`	`1` starts the browser without its sandbox, for containers without user namespaces.
`BOGEN_FFMPEG`	Path to ffmpeg for video and AVIF, or `none` to use only the browser.
`BOGEN_EXPORT_DIR`	Where `export_file` writes. Default `~/Downloads/Bogen`.
`BOGEN_ALLOWED_ORIGINS`	Extra browser origins the server accepts, comma separated.
`FIGMA_TOKEN`	For `import figma`: your Figma personal access token.
`BOGEN_PEER_TOKEN`	For `peer add`: the other device's token, to keep it off the command line.
`OPENAI_API_KEY`, `GEMINI_API_KEY`	Your own keys, for image generation.
`CODEX_HOME`	Where `install` and `uninstall` find Codex's config and skill. Default `~/.codex`.