BrainAPI CLI

For the complete BrainAPI documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL. Docs MCP: /docs/mcp.

BrainAPI CLI

Install, configure, and run BrainAPI locally with the official brainapi-tui package and brainapi binary

The BrainAPI CLI is the official [email protected] npm package: a Node.js terminal CLI (built with @clack/prompts) that installs the brainapi binary and configures and runs BrainAPI on your machine.

Instead of manually cloning the repo, creating a venv, writing .env, starting Docker, and running uvicorn/Celery, you run a small global command.

npm install -g [email protected]   # installs `brainapi` on PATH

This is not the same binary as bin/brainapi in the repo root, which is a Python entry point for plugin management (src/core/plugins/cli.py).

Managed install layout

The CLI keeps a managed install under ~/.brainapi/ (or $BRAINAPI_HOME):

Path	Purpose
`~/.brainapi/source/`	Cloned `brainapi2` repo
`~/.brainapi/source/.venv/`	Python virtualenv
`~/.brainapi/source/.env`	Generated configuration
`~/.brainapi/state.json`	Install metadata (repo URL, branch, chosen services, etc.)

Commands

Full bootstrap:

Ensures Python ≥ 3.11 and Docker (with recovery flows if missing).
Clones the repo ($BRAINAPI_REPO_URL, branch $BRAINAPI_BRANCH or main).
Creates the venv and installs Python deps (including extras based on your choices).
Runs the setup wizard and writes .env.
Optionally installs plugins (registry or local paths).
Optionally starts Docker Compose for backing services (Postgres, Redis, Neo4j, Milvus, Mongo, etc.).

brainapi init

Options: -r/--repo, -b/--branch, -f/--force (re-init even if state exists).

If you run any other command first (start, doctor, …), it auto-runs init when no install exists.

Setup wizard

Both init and config walk you through:

Defaults vs custom stack (e.g. NetworkX + Postgres + pgvector + remote GCP Vertex).
Vector DB, data DB, graph DB, and models mode (local Ollama vs remote providers).
Remote chat providers include OpenAI-compatible options such as DeepSeek (chat only — embeddings stay on another provider). See Installation → DeepSeek.
Pipeline (OCR, accurate vs lightweight ingestion via PIPELINE_MODE). Observations and graph consolidation default off unless you enable them in .env.
Search: enable /retrieve/search, then choose hybrid BM25+dense (default), dense only, or BM25 only. Search requires DATA_DB=postgresql; the wizard leaves it disabled for other data stores.
Connection details for only the services you picked.
Services runtime: Docker Compose vs manual (you run services yourself).
BRAINPAT_TOKEN (generate or paste).
Plugins (search/install, e.g. chatbot).
Whether to bring up containers now.

Search choices written by the wizard

Wizard choice	`SEARCH_ENABLED`	`SEARCH_USE_DENSE`	`SEARCH_USE_BM25`
Disabled (default)	`false`	`true`	`true`
Both fused	`true`	`true`	`true`
Dense only	`true`	`true`	`false`
BM25 only	`true`	`false`	`true`

The wizard also writes SEARCH_FUSION=rrf, SEARCH_FUSION_ALPHA=0.5, SEARCH_BM25_K1=1.2, SEARCH_BM25_B=0.75, and CONTEXT_PASSAGE_MODE=hybrid. Re-run brainapi config and select Search (BM25 + dense) to change the selection later.

The <200 ms p50 target shown by the wizard excludes the query-embedding RTT and describes the default, unpersonalized Search path—not catalog mode or a cross-encoder plugin.

Typical end-user flow

npm install -g [email protected]
brainapi init          # first time
brainapi start         # daily dev / local server
brainapi doctor        # troubleshoot
brainapi config        # change DB/models/plugins
brainapi update        # pull latest BrainAPI

Environment overrides

Prop

Type

Developing the TUI itself

cd tui
npm install
npm run dev              # watch build
node dist/index.js init  # or: npm start -- init

Mental model

brainapi (TUI)  →  ~/.brainapi/source/  →  Python BrainAPI (API, MCP, worker, plugins)
                 ↑
         interactive prompts + Docker + .env

The TUI is ops/dev ergonomics: it does not implement graph logic or chatbot inference. It gets BrainAPI running locally with the right .env and processes. The chatbot plugin and MCP server are started by brainapi start as separate processes (API on 8000, MCP on 8001).

Relation to `bin/brainapi`

Entry	Tech	Role
`brainapi-tui` → `brainapi`	Node	Install, configure, start stack
`bin/brainapi`	Python	Plugin CLI inside an already-set-up project

For a fresh machine, you typically use the TUI first. Once ~/.brainapi/source exists, you can also work inside that tree with Poetry / bin/brainapi for plugin-specific tasks.

BrainAPI CLI

On this page