CLI reference

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.

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.

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.

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 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.

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.

`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.

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

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.

Reference

Project

CLI reference

Entity commands

`ngram create`

`ngram talk <entity>`

`ngram run <entity>`

`ngram worker <entity>`

`ngram status <entity>`

`ngram evolve <entity>`

`ngram knowledge <entity>`

`ngram journal <entity>`

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

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

`ngram export <entity> <dest_dir>`

`ngram import <bundle_dir>`

Setup commands

`ngram setup`

`ngram lab up <entity> --lan`

`ngram stop`

`ngram api`

Gateway commands

`ngram gateway setup`

`ngram gateway on | off | status | restart`

​Entity commands

​ngram create

​ngram talk <entity>

​ngram run <entity>

​ngram worker <entity>

​ngram status <entity>

​ngram evolve <entity>

​ngram knowledge <entity>

​ngram journal <entity>

​ngram recall <entity> "<query>"

​ngram wipe <entity> [--yes]

​ngram export <entity> <dest_dir>

​ngram import <bundle_dir>

​Setup commands

​ngram setup

​ngram lab up <entity> --lan

​ngram stop

​ngram api

​Gateway commands

​ngram gateway setup

​ngram gateway on | off | status | restart

Entity commands

`ngram create`

`ngram talk <entity>`

`ngram run <entity>`

`ngram worker <entity>`

`ngram status <entity>`

`ngram evolve <entity>`

`ngram knowledge <entity>`

`ngram journal <entity>`

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

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

`ngram export <entity> <dest_dir>`

`ngram import <bundle_dir>`

Setup commands

`ngram setup`

`ngram lab up <entity> --lan`

`ngram stop`

`ngram api`

Gateway commands

`ngram gateway setup`

`ngram gateway on | off | status | restart`