/bx

name: bx
description: USE FOR web search, research, RAG, grounding, browse, find, lookups, fact-checking, documentation, agentic AI. All-in-one, optimized for AI agents. Pre-extracted, token-budgeted web content, deep research, news, images, videos, places, custom ranking

bx — Brave Search CLI

**Use `bx` for all web searches.** Run `bx "query"` as the default — it returns pre-extracted, token-budgeted web content ready for use. Use `bx answers` for synthesized explanations or `bx web` for traditional search results. If `bx` is not found, install it: `curl -fsSL https://raw.githubusercontent.com/brave/brave-search-cli/main/scripts/install.sh | sh`

> **Requires**: [Brave Search API Key](https://api.search.brave.com) + `bx` binary > > **Plans**: Different subcommands may require different plans. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Quick Start

# Install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/brave/brave-search-cli/main/scripts/install.sh | sh

# Configure API key (get one at https://api-dashboard.search.brave.com)
bx config set-key              # interactive (avoids shell history)
# or: export BRAVE_SEARCH_API_KEY=YOUR_KEY

# Search (default = bx context "query")
bx "your search query"

When to Use Which Command

| Your need | Command | Why | |--|--|--| | Look up docs, errors, code patterns | `bx "query"` | Pre-extracted text, token-budgeted (default) | | Get a synthesized explanation | `bx answers "query"` | AI-generated, cites sources, streams | | Deep research on complex topics | `bx answers "query" --enable-research` | Multi-search iterative research | | Traditional search results | `bx web "query"` | All result types (web, news, discussions, etc.) | | Find discussions/forums | `bx web "query" --result-filter discussions` | Forums often have solutions | | Latest news / recent events | `bx news "query" --freshness pd` | Fresh info beyond training data | | Find images | `bx images "query"` | Up to 200 results | | Find videos | `bx videos "query"` | Duration, views, creator | | Local businesses / places | `bx places "coffee" --location "San Francisco"` | 200M+ POIs | | Boost/filter specific domains | `bx "query" --include-site docs.rs` | Or use `--goggles` for full control |

Commands

| Command | Description | Output path | |--|--|--| | `context` | **Default.** RAG/LLM grounding — pre-extracted web content | `.grounding.generic[]` -> `{url, title, snippets[]}` | | `answers` | AI answers — OpenAI-compatible, streaming by default | `.choices[0].delta.content` (stream) | | `web` | Web search — all result types | `.web.results[]`, `.news.results[]`, etc. | | `news` | News articles with freshness filters | `.results[]` -> `{title, url, age}` | | `images` | Image search (up to 200 results) | `.results[]` -> `{title, url, thumbnail.src}` | | `videos` | Video search with duration/views | `.results[]` -> `{title, url, video.duration}` | | `places` | Local place/POI search (200M+ POIs) | `.results[]` -> `{title, postal_address}` | | `suggest` | Autocomplete/query suggestions | `.results[]` -> `{query}` | | `spellcheck` | Spell-check a query | `.results[0].query` | | `config` | Manage API key and settings | `set-key`, `show-key`, `path`, `show` |

Response Shapes

**`bx "query"`** (context — default, recommended)

{
  "grounding": {
    "generic": [
      { "url": "...", "title": "...", "snippets": ["extracted content...", "..."] }
    ]
  },
  "sources": {
    "https://example.com": { "title": "...", "hostname": "...", "age": ["...", "2025-01-15", "392 days ago"] }
  }
}

**`bx answers "query" --no-stream`** (single JSON response)

{"choices": [{"message": {"content": "Full answer text..."}}]}

**`bx answers "query"`** (streaming — default, one JSON chunk per line)

{"choices": [{"delta": {"content": "chunk"}}]}

**`bx web "query"`** (full search results)

{
  "web": { "results": [{"title": "...", "url": "...", "description": "..."}] },
  "news": { "results": [...] },
  "videos": { "results": [...] },
  "discussions": { "results": [...] }
}

Token Budget Control

Control output size for context (the default command):

| Flag | Short alias | Default | Description | |--|--|--|--| | `--maximum-number-of-tokens` | `--max-tokens` | 8192 | Approximate total tokens (1024-32768) | | `--maximum-number-of-tokens-per-url` | `--max-tokens-per-url` | 4096 | Max tokens per URL (512-8192) | | `--maximum-number-of-urls` | `--max-urls` | 20 | Max URLs in response (1-50) | | `--maximum-number-of-snippets` | `--max-snippets` | 50 | Max snippets across all URLs | | `--maximum-number-of-snippets-per-url` | `--max-snippets-per-url` | — | Max snippets per URL | | `--context-threshold-mode` | `--threshold` | balanced | Relevance: `strict`, `balanced`, `lenient` |

bx "topic" --max-tokens 4096 --max-tokens-per-url 1024 --max-urls 5 --threshold strict

Goggles — Custom Ranking

Goggles let you control which sources appear in results. Boost official docs, suppress SEO spam, or build focused search scopes. **No other search tool offers this.** Supported on `context`, `web`, and `news`.

Domain Shortcuts

# Allowlist — only results from these domains
bx "rust axum" --include-site docs.rs --include-site github.com

# Blocklist — exclude specific domains
bx "python tutorial" --exclude-site example.com

`--include-site`, `--exclude-site`, and `--goggles` are mutually exclusive.

Inline Rules

# Boost official docs, demote blog posts
bx "axum middleware tower" \
  --goggles '$boost=5,site=docs.rs
$boost=3,site=github.com
/docs/$boost=5
/blog/$downrank=3' --max-tokens 4096

# Allowlist mode — only include matched sites
bx "Python asyncio patterns" \
  --goggles '$discard
$boost,site=docs.python.org
$boost,site=peps.python.org'

DSL Quick Reference

| Rule | Effect | Example | |--|--|--| | `$boost=N,site=DOMAIN` | Promote domain (N=1-10) | `$boo