> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Reference for the Embedder CLI commands, headless process modes, flags, subcommand aliases, and environment variables recognized by the binary.

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

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

## Command tree

```text theme={"system"}
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:

```bash theme={"system"}
# 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

```bash theme={"system"}
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`

```bash theme={"system"}
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`

```bash theme={"system"}
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`

```bash theme={"system"}
embedder monitor
```

Opens the daemon monitor. It refreshes once per second.

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

### `embedder stop daemon`

```bash theme={"system"}
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

```bash theme={"system"}
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 <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop it.

## MCP commands

### Add a server

```bash theme={"system"}
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:

```bash theme={"system"}
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

```bash theme={"system"}
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

```bash theme={"system"}
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](/integrations/mcp-servers) for OAuth, catalog entries, tool controls, and the configuration schema.

## Bridge commands

### Discover bridges

```bash theme={"system"}
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

```bash theme={"system"}
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

```bash theme={"system"}
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

```bash theme={"system"}
embedder bridge status
```

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

### Run diagnostics

```bash theme={"system"}
embedder bridge doctor [name]
embedder bridge verify [name]
```

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

1. Pinned connection and protocol handshake
2. Advertised capabilities
3. Serial-port enumeration
4. `probe-rs`
5. OpenOCD or J-Link GDB Server
6. File upload and download

The command exits nonzero if any check fails.

### Execute a bridge command

```bash theme={"system"}
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

```bash theme={"system"}
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

```bash theme={"system"}
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](/integrations/remote-bridge) for service behavior and the `embedder-bridge` binary commands.

## Install a skill

```bash theme={"system"}
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` |

<Note>
  Development builds also read `STAGING_TOKEN` with staging and preview environments. It is not a production authentication variable.
</Note>