CLI reference - Embedder

The embedder binary provides an interactive terminal UI, two headless process modes, daemon controls, MCP configuration, remote bridge management, dashboards, and skill installation.

Running embedder with no arguments opens the interactive terminal UI. Only --server and --daemon are headless process modes.

Command tree

embedder
  status
  start daemon
  stop daemon
  monitor
  dashboard [slug]
  mcp
    add <name> <command-or-url>
    remove|rm <name>
    list|ls
  bridge
    discover
    pair <name|host:port>
    list|ls
    remove|rm <name>
    status
    doctor|verify [name]
    exec [options] <name> <command> [args...]
    start [--relay]
    stop
    install-service
  skill
    install <SKILL.md|https-url>

embedder --server [--listen [host]:port]
embedder --daemon [daemon options]

Run embedder without a command to open the terminal UI.

Global flags and process modes

Flag	Behavior
`-h`, `--help`	Prints top-level help and exits
`-v`, `--version`	Prints the package version when it is the first argument
`--server`	Starts the JSON-RPC server over stdio
`--listen [host]:port`	Adds a pinned WSS listener to `--server`; default `127.0.0.1:4851`
`--daemon`	Runs the long-lived backend-connected daemon in the foreground
`--agent-team`	Enables Agent Team execution for the process
`--subagent-hardware`	Allows newly spawned general subagents to use hardware tools
`--env <name>`	Selects `prod`, `st`, `staging`, `preview`, or `test`
`--pr-label <label>`	Selects the preview backend and app for a development PR label

If both process flags are present, --daemon wins because it is evaluated before --server.

`--listen` parsing

Use one of these forms:

# Default loopback address and port
embedder --server --listen

# Custom port on loopback
embedder --server --listen :4900

# Explicit address and port
embedder --server --listen 0.0.0.0:4900

The implementation does not parse a bare port. --listen 4900 falls back to 127.0.0.1:4851. Port 0 is accepted and lets the operating system choose an available port. The stdio transport stays active when --listen is set. Closing stdio stops a normal --server process, but a listening server remains alive until it receives SIGINT or SIGTERM.

Account status

embedder status

Prints the current plan and usage data. It reads EMBEDDER_AUTH_TOKEN before stored interactive credentials. The command exits with status 1 when authentication or the usage request fails.

Daemon commands

`embedder start daemon`

embedder start daemon [options]

Option	Default	Behavior
`--team <name>`	none	Restricts claims to a team; requires `--project`
`--project <name>`	none	Restricts claims to a project; requires `--team`
`--backend-url <url>`	selected environment	Overrides the daemon API and WebSocket host

The command starts a detached child with --daemon. It resolves authentication before spawning and reports an existing daemon instead of duplicating it.

`embedder --daemon`

embedder --daemon \
  [--backend-url <url>] \
  [--team <name> --project <name>]

This foreground entry point is what start daemon launches. It accepts stored daemon credentials or EMBEDDER_API_KEY; it does not prompt. --team-id and --project-id are internal paired flags passed by start daemon after name resolution. Provide both IDs or neither. The daemon verifies the IDs against the named team and project.

`embedder monitor`

embedder monitor

Opens the daemon monitor. It refreshes once per second.

Key	Action
`m`	Change the model when one daemon is listed
`Up`, `k`	Scroll up
`Down`, `j`	Scroll down
`PageUp`, `PageDown`	Scroll by a page
`Home`, `End`	Jump to the start or end
`q`, `Esc`, `Ctrl`+`C`	Close the monitor

`embedder stop daemon`

embedder stop daemon [--pid <positive-integer>]

Without --pid, the command stops the only active daemon in the current application directory. It requires a PID when several are listed.

Dashboard server

embedder dashboard [slug]

Serves project dashboards on a localhost URL and prints the address. When slug is present, the printed target ends in /d/<encoded-slug>. Press Ctrl+C to stop it.

MCP commands

Add a server

embedder mcp add <name> <command-or-url> [options]

Option	Values	Default
`-t`, `--transport`	`stdio`, `sse`, `http`	`stdio`
`-s`, `--scope`	`global`, `project`	`global`
`-e`, `--env <KEY=VALUE>`	Repeatable; stdio only	none
`-H`, `--header <KEY=VALUE>`	Repeatable; SSE or HTTP only	none

Examples:

embedder mcp add linear https://mcp.linear.app/mcp --transport http

embedder mcp add firecrawl npx -y firecrawl-mcp \
  --env 'FIRECRAWL_API_KEY=${FIRECRAWL_API_KEY}'

embedder mcp add lab http://lab.example.test/mcp \
  --transport http \
  --header 'Authorization=Bearer ${LAB_MCP_TOKEN}' \
  --scope project

For stdio, every positional argument after the name becomes part of the command string and is split on whitespace into command and args.

List servers

embedder mcp list
embedder mcp ls

Lists the merged global and current-project configuration. A project server with the same name replaces the global server in this view.

Remove a server

embedder mcp remove <name> [--scope global|project]
embedder mcp rm <name> [--scope global|project]

Removal defaults to the global file. Use --scope project to edit <current-directory>/.embedder/mcp.json. See MCP servers for OAuth, catalog entries, tool controls, and the configuration schema.

Bridge commands

Discover bridges

embedder bridge discover

Browses _embedder-bridge._tcp.local for 2.5 seconds and prints the address, bridge protocol version, mode, fingerprint, and pairing state.

Pair

embedder bridge pair <name|host:port> [--code <code>] [--name <local-name>]

