knowbrain-cli

Command-line tool kb for KnowBrain (spaces, stores, tasks, search, and related APIs). Contributors: conventions, logging, and layout are documented in AGENTS.md.

Install

From npm (Node 20+):

npm install -g knowbrain-cli

The kb executable is provided by the package bin field (dist/kb.js).

From the monorepo (development):

pnpm --filter knowbrain-cli build
pnpm link --global -C apps/cli

Configuration

• KB_BASE_URL — Service origin for auth and API routing (default https://mozidesk.com). Override per invocation: kb --base-url https://your-host space list.
• KB_API_PATH_PREFIX — Path prefix for resource APIs under the origin (default /api/knowbrain). Set to an empty string to call the OMI server directly (for example KB_BASE_URL=http://127.0.0.1:7654 with KB_API_PATH_PREFIX=).
• KB_SPACE / KB_TASK — Default space and task ids (same as --space / --task). Resolution order for space: --space → KB_SPACE → login credentials → public. KB_SPACE overrides the space id stored by kb login.
• KB_API_KEY / --api-key — API key sent as the x-api-key header (CloudX Better Auth api-key plugin). Takes precedence over kb login bearer credentials, so headless/agent callers (CI, sandboxed agents) can authenticate without a browser flow. On 401, the CLI surfaces API_KEY_INVALID instead of AUTH_REQUIRED/AUTH_EXPIRED to signal key rotation rather than re-login.
• --log-level — Log verbosity to stderr only (error, warn, info, debug).

Sign in

kb login    # device authorization in the browser; stores ~/.config/kb/credentials.json
kb logout   # remove stored credentials

Run kb login before other commands when the API requires authentication. Progress and links are printed to stderr; successful login leaves stdout empty.

For headless/agent use, set KB_API_KEY (and KB_SPACE) instead of running kb login:

export KB_BASE_URL=http://localhost:7655
export KB_API_PATH_PREFIX=/api/knowbrain
export KB_SPACE=user-space-id
export KB_API_KEY=cx_system_key_for_user
kb store list

Agent skill

Install the bundled knowbrain-kb skill into Codex, Claude Code, OpenCode, or generic agent directories:

kb onboard              # interactive plan + confirmation on stderr
kb onboard -y           # skip confirmation
kb version              # JSON: { "version": "..." }

Skill source: apps/cli/skills/knowbrain-kb/SKILL.md (included in the npm package). Build stamps version: from package.json.

Optional: standalone binaries

For machines without Node, you can ship a single-file executable (e.g. pkg, bun build --compile) in CI and attach artifacts to GitHub Releases—one build per OS/architecture. That path is not wired in this repository by default.