@briefhq/cli

Brief — Your Product Co-founder, in the terminal.

Query decisions, manage documents, chat with your product knowledge base, and keep your entire team aligned — from the command line or through AI coding agents.

Quick Start

npx @briefhq/cli login
npx @briefhq/cli ask "what should we build next?"

Installation

# Zero-install (always latest)
npx @briefhq/cli@latest <command>

# Global install
npm i -g @briefhq/cli

# pnpm
pnpm add -g @briefhq/cli

Requires Node.js 20+.

Authentication

Interactive Login

brief login

Opens your browser for OAuth authentication (PKCE). Credentials are stored in ~/.config/brief/credentials.json with mode 0600.

For headless environments:

brief login --no-browser

Token-Based (CI / Agents)

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

Or pass inline:

brief --token <token> decisions list --json

Token Resolution Order

The CLI resolves authentication in this order:

1. BRIEF_TOKEN environment variable
2. --token flag
3. Stored credentials (~/.config/brief/credentials.json)
4. Auto-refresh via refresh token if expired

Commands

Agent Reasoning

| Command | Description | | --- | --- | | ask <question> | Ask Brief a question (streaming response) |

brief ask "what should we prioritize next?"
brief ask --mode check "should we use Redis for caching?"
brief ask --mode decide "monorepo vs polyrepo?"
brief ask -c <conversation-id> "tell me more"
brief ask --context "refactoring auth module" "what decisions apply here?"
brief ask "summarize the research findings" --folder <folder-uuid>
brief ask "compare these two docs" --docs <doc-uuid-1>,<doc-uuid-2>
brief ask "deep analysis of our auth strategy" --model claude-sonnet-4-5

Flags:

| Flag | Description | | --- | --- | | -m, --mode <mode> | Reasoning mode: advise (default), check, decide | | -c, --conversation <id> | Continue an existing conversation | | --context <text> | What you are currently working on | | --folder <uuid> | Scope context to documents in this folder | | --docs <uuids> | Include specific documents as context (comma-separated) | | --model <id> | Model to use (e.g., claude-sonnet-4-5) |

Product Context

| Command | Description | | --- | --- | | context | View or update product context |

Decisions

| Command | Description | | --- | --- | | decisions search <query> | Search decisions | | decisions list | List decisions | | decisions get <id> | Get decision details | | decisions create | Record a new decision | | decisions confirm <id> | Confirm a pending decision | | decisions reject <id> | Reject a pending decision | | decisions archive <id> | Archive a decision | | decisions tags | List all decision tags |

brief decisions search "authentication"
brief decisions list --tags security,auth --limit 5
brief decisions create --decision "Use JWT for auth" --rationale "Stateless, works across services"
brief decisions confirm abc123
brief decisions reject abc123 --reason "Superseded by SSO decision"

Notable flags:

| Flag | Applies to | Description | | --- | --- | --- | | --limit <n> | search, list | Max results (default: 10/20) | | --tags <csv> | list, create | Filter or set comma-separated tags | | --category <name> | list, create | Filter or set category | | --include-archived | list | Include archived decisions | | --decision <text> | create | The decision text (required) | | --rationale <text> | create, confirm | Rationale (required for create) | | --reason <text> | reject, archive | Reason (required for reject) | | --topic <text> | create | Decision topic | | --severity <text> | create | Decision severity |

Documents

| Command | Description | | --- | --- | | docs search <query> | Search documents | | docs list | List documents | | docs read <id> | Get document content | | docs browse | Show folder tree | | docs create | Create a new document | | docs import <directory> | Import markdown files from a directory |

brief docs search "onboarding"
brief docs browse
brief docs read doc_abc123
brief docs import ./research-notes --folder <folder-uuid>

Import command: Reads all .md files from a local directory and uploads them as Brief documents. Processes up to 100 files per batch asynchronously.

Features

| Command | Description | | --- | --- | | features list | List product features | | features get <id> | Get feature details |

Personas

| Command | Description | | --- | --- | | personas list | List user personas | | personas get <id> | Get persona details |

Research Signals

| Command | Description | | --- | --- | | signals list | View research signals and customer insights | | signals search <theme> | Search signals by theme |

Work Pipeline

| Command | Description | | --- | --- | | pipeline | View the work pipeline |

Conversations

| Command | Description | | --- | --- | | conversations list | List recent conversations | | conversations get <id> | View a conversation |

Setup

| Command | Description | | --- | --- | | init | Set up Brief for your coding agents | | login | Authenticate with Brief | | logout | Log out and revoke credentials | | status | Show authentication and workspace status | | token | Print the current access token | | workspace list | List available workspaces | | workspace switch <id> | Switch the active workspace |

brief init                         # Auto-detect agents in current project
brief init --agent cursor,claude   # Target specific agents
brief init --agent all --global    # Install globally for all agents
brief init --refresh               # Update existing skill files
brief token --refresh              # Force-refresh and print token

Supported agents: Cursor, Claude Code, GitHub Copilot, Windsurf, Cline, Codex

Discovery

| Command | Description | | --- | --- | | manifest | Print machine-readable command manifest | | skill show | Print the Brief skill file content | | skill push <file> | Push a custom skill file to Brief |

Agent Usage

The CLI is built for AI coding agents. Every command supports structured output, deterministic exit codes, and machine-readable error envelopes.

JSON Output

Pass --json to any command for structured output:

brief decisions list --json

{
  "success": true,
  "data": [ ... ],
  "meta": { "timestamp": "2025-01-15T10:30:00.000Z" }
}

Filter with --jq:

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

Multi-Turn Conversations

The ask command returns a conversation_id that agents can use for follow-ups:

# First question
RESPONSE=$(brief ask "what's our auth strategy?" --json)
CONV_ID=$(echo "$RESPONSE" | jq -r '.data.conversation_id')

# Follow-up in the same conversation
brief ask -c "$CONV_ID" "what are the risks?" --json

Command Discovery

Agents can discover all available commands at runtime:

brief manifest --json

Returns the full command schema including arguments, flags, types, defaults, and choices.

Error Envelope

Errors use the same JSON structure:

{
  "success": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Not authenticated. Run: brief login",
    "suggestion": "..."
  }
}

CI/CD Integration

export BRIEF_TOKEN=$BRIEF_TOKEN
brief decisions search "deployment" --json
brief ask "summarize our Q1 decisions" --json --jq '.data.answer'

Global Flags

| Flag | 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 the update check | | -v, --version | Show version |

Exit Codes

| Code | Meaning | Recommended Agent Action | | --- | --- | --- | | 0 | Success | Proceed normally | | 1 | General error | Retry or surface to user | | 2 | Usage error | Fix the command syntax | | 3 | Auth required | Run brief login or set BRIEF_TOKEN | | 4 | Not found | Check the resource ID | | 5 | Rate limited | Wait and retry (see retry_after in error) | | 6 | Server error | Retry after a short delay |

Skills Integration

Brief ships a skill file that teaches AI agents how to use your product context. Install it into any supported agent with a single command:

brief init

Or fetch the skill content directly:

brief skill show

For custom skills, push your own skill file to Brief:

brief skill push ./my-custom-skill.md

Links

• Website
• Documentation
• GitHub
• npm

License

MIT