name must match an mDNS instance. A direct address must include a port, such as 192.0.2.25:4849 or [2001:db8::25]:4849. If --code is absent, the CLI prompts for it. The local name defaults to the discovered name or direct host.

List and remove pairings

embedder bridge list
embedder bridge ls

embedder bridge remove <name>
embedder bridge rm <name>

Pairings are stored in ~/.embedder/bridges.json with mode 0600 where the platform supports it.

Probe status

embedder bridge status

Attempts a pinned, token-authenticated connection to every locally stored bridge and reports connected or unreachable.

Run diagnostics

embedder bridge doctor [name]
embedder bridge verify [name]

When no name is provided, the first stored pairing is used. The command checks:

Pinned connection and protocol handshake
Advertised capabilities
Serial-port enumeration
probe-rs
OpenOCD or J-Link GDB Server
File upload and download

The command exits nonzero if any check fails.

Execute a bridge command

embedder bridge exec [--shell] [--timeout <ms>] <name> <command> [args...]

The default timeout is 10 minutes. The bridge protocol caps execution at 30 minutes. Without --shell, the command is an argv array. --shell joins the arguments into a shell command. A bridge with a nonempty exec_allowlist rejects shell mode and rejects programs not named in the allowlist.

Start or stop the bundled bridge

embedder bridge start [--relay]
embedder bridge stop

start extracts and detaches the bundled embedder-bridge, binds it to 0.0.0.0:4849, and stores runtime state under the Embedder application directory. --relay adds the configured production relay URL when the bridge config is first created.

Install a system service

sudo embedder bridge install-service \
  [--state-dir <path>] \
  [--bin-dir <path>]

Linux and macOS are supported. The binary directory defaults to /usr/local/bin.

Platform	Default state	Config	Service
Linux	`/var/lib/embedder-bridge`	`/etc/embedder-bridge/config.toml`	`embedder-bridge.service`
macOS	`/usr/local/var/embedder-bridge`	`/usr/local/etc/embedder-bridge/config.toml`	`dev.embedder.bridge`

The generated service config binds to loopback and enables the relay. Existing config files are preserved. See Remote hardware bridge for service behavior and the embedder-bridge binary commands.

Install a skill

embedder skill install <SKILL.md|https-url> \
  [--user] \
  [--overwrite] \
  [--project-root <path>]

The default scope is the project rooted at the current directory or --project-root. --user installs into user scope. --overwrite permits replacement. Remote skill URLs must use HTTPS.

Environment variables

Authentication and backend selection

Variable	Used by
`EMBEDDER_AUTH_TOKEN`	JSON-RPC server, interactive backend calls, and `embedder status`; overrides stored login credentials
`EMBEDDER_API_KEY`	Daemon authentication
`EMBEDDER_API_URL`	Overrides the selected environment’s API base URL
`EMBEDDER_BACKEND_URL`	Daemon backend when `--backend-url` is absent
`EMBEDDER_TEAM`	Daemon team name; requires `EMBEDDER_PROJECT`
`EMBEDDER_PROJECT`	Daemon project name; requires `EMBEDDER_TEAM`

Runtime and daemon

Variable	Default	Effect
`EMBEDDER_APP_DIR`	`~/.embedder`	Moves application state, configs, credentials, worktrees, and extracted binaries
`EMBEDDER_DAEMON_CONCURRENCY`	`4`	Sets the shared GitHub and Slack worker count
`EMBEDDER_SERVER_BIN_PATH`	current binary	Overrides the child server binary used by the terminal client
`EMBEDDER_CLIENT_TYPE`	detected	Overrides client attribution when set to a recognized client type
`EMBEDDER_NO_TELEMETRY=1`	unset	Disables telemetry

MCP, providers, and certificates

Variable	Effect
`NODE_EXTRA_CA_CERTS`	Adds PEM certificate authorities for MCP HTTP, SSE, and OAuth requests
`${NAME}`	Expands a required environment value in MCP and local-model configuration
`${NAME:-fallback}`	Expands an environment value with a fallback
`OLLAMA_CONTEXT_LENGTH`	Sets Ollama’s server-side context limit; this is read by Ollama, not Embedder

Bridge logging

Variable	Effect
`EMBEDDER_BRIDGE_LOG`	Sets the Rust bridge tracing filter; default `info`

Development builds also read STAGING_TOKEN with staging and preview environments. It is not a production authentication variable.

​Command tree

​Global flags and process modes

​--listen parsing

​Account status

​Daemon commands

​embedder start daemon

​embedder --daemon

​embedder monitor

​embedder stop daemon

​Dashboard server

​MCP commands

​Add a server

​List servers

​Remove a server

​Bridge commands

​Discover bridges

​Pair

​List and remove pairings

​Probe status

​Run diagnostics

​Execute a bridge command

​Start or stop the bundled bridge

​Install a system service

​Install a skill

​Environment variables

​Authentication and backend selection

​Runtime and daemon

​MCP, providers, and certificates

​Bridge logging

Command tree

Global flags and process modes

`--listen` parsing

Account status

Daemon commands

`embedder start daemon`

`embedder --daemon`

`embedder monitor`

`embedder stop daemon`

Dashboard server

MCP commands

Add a server

List servers

Remove a server

Bridge commands

Discover bridges

Pair

List and remove pairings

Probe status

Run diagnostics

Execute a bridge command

Start or stop the bundled bridge

Install a system service

Install a skill

Environment variables

Authentication and backend selection

Runtime and daemon

MCP, providers, and certificates

Bridge logging