Product Brain

https://productbrain.io/docs
Admin
Product Brain is a governed knowledge graph that stores product decisions and context, enabling...
Tokens:19,316
Snippets:308
Trust Score:3.7
Update:2 days ago
Show doc for...
Tokens:
Raw
### Verify pb CLI installation

Source: https://productbrain.io/docs/install

Run these commands to confirm the CLI is installed and view help information.

```bash
pb --version
pb --help
```

--------------------------------

### Install pb CLI globally

Source: https://productbrain.io/docs/cli/overview

Install the pb CLI globally using npm. The package is @productbrain/cli at the beta tag.

```bash
npm install -g @productbrain/cli@beta
```

--------------------------------

### First useful pb call

Source: https://productbrain.io/docs/install

Runs the orient command to initialize the CLI after installation.

```bash
pb orient --task "first orient after install"
```

--------------------------------

### Start a session

Source: https://productbrain.io/docs/cli/write-commands

Opens a session before write-heavy work.

```bash
pb session start
```

--------------------------------

### Start a write session prompt

Source: https://productbrain.io/docs/quickstart

Use this prompt to start a session when work will change code, product decisions, or reusable knowledge. In MCP-connected tools, the agent can do this for you.

```text
Start a session. I am working on onboarding.
```

--------------------------------

### pb session start

Source: https://productbrain.io/docs/cli/generated-reference

Opens a tracked write session.

```APIDOC
## pb session start

### Description
Open a tracked write session.

### Command
`pb session start`
```

--------------------------------

### Start a task with Codex

Source: https://productbrain.io/docs/integrations/codex

Instruct Codex to use Product Brain to orient and start a session before making changes.

```text
Use Product Brain to orient for this task and start a session before making changes.
```

--------------------------------

### orient

Source: https://productbrain.io/docs/mcp/generated-reference

Orient tool with actions: record-activation, start, task. Should be called first before substantive work.

```APIDOC
## orient

### Description
Orient tool with actions: record-activation, start, task. Should be called first before substantive work.

### Actions
- `record-activation`
- `start`
- `task`

### Source
`packages/mcp-server/src/tools/orient.ts`
```

--------------------------------

### Common pb CLI workflow loop

Source: https://productbrain.io/docs/cli/overview

A typical sequence of pb commands: orient with a task description, start a session, capture a decision, and close the session.

```bash
pb orient --task "Describe the task"
pb session start
pb capture "DEC: ..."
pb session close
```

--------------------------------

### Authenticate pb CLI

Source: https://productbrain.io/docs/install

Starts the authentication flow for the Product Brain CLI. Requires a Product Brain API key (pb_sk_…) from the app.

```bash
pb login
```

--------------------------------

### orient

Source: https://productbrain.io/docs/mcp/knowledge-tools

Load workspace and task context first. Actions: start (session opener), task (mid-session refresh), record-activation.

```APIDOC
## orient

### Description
Load workspace + task context first. Actions: `start` (session opener), `task` (mid-session refresh), `record-activation`.

### Actions
- **start** - Session opener
- **task** - Mid-session refresh
- **record-activation** - Record activation
```

--------------------------------

### workflows

Source: https://productbrain.io/docs/mcp/generated-reference

Workflows tool with actions: checkpoint, get-run, list, load-skill, start. Manages workflows.

```APIDOC
## workflows

### Description
Workflows tool with actions: checkpoint, get-run, list, load-skill, start.

### Actions
- `checkpoint`
- `get-run`
- `list`
- `load-skill`
- `start`

### Source
`packages/mcp-server/src/tools/workflows.ts`
```

--------------------------------

### chain

Source: https://productbrain.io/docs/mcp/generated-reference

Chain tool (module-gated) with actions: create, edit, get, list, version.commit, version.diff, version.history, version.list, version.revert. Requires PB_MODULES=core,gitchain.

