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

# CLI reference

> Every ngram command and its flags.

## Entity commands

### `ngram create`

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

### `ngram talk <entity>`

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

```bash theme={"theme":"github-light-default"}
ngram talk canary
ngram talk canary --ollama              # start Ollama if needed
ngram talk canary --ollama --pull-models # also download models
```

### `ngram run <entity>`

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

```bash theme={"theme":"github-light-default"}
ngram run canary
ngram run canary --ollama
ngram run canary --ollama --pull-models
```

### `ngram worker <entity>`

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

### `ngram status <entity>`

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

### `ngram evolve <entity>`

Force one trait evolution cycle. For debugging and development.

### `ngram knowledge <entity>`

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

### `ngram journal <entity>`

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

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

Semantic search over episodic memory.

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

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

### `ngram export <entity> <dest_dir>`

Backup entity YAML and database to a directory.

### `ngram import <bundle_dir>`

Restore an entity from a backup bundle.

## Setup commands

### `ngram setup`

Guided local-first setup for inference, `.env`, and Entity creation. Cloudflare
and Railway are entered only through the explicit advanced hybrid profile.

```bash theme={"theme":"github-light-default"}
ngram setup                         # interactive; hosted is the fastest default
ngram setup --profile hosted        # provider API, local Entity runtime
ngram setup --profile local         # Ollama, local Entity runtime
ngram setup --profile hybrid        # advanced protected gateway + Railway
```

| 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. Hosted setup
supports managed providers including OpenAI and Venice plus custom
OpenAI-compatible endpoints.

### `ngram lab up <entity> --lan`

One-command thin-host + Quest bootstrap. On first run it configures hosted chat
and embeddings, creates the authenticated loopback Entity bridge, installs the
locked WebXR workspace, runs readiness probes, and starts Entity + WebXR under
one foreground supervisor. Later runs reuse the secret-free lab profile.

```bash theme={"theme":"github-light-default"}
ngram lab up rook --lan
ngram lab doctor rook
ngram lab run rook --lan
ngram lab setup rook --provider venice
ngram lab setup rook --provider custom --base-url https://gpu.example/v1
```

`--lan` exposes only the HTTPS WebXR surface and requires confirmation that the
network is trusted. The Entity bridge remains loopback-only. `--configure`
replaces an existing profile; `--skip-provider-check` is available for offline
setup but removes the preflight guarantee. See [Quest lab](/deployment/quest-lab).

### `ngram stop`

Stop local ngram 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 |

### `ngram api`

Start the HTTP health API.

```bash theme={"theme":"github-light-default"}
ngram api --host 0.0.0.0 --port 8080
```

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

## Gateway commands

### `ngram gateway setup`

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

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

### `ngram 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>