Brief CLI Setup Guide

Why Use the Brief CLI?

The Brief CLI (@briefhq/cli) gives you terminal access to everything in Brief — product context, decisions, documents, personas, signals, and more.

Use Case	How the CLI Helps
Quick lookups	brief decisions search "auth" is faster than opening a browser
AI coding agents	Any agent with shell access can call Brief — no MCP config needed
Scripting & automation	Pipe JSON output into your own tools with --json and --jq
Decision validation	brief ask --mode check "..." before you build

CLI vs. MCP

The CLI and Brief MCP access the same API and provide the same capabilities. Choose whichever fits your workflow:

• MCP — Direct protocol integration for editors with MCP support (Cursor, Claude Code, Windsurf, VS Code)
• CLI — Works from any terminal and with any AI agent that has shell access. No protocol configuration needed.

You can use both at the same time.

---

Installation

Install globally with npm:

npm install -g @briefhq/cli

Or run without installing using npx:

npx @briefhq/cli@latest status

Verify the installation:

brief --version

---

Authentication

Log in with your Brief account using OAuth:

brief login

This opens your browser for authentication. Once complete, your credentials are stored securely and tokens refresh automatically.

Check your connection status:

brief status

To switch workspaces (if you belong to multiple organizations):

brief workspace

To log out:

brief logout

---

Core Commands

brief ask

Ask Brief anything about your product. This is the primary command — Brief's AI agent has access to your decisions, personas, research signals, documents, and connected integrations (Linear, GitHub, Notion, Slack, etc.).

# Get strategic guidance
brief ask "What auth pattern should we use?"

# Validate an approach against existing decisions
brief ask --mode check "We plan to switch to Redis for caching"

# Ask with working context
brief ask --context "refactoring the billing module" "What decisions apply here?"

# Continue a conversation
brief ask -c <conversation-id> "What are the risks?"

Modes:

• advise (default) — Open-ended strategic guidance grounded in your org's context
• check — Validates your approach against existing decisions, returning conflict analysis

During long-running queries, brief ask shows real-time progress — you'll see which tools Brief's agent is using (e.g., "Using search_decisions...") and when each completes.

brief decisions

Search, create, and manage product decisions.

# Search decisions
brief decisions search "authentication"

# List recent decisions
brief decisions list

# Record a new decision
brief decisions create --decision "Use Postgres over MongoDB" --rationale "Relational data model fits our needs"

# Get details on a specific decision
brief decisions get D-42

# Confirm or reject a pending decision
brief decisions confirm D-42
brief decisions reject D-42 --reason "Superseded by D-45"

brief docs

Search, read, and create documents.

# Search documents
brief docs search "onboarding flow"

# Browse the folder tree
brief docs browse

# Read a specific document
brief docs read <document-id>

# Create a new document (get folder ID from browse first)
brief docs create --title "API Design" --folder <folder-id> --content "# API Design\n\n..."

# Import local markdown files
brief docs import ./specs/

brief context

View your comprehensive product context — company info, goals, velocity metrics, and team data.

brief context

# Structured output for scripting
brief context --json

brief signals

View research signals and customer insights extracted from your connected tools.

# List recent signals
brief signals list

# Search signals by theme
brief signals search "onboarding friction"

brief personas

View user personas Brief has identified from your data.

brief personas list
brief personas get <persona-id>

brief features

View your product feature registry.

brief features list
brief features get <feature-id>

brief pipeline

View your work pipeline — what's being built, what's planned, and what's shipped.

brief pipeline

brief market

View GTM data — competitors, deals, and positioning.

# List tracked competitors
brief market competitors

# Filter by status
brief market competitors --status active

# View sales pipeline deals
brief market deals

# Filter by stage or source
brief market deals --stage "negotiation"
brief market deals --source hubspot

# View your positioning document
brief market positioning

---

Setting Up AI Coding Agents

The CLI can install skill files that teach AI coding agents how to use Brief. This works with Claude Code, Cursor, Windsurf, Codex, Copilot, and Cline.

# Auto-detect your agent and install skill files
brief init

# Target a specific agent
brief init --agent cursor
brief init --agent claude

# Install to global config (~/) instead of project
brief init --global

# Update existing skill files
brief init --refresh

After running brief init, your AI coding agent can call Brief commands via shell tool-use — no MCP configuration required. The agent gets access to product context, decision validation, document search, and more.

Supported Agents

Agent	Command
Claude Code	brief init --agent claude
Cursor	brief init --agent cursor
Windsurf	brief init --agent windsurf
Codex	brief init --agent codex
Copilot	brief init --agent copilot
Cline	brief init --agent cline
All agents	brief init --agent all

---

JSON Output and Scripting

Any command supports --json for structured output:

brief decisions list --json
brief ask "summarize our Q1 decisions" --json

Filter with --jq:

brief decisions list --json --jq '.data[0].decision'

Multi-turn conversations in scripts:

RESPONSE=$(brief ask "what's our auth strategy?" --json)
CONV_ID=$(echo "$RESPONSE" | jq -r '.data.conversation_id')
brief ask -c "$CONV_ID" "what are the risks?" --json

---

Global Options

Option	Description
--json	Output as JSON
--jq <expr>	Filter JSON output with a jq expression
-q, --quiet	Suppress non-essential output
--no-color	Disable colored output
--no-browser	Don't open browser for auth flows
--token <token>	Use a specific access token
--org <org-id>	Override organization ID
--no-update-check	Skip update check

---

Troubleshooting

"command not found: brief"

The CLI isn't in your PATH. Either:

• Install globally: npm install -g @briefhq/cli
• Use npx: npx @briefhq/cli@latest <command>

Authentication errors

Re-authenticate:

brief logout
brief login

Wrong workspace

Switch workspaces:

brief workspace

Browser won't open

Use the --no-browser flag and manually visit the URL printed in your terminal:

brief login --no-browser

Stale data

The CLI always fetches live data from the Brief API. If results seem stale, check your integration sync status at Brief → Settings → Integrations.

---

What's Next?

Now that the Brief CLI is installed:

1. Try brief ask "I'm new, show me around" to explore your product context
2. Run brief init to set up your AI coding agent
3. Search before building — brief decisions search "..." to avoid redoing solved problems
4. Record decisions as you go — brief decisions create to build institutional memory

For more on using Brief effectively, see:

• Brief MCP Setup Guide — alternative integration via MCP protocol
• Tips for Better Answers
• Example Prompts