Now that the Brief CLI is installed and your agent is wired up: Try brief ask "I'm new, show me around" to explore your product context Search before building — brief decisions search "..." to avoid redoing solved problems Record decisions as you go — brief decisions create to build institutional memory Validate approaches — brief ask --mode check "..." before an architectural change For more on using Brief effectively, see: Brief MCP Setup Guide — alternative integration via MCP protocol Tips for Better Answers Example Prompts

Brief CLI Setup Guide

Install and use the Brief CLI to navigate to your Product Graph, decisions, and documents from the terminal. Works standalone or as a tool for AI coding agents.

Last updated: April 13, 2026

The Brief CLI (@briefhq/cli) gives you terminal access to everything in Brief—your Product Graph, decisions, documents, personas, signals, and more. Every builder stays aligned, even from the command line.

Why Use the Brief CLI?

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 navigate to 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. No team ships blind.

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). Navigates your AI automatically.
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. Either way, every builder stays aligned.

Quick Start

Prerequisite: Node.js 20 or later. Check with node --version. If you don't have it, grab it from nodejs.org or your package manager.

The fastest path from zero to a working Brief CLI:

npm i -g @briefhq/cli

Then, from your project's root directory, run:

brief init

On first run, brief init:

Opens a browser to sign you in (OAuth PKCE). Credentials are stored securely in ~/.config/brief/ and tokens refresh automatically.
Auto-detects your coding agent in the current directory (Cursor, Claude Code, GitHub Copilot / VS Code, Windsurf, Cline, Codex, Junie) and installs the Brief CLI skill + instruction file so the agent knows how to call Brief from the shell.
Packs and uploads your codebase context so Brief can answer questions grounded in your actual code.

Restart your coding agent once brief init finishes. You can then call brief ask, brief decisions, and the other commands below from the terminal — or your agent can call them for you via shell tool-use.

CLI vs MCP: this setup wires your coding agent to reach Brief through the shell CLI. If you prefer your agent to reach Brief through MCP tool calls instead (or in addition), follow the Brief MCP setup guide — MCP installation is host-native and separate from the CLI path.

Zero-install alternative

Prefer not to install globally? Run any command through npx:

npx @briefhq/cli@latest init
npx @briefhq/cli@latest ask "what should we prioritize next?"

This always pulls the latest version, which is ideal for ephemeral runners and one-off invocations. pnpm supports a global install; for Yarn, use yarn dlx for one-off CLI runs (this works in Yarn Classic and Yarn Berry—Yarn 2+ removed yarn global add):

pnpm add -g @briefhq/cli
yarn dlx @briefhq/cli@latest init

CI / Headless Environments

Skip the interactive login and pass a token via environment variable. This is the canonical path for CI pipelines, remote agents, and any non-TTY caller:

export BRIEF_TOKEN=your_token_here
brief ask "what's our positioning?" --json

Store BRIEF_TOKEN in your CI platform’s secret manager (masked or protected variables) and inject it at runtime—never commit it to the repository or check it into plaintext scripts. Commands such as brief ask consume it from the environment.

Generate a token from Settings → Integrations → API Keys in the Brief web app, or run brief token on a machine where you're already logged in.

BRIEF_TOKEN takes precedence over stored credentials and works for every brief command. The CLI resolves authentication in this order:

BRIEF_TOKEN environment variable
--token flag
BRIEF_API_KEY environment variable
Stored credentials from brief login (auto-refreshed if expired)

For headless environments where you can't open a browser interactively, brief login --no-browser prints a URL you can visit from another device and paste the completion code back.

Account Management

brief logout                    # Revoke local credentials
brief workspace                 # Switch between workspaces
brief workspace list --json     # List all workspaces you belong to

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., brief_search, document tools) 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

`brief init` — Coding Agent Setup

brief init is the workhorse of the Quick Start above. It auto-detects coding agents in the current directory and writes the Brief CLI skill + instruction files, so your agent knows how to call Brief from the shell.

# Detect and configure every supported agent it finds
brief init

# Target specific agent(s)
brief init --agent cursor
brief init --agent claude,codex

# Install skill files to ~/ globally instead of the project
brief init --global

# Re-fetch skill content and overwrite existing files
brief init --refresh

# Skip the codebase upload (faster, less context for Brief)
brief init --no-scan

Supported agents

For each detected agent, brief init writes a skill file (teaching the agent how to use the Brief CLI) and an instruction file (reminding the agent to use Brief at the right moments):

Agent	`--agent` value	Skill file	Instruction file
Claude Code	`claude`	`.claude/skills/brief/SKILL.md`	`CLAUDE.md`
Cursor	`cursor`	`.cursor/skills/brief/SKILL.md`	`.cursor/rules/brief-context.mdc`
GitHub Copilot / VS Code	`copilot` (or `vscode`)	`.agents/skills/brief/SKILL.md`	`.github/copilot-instructions.md`
Windsurf	`windsurf`	`.windsurf/skills/brief/SKILL.md`	`.windsurfrules`
Cline	`cline`	`.agents/skills/brief/SKILL.md`	`.clinerules`
Codex	`codex`	`.agents/skills/brief/SKILL.md`	`AGENTS.md`
Junie	`junie`	`.junie/skills/brief/SKILL.md`	`.junie/AGENTS.md`
All of the above	`all`	All of the above	All of the above

After brief init finishes, restart your coding agent so it picks up the new skill and instruction files. Your agent can then call Brief from the terminal via shell tool-use — no further configuration required.

brief init also drops an .mcp.json (or host-specific equivalent) into your project as a convenience, so an agent that supports MCP can optionally reach Brief through MCP tool calls too. If MCP is your primary path, follow the Brief MCP setup guide — MCP install is host-native and the canonical source of truth for MCP configuration.

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 → Integrations.

What's Next?

Now that the Brief CLI is installed and your agent is wired up:

Try brief ask "I'm new, show me around" to explore your product context
Search before building — brief decisions search "..." to avoid redoing solved problems
Record decisions as you go — brief decisions create to build institutional memory
Validate approaches — brief ask --mode check "..." before an architectural change

For more on using Brief effectively, see:

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