```APIDOC
## chain

### Description
Chain tool (module-gated) with actions: create, edit, get, list, version.commit, version.diff, version.history, version.list, version.revert.

### Requires
`PB_MODULES=core,gitchain`

### Actions
- `create`
- `edit`
- `get`
- `list`
- `version.commit`
- `version.diff`
- `version.history`
- `version.list`
- `version.revert`

### Source
`packages/mcp-server/src/tools/gitchain.ts`
```

--------------------------------

### pb get <id>

Source: https://productbrain.io/docs/cli/generated-reference

Retrieves the full entry including data, relations, and history.

```APIDOC
## pb get <id>

### Description
Full entry: data, relations, history.

### Command
`pb get <id>`

### Arguments
- `<id>` (string) - Required - The entry identifier.
```

--------------------------------

### session

Source: https://productbrain.io/docs/mcp/generated-reference

Session tool with actions: close, commit-constellation, resume, start, status, wrapup-commit, wrapup-review. Manages session lifecycle and facilitation.

```APIDOC
## session

### Description
Session - Lifecycle & Facilitation

### Actions
- `close`
- `commit-constellation`
- `resume`
- `start`
- `status`
- `wrapup-commit`
- `wrapup-review`

### Source
`packages/mcp-server/src/tools/session.ts`
```

--------------------------------

### entries

Source: https://productbrain.io/docs/mcp/knowledge-tools

Manage entries with actions: list, get, batch, search, update, commit, history, move, verify. Optional filters: collection, status, label, tag, query.

```APIDOC
## entries

### Description
Manage entries. Actions: `list`, `get`, `batch`, `search`, `update`, `commit`, `history`, `move`, `verify`. Optional filters: `collection`, `status`, `label`, `tag`, `query`.

### Actions
- **list** - List entries
- **get** - Get an entry
- **batch** - Batch operations
- **search** - Search entries
- **update** - Patch an entry (writes need session + scope)
- **commit** - Promote a draft with validation — **human confirms** in consensus workspaces
- **history** - Audit trail for an entry
- **move** - Move `entryId` to `toCollection` slug
- **verify** - Mark an entry verified (lightweight, no codebase scan)

### Filters
- **collection** - Filter by collection
- **status** - Filter by status
- **label** - Filter by label
- **tag** - Filter by tag
- **query** - Filter by query
```

--------------------------------

### Claude Code prompt for using Product Brain

Source: https://productbrain.io/docs/integrations/claude

Ask Claude Code to use Product Brain for orientation, session start, and capturing decisions or tensions. Claude Code can translate this into terminal commands when needed.

```text
Use Product Brain to orient for this task, start a session, and capture durable decisions or tensions as we work.
```

--------------------------------

### pb search "onboarding"

Source: https://productbrain.io/docs/cli/read-commands

Searches for items matching the given query.

```bash
pb search "onboarding"
```

--------------------------------

### pb get DEC-123

Source: https://productbrain.io/docs/cli/read-commands

Retrieves a specific item by its ID (e.g., DEC-123).

```bash
pb get DEC-123
```

--------------------------------

### pb orient [-b]

Source: https://productbrain.io/docs/cli/generated-reference

Provides a workspace overview. Use -b for a brief output and --task for task-grounded context.

```APIDOC
## pb orient [-b]

### Description
Workspace overview. Use `-b` for brief output, `--task` for task-grounded context.

### Command
`pb orient [-b]`

### Options
- `-b` (flag) - Optional - Brief output.
- `--task` (string) - Optional - Task-grounded context.
```

--------------------------------

### Run MCP server via npx

Source: https://productbrain.io/docs/pb-and-mcp

Run the `@productbrain/mcp` package using npx for stdio. Use for MCP hosts like Cursor, Claude, or ChatGPT tools.

```bash
npx @productbrain/mcp@beta
```

--------------------------------

### Upgrade or uninstall pb CLI

Source: https://productbrain.io/docs/install

Upgrade to the latest beta version or uninstall the CLI completely.

```bash
npm install -g @productbrain/cli@beta
npm uninstall -g @productbrain/cli
```

--------------------------------

### Recommended .cursorrules snippet

Source: https://productbrain.io/docs/integrations/cursor

