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

# CLI reference

> Every bumblebee command and its flags.

## Entity commands

### `bumblebee create`

Interactive genesis wizard. Creates a new entity YAML file in `configs/entities/`.

### `bumblebee talk <entity>`

CLI conversation with no daemon. Direct 1:1 chat in the terminal.

```bash theme={null}
bumblebee talk canary
bumblebee talk canary --ollama              # start Ollama if needed
bumblebee talk canary --ollama --pull-models # also download models
```

### `bumblebee run <entity>`

Daemon mode. Starts the heartbeat, soma, memory consolidation, initiative, and every platform in entity YAML.

```bash theme={null}
bumblebee run canary
bumblebee run canary --ollama
bumblebee run canary --ollama --pull-models
```

### `bumblebee worker <entity>`

Daemon + platforms without CLI REPL. Intended for Railway worker containers.

### `bumblebee status <entity>`

Show emotional state, drives, paths, and runtime info.

### `bumblebee evolve <entity>`

Force one trait evolution cycle. For debugging and development.

### `bumblebee knowledge <entity>`

Create or open `knowledge.md` in `$EDITOR`.

### `bumblebee journal <entity>`

Create or open `journal.md` in `$EDITOR`.

### `bumblebee recall <entity> "<query>"`

Semantic search over episodic memory.

### `bumblebee wipe <entity> [--yes]`

Clear rolling chat history and wipe SQLite/Postgres memory. Destructive — prompts for confirmation unless `--yes` is passed.

### `bumblebee export <entity> <dest_dir>`

Backup entity YAML and database to a directory.

### `bumblebee import <bundle_dir>`

Restore an entity from a backup bundle.

## Setup commands

### `bumblebee setup`

Guided setup wizard for `.env`, home stack, Railway, and entity creation.

```bash theme={null}
bumblebee setup                        # interactive (asks which profile)
bumblebee setup --profile hybrid       # hybrid Railway setup
bumblebee setup --profile local        # local-only setup
```

| Flag                      | Effect                                                    |
| ------------------------- | --------------------------------------------------------- |
| `--gateway-host`          | Gateway bind host for tunnel config (default `127.0.0.1`) |
| `--gateway-port`          | Gateway port (default `8010`)                             |
| `--skip-tunnel-bootstrap` | Do not offer automated Cloudflare tunnel + DNS + config   |

See [Setup & onboarding](/onboarding) for the full wizard flow. The wizard can optionally configure **OpenRouter** or **Venice** for harness testing ([Hosted inference (testing)](/deployment/hosted-inference-testing)).

### `bumblebee stop`

Stop local Bumblebee processes, gateway, and Ollama.

| Flag                     | Effect                      |
| ------------------------ | --------------------------- |
| `--dry-run`              | Show what would be stopped  |
| `--skip-gateway`         | Don't run gateway shutdown  |
| `--leave-ollama-running` | Keep Ollama alive           |
| `--tunnel-name NAME`     | Tunnel name for gateway off |

### `bumblebee api`

Start the HTTP health API.

```bash theme={null}
bumblebee api --host 0.0.0.0 --port 8080
```

Requires: `pip install 'bumblebee[api]'`

## Gateway commands

### `bumblebee gateway setup`

Interactive gateway configuration: tunnel, token, `.env`, optional stack start.

Flags: `--tunnel-name`, `--cloudflared-config`, `--gateway-host`, `--gateway-port`, `--skip-tunnel-bootstrap`

### `bumblebee gateway on | off | status | restart`

Control the home inference stack (Ollama + gateway + cloudflared).

| Command   | What it does             |
| --------- | ------------------------ |
| `on`      | Start all three services |
| `off`     | Stop all three           |
| `status`  | Check what's running     |
| `restart` | Off then on (2s pause)   |

Flags for `on`/`status`/`restart`: `--tunnel-name`, `--cloudflared-config`, `--tunnel-url`, `--gateway-host`, `--gateway-port`

Flags for `off`/`restart`: `--leave-ollama-running`

<Note>
  `gateway on | off | status | restart` run **`scripts/gateway.ps1`** on Windows and **`scripts/gateway.sh`** on macOS and Linux. `gateway setup` works on any OS.
</Note>