CLI Overview

The NimbleBrain runtime launches with bun. There are two entry points: bun run start starts the production HTTP API server, and bun run dev runs the same server in development mode with file watching and web HMR.

The runtime has no terminal client. You interact with a running instance through the web app it serves and the /mcp endpoint (for external MCP clients) — not from the shell. Bundles, skills, credentials, and automations are managed from the web UI and the agent’s tool actions, not from subcommands.

Usage

bun run start                            # production HTTP server
bun run dev                              # development mode (watch + web HMR)
bun run src/cli/index.ts serve [flags]   # explicit form (config / production)

Entry points

Command	Description
bun run start	Start the HTTP API server (production entry point)
bun run dev	Start development mode (API with watch + web HMR)

Flags

The server and dev mode share most flags:

Flag	Commands	Description
--config <path>, -c	serve, dev	Path to a nimblebrain.json config file
--port <number>	serve, dev	HTTP server port (default: 27247)
--model <name>	serve	Override the default model (e.g., claude-sonnet-4-6)
--debug	serve, dev	Verbose event logging to stderr
--no-web	dev	Skip the web dev server (API only)

The working directory is set with the NB_WORK_DIR environment variable, not a flag. bun run src/cli/index.ts boots the server directly; a leading serve token is accepted (the deploy command passes it) but optional.

See Running the server and Dev mode for each command’s full flag set.

Config resolution

NimbleBrain loads its configuration from a nimblebrain.json file. The CLI resolves the config path using this priority:

Priority	Source	Path
1	--config / -c flag	Exactly the path you specify
2	Project-local directory	./.nimblebrain/nimblebrain.json (used only when it exists)
3	Default work directory	<NB_WORK_DIR>/nimblebrain.json, where NB_WORK_DIR defaults to ~/.nimblebrain
4	Current directory	./nimblebrain.json

Both bun run start and bun run dev default to the same global work directory at ~/.nimblebrain. bun run dev starts the server (bun run src/cli/index.ts serve) under the hood, so it inherits that default unless you override it with --config or NB_WORK_DIR.

If no config file exists at the resolved path, NimbleBrain auto-creates one with defaults:

nimblebrain.json

{
  "$schema": "https://schemas.nimblebrain.ai/v1/nimblebrain-config.schema.json",
  "version": "1"
}

CLI flags override values from the config file. For example, --model claude-sonnet-4-6 overrides whatever defaultModel is set in your config.

Exit codes

Code	Meaning
0	Success
1	Runtime error
2	Usage error (bad flags, missing arguments)

Related commands

• Running the server — production HTTP server
• Dev mode — development mode