Add this snippet to your .cursorrules file to instruct the agent to use Product Brain before substantive edits and to manage sessions.

```text
Before substantive edits, use Product Brain (MCP or pb) to orient for the current task and respect captured DEC/STD/TEN context. Start a session before writes; close it when done.
```

--------------------------------

### Run pb handshake

Source: https://productbrain.io/docs/cli/handshake

Executes the handshake command to write local agent instructions and Product Brain context files into the repository. Re-run after upgrades during early access.

```bash
pb handshake
```

--------------------------------

### Prompt to use Product Brain MCP in Cursor

Source: https://productbrain.io/docs/integrations/cursor

After configuring MCP and restarting Cursor, ask this to have the agent use Product Brain MCP for orientation.

```text
Use Product Brain MCP to orient for the task we're about to do.
```

--------------------------------

### pb orient --task "Describe the task"

Source: https://productbrain.io/docs/cli/read-commands

Orients the CLI to a specific task. Use this before making changes to understand the context.

```bash
pb orient --task "Describe the task"
```

--------------------------------

### Run pb doctor

Source: https://productbrain.io/docs/cli/doctor

Use this command to diagnose CLI configuration and connectivity. It is currently in early access.

```bash
pb doctor
```

--------------------------------

### Capture, update, relate, and accept entries

Source: https://productbrain.io/docs/cli/write-commands

Commands to capture knowledge, update an entry, relate entries, and accept an entry.

```bash
pb capture "DEC: chose X because Y"
```

```bash
pb update DEC-123
```

```bash
pb relate DEC-123 belongs_to PROD-6
```

```bash
pb entry accept DEC-123
```

--------------------------------

### pb context WP-123

Source: https://productbrain.io/docs/cli/read-commands

Shows the context for a specific work item (e.g., WP-123).

```bash
pb context WP-123
```

--------------------------------

### First prompt to orient with Product Brain

Source: https://productbrain.io/docs/integrations/chatgpt

Use this prompt in a new ChatGPT chat to ask Product Brain to orient for a task. Replace the ellipsis with your task description.

```plaintext
Use Product Brain to orient for this task: "..."
```

--------------------------------

### capture

Source: https://productbrain.io/docs/mcp/knowledge-tools

Create entries — single (name, description, optional data) or batch (action=batch, items[]).

```APIDOC
## capture

### Description
Create entries — single (`name`, `description`, optional `data`) or batch (`action=batch`, `items[]`).

### Parameters
- **name** (string) - Required - Name of the entry
- **description** (string) - Required - Description of the entry
- **data** (object) - Optional - Additional data
- **action** (string) - Optional - Set to `batch` for batch creation
- **items[]** (array) - Optional - Array of items for batch creation
```

--------------------------------

### pb glossary

Source: https://productbrain.io/docs/cli/generated-reference

Displays key Product Brain CLI terms.

```APIDOC
## pb glossary

### Description
Key Product Brain CLI terms.

### Command
`pb glossary`
```

--------------------------------

### context

Source: https://productbrain.io/docs/mcp/generated-reference

Context tool with actions: brief, build, chain, changes, cross-cut, gather, incremental, last-verified-brief, neighborhood. Provides context-related operations.

```APIDOC
## context

### Description
Context tool with actions: brief, build, chain, changes, cross-cut, gather, incremental, last-verified-brief, neighborhood.

### Actions
- `brief`
- `build`
- `chain`
- `changes`
- `cross-cut`
- `gather`
- `incremental`
- `last-verified-brief`
- `neighborhood`

### Source
`packages/mcp-server/src/tools/context.ts`
```

--------------------------------

### Orient before work prompt

Source: https://productbrain.io/docs/quickstart

Use this prompt to instruct your agent to orient from the Chain before substantive work. Orientation loads relevant decisions, tensions, standards, and active work for the task.

```text
Use Product Brain to orient before we work on the onboarding flow.
```

--------------------------------

### MCP configuration in .cursor/mcp.json

Source: https://productbrain.io/docs/integrations/cursor

Create or merge this JSON block in .cursor/mcp.json, replacing YOUR_API_KEY with a key from Settings → API keys. Restart Cursor after saving.

```json
{
  "mcpServers": {
    "productbrain": {
      "url": "https://mcp.productbrain.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

--------------------------------

### question

Source: https://productbrain.io/docs/mcp/generated-reference

Question tool with actions: adopt, answer, assign, create, decline, force-close, list, snooze. Manages questions.

```APIDOC
## question

### Description
Question tool with actions: adopt, answer, assign, create, decline, force-close, list, snooze.

### Actions
- `adopt`
- `answer`
- `assign`
- `create`
- `decline`
- `force-close`
- `list`
- `snooze`

### Source
`packages/mcp-server/src/tools/question.ts`
```

--------------------------------

### MCP Authentication Header

Source: https://productbrain.io/docs/mcp/overview

Authenticate with a workspace key using the Authorization header. Replace pb_sk_your_workspace_key with your actual key.

```text
Authorization: Bearer pb_sk_your_workspace_key
```

--------------------------------

### Refresh agent context with Codex

Source: https://productbrain.io/docs/integrations/codex

Ask Codex to refresh local Product Brain context when the repository needs current agent instructions.

```text
Refresh the Product Brain handshake before continuing.
```

--------------------------------

### pb fields decisions

Source: https://productbrain.io/docs/cli/read-commands

Displays the fields available for decisions.

```bash
pb fields decisions
```

--------------------------------

### pb scoreboard [--task <task>] [--json]

Source: https://productbrain.io/docs/cli/generated-reference

Shows the flywheel health board with M1/M2/M3 metrics, materialization age, and diagnosis. Use --json for the structured agent shape.

```APIDOC
## pb scoreboard [--task <task>] [--json]

### Description
Flywheel health board: M1/M2/M3 metrics, materialization age, and diagnosis. `--json` for the structured agent shape.

### Command
`pb scoreboard [--task <task>] [--json]`

### Options
- `--task` (string) - Optional - Task identifier for context.
- `--json` (flag) - Optional - Output in structured JSON format.
```

--------------------------------

### pb entry accept <id>

Source: https://productbrain.io/docs/cli/generated-reference

Accepts a draft entry onto the Chain (commit to SSOT).

```APIDOC
## pb entry accept <id>

### Description
Accept a draft entry onto the Chain (commit to SSOT).

### Command
`pb entry accept <id>`

### Arguments
- `<id>` (string) - Required - The entry identifier.
```

--------------------------------

### pb capture "<text>"

Source: https://productbrain.io/docs/cli/generated-reference

Captures knowledge and auto-classifies it to the right collection.

```APIDOC
## pb capture "<text>"

### Description
Capture knowledge. Auto-classifies to the right collection.

### Command
`pb capture "<text>"`

### Arguments
- `<text>` (string) - Required - The text to capture.
```

--------------------------------

### chain-review

Source: https://productbrain.io/docs/mcp/generated-reference

Chain Review tool (module-gated) with actions: branch.conflicts, branch.create, branch.list, branch.merge, comment, gate, list-comments, resolve-comment. Requires PB_MODULES=core,gitchain.

```APIDOC
## chain-review

### Description
Chain Review tool (module-gated) with actions: branch.conflicts, branch.create, branch.list, branch.merge, comment, gate, list-comments, resolve-comment.

### Requires
`PB_MODULES=core,gitchain`

### Actions
- `branch.conflicts`
- `branch.create`
- `branch.list`
- `branch.merge`
- `comment`
- `gate`
- `list-comments`
- `resolve-comment`

### Source
`packages/mcp-server/src/tools/gitchain.ts`
```

--------------------------------

### Capture changes prompts

Source: https://productbrain.io/docs/quickstart

Use these prompts to capture decisions, tensions, or insights as they appear. The human says what changed; the agent handles the tool call.

```text
Save a decision: user-visible work ships behind feature flags until rollout confidence is high.

Save a tension: mobile auth still breaks during uncontrolled rollouts.

Save an insight: users drop at step 3 when they hit an unfinished onboarding flow.
```

--------------------------------

### relations

Source: https://productbrain.io/docs/mcp/generated-reference

Relations tool with actions: batch-create, create, delete, dismiss, find, suggest. Manages relations.

```APIDOC
## relations

### Description
Relations tool with actions: batch-create, create, delete, dismiss, find, suggest.

### Actions
- `batch-create`
- `create`
- `delete`
- `dismiss`
- `find`
- `suggest`

### Source
`packages/mcp-server/src/tools/relations.ts`
```

--------------------------------

### Close the loop prompt

Source: https://productbrain.io/docs/quickstart

Use this prompt to close the session so the next agent or teammate inherits current context.

```text
Close the Product Brain session and summarize what changed.
```

--------------------------------

### relations

Source: https://productbrain.io/docs/mcp/knowledge-tools

Create or manage typed edges. Actions: create, batch-create, dismiss, delete, find, suggest.

```APIDOC
## relations

### Description
Create or manage typed edges. Actions: `create`, `batch-create`, `dismiss`, `delete`, `find`, `suggest`.

### Actions
- **create** - Create a relation
- **batch-create** - Batch create relations
- **dismiss** - Dismiss a relation
- **delete** - Delete a relation
- **find** - Find relations
- **suggest** - Suggest relations
```

--------------------------------

### pb collections list

Source: https://productbrain.io/docs/cli/generated-reference

Lists all collections with field counts.

```APIDOC
## pb collections list

### Description
All collections with field counts.

### Command
`pb collections list`
```

--------------------------------

### workspace

Source: https://productbrain.io/docs/mcp/generated-reference

Workspace tool with actions: audit, check, proposals-count, proposals-list, proposals-respond, self-test, status, usage, whoami. Manages workspace operations.

```APIDOC
## workspace

### Description
Workspace tool with actions: audit, check, proposals-count, proposals-list, proposals-respond, self-test, status, usage, whoami.

### Actions
- `audit`
- `check`
- `proposals-count`
- `proposals-list`
- `proposals-respond`
- `self-test`
- `status`
- `usage`
- `whoami`

### Source
`packages/mcp-server/src/tools/workspace.ts`
```

--------------------------------

### Authorization Header for MCP

Source: https://productbrain.io/docs/mcp/authentication

Send this header with your pb_sk_... API key to authenticate with the MCP server. Use read or read-write keys depending on your needs.

```http
Authorization: Bearer pb_sk_your_key
```

--------------------------------

### pb doctor

Source: https://productbrain.io/docs/cli/generated-reference

Checks configuration and connectivity.

```APIDOC
## pb doctor

### Description
Check configuration and connectivity.

### Command
`pb doctor`
```

--------------------------------

### pb fields <collection>

Source: https://productbrain.io/docs/cli/generated-reference

Shows field definitions for a collection.

```APIDOC
## pb fields <collection>

### Description
Field definitions for a collection.

### Command
`pb fields <collection>`

### Arguments
- `<collection>` (string) - Required - The collection name.
```

--------------------------------

### capture

Source: https://productbrain.io/docs/mcp/generated-reference

Capture tool with actions: batch, capture. Used for capturing data.

```APIDOC
## capture

### Description
Capture tool with actions: batch, capture.

### Actions
- `batch`
- `capture`

### Source
`packages/mcp-server/src/tools/smart-capture.ts`
```

--------------------------------

### shape

Source: https://productbrain.io/docs/mcp/generated-reference

Shape tool with actions: agree, dismiss, list, show. Manages shapes.

```APIDOC
## shape

### Description
Shape tool with actions: agree, dismiss, list, show.

### Actions
- `agree`
- `dismiss`
- `list`
- `show`

### Source
`packages/mcp-server/src/tools/shape.ts`
```

--------------------------------

### pb session close

Source: https://productbrain.io/docs/cli/generated-reference

Closes the session and shows a summary.

```APIDOC
## pb session close

### Description
Close session, show summary.

### Command
`pb session close`
```
Tokens:
Raw