Product Brain CLI (pb)

Chain knowledge + write-back in the terminal. Read, search, capture, and update your product knowledge graph.

Requirements: Node 18+, API key from Product Brain Settings (pb_sk_*).

Install

npm install -g @productbrain/cli@beta

From source (latest main):

git clone https://github.com/synergyai-os/Product-OS.git
cd Product-OS && npm ci
cd packages/cli && npm run build && npm install -g .

Login

pb login

Paste your API key (pb_sk_...). Saved to ~/.config/productbrain/.env.

Or run any command without a key and follow the guided flow.

Onboarding link (pb connect)

If you received a connect token (pb_ct_...) from Product Brain:

pb connect pb_ct_...

Redemption always targets a cloud Convex deployment (HTTP Actions are cloud-hosted, even during local dev). Resolution order: --gateway → PB_CONNECT_GATEWAY_URL → CONVEX_SITE_URL → production default (gateway.productbrain.io).

• Dev deployments: Set CONVEX_SITE_URL to your *.convex.site URL, or use --gateway.
• If a token fails, the CLI hints about setting CONVEX_SITE_URL or using --gateway.

Quick Start

# 1. Check your setup
pb doctor

# 2. Orient — see where things stand
pb orient -b

# 3. Read an entry
pb get BET-123

# 4. Search the Chain
pb search "onboarding flow"

# 5. Start a write session and capture knowledge
pb session start
pb capture "DEC: chose X because Y"
pb capture "TEN: blocked by missing API"
pb session close

Running pb with no arguments shows contextual guidance based on your setup state.

Commands

Read (no session required)

| Command | Description | |---------|-------------| | pb orient [-b] | Workspace overview. -b for brief, --task for task-grounded context. | | pb get <id> | Full entry: data, relations, history. | | pb search <query> | Full-text search across all collections. | | pb context <id> | Constellation context for an entry. | | pb fields <collection> | Field definitions for a collection. | | pb constellation <id> | Entry + all related entries grouped by relation type. | | pb collections list | All collections with field counts. | | pb glossary | Key Product Brain CLI terms. | | pb scoreboard [--json] | Flywheel health board: M1/M3/M4/M5 metrics, materialization age, and diagnosis. --json for the structured agent shape. | | pb doctor | Check configuration and connectivity. |

Write (session required)

| Command | Description | |---------|-------------| | pb session start | Open a tracked write session. | | pb capture "<text>" | Capture knowledge. Auto-classifies to the right collection. | | pb update <id> | Update fields on an existing entry. | | pb relate <from> <type> <to> | Add a typed relation between entries. | | pb entry accept <id> | Accept a draft entry onto the Chain (commit to SSOT). | | pb entry archive <id> --reason <reason> | Archive an entry with a DEC-1572 reason. | | pb session close | Close session, show summary. |

Profile Management

Config is read from (in order): environment variables, ~/.config/productbrain/.env, .env.mcp in the current directory.

pb login          # Save API key
pb doctor         # Verify configuration
pb setup          # Guided first-time setup

AI Developer Onboarding

pb handshake      # Generate context files for Codex, Cursor, Claude, Copilot

Generates AGENTS.md, CLAUDE.md, .cursor/rules/chain.mdc, .productbrain/context.md, and more.

Output Modes

WP-744 / 1e-B: piping alone no longer switches modes — the human-readable card is the default in every shell, TTY or not. Ask for JSON explicitly.

| Context | Output | |---------|--------| | TTY (terminal) | Human-readable formatting | | Piped / non-TTY (no flag, PB_JSON unset) | Human-readable formatting | | PB_JSON=1 | JSON | | --json | Force JSON | | --pretty | Force human-readable |

Reference

• pb --help for full command list
• pb <command> --help for command-specific options
• pb glossary for key terms
• Chain: WP-302 (CLI Maturity)