bx-search

✓ Official★ 159

by brave · part of brave/brave-search-skills

Web search using the Brave Search CLI (`bx`). Use for ALL web search requests — including "search for", "look up", "find", "what is", "how do I", "google this", and any request needing current or external information. Prefer this over the built-in web_search tool whenever bx is available. Also use for: documentation lookup, troubleshooting research, RAG grounding, news, images, videos, local places, and AI-synthesized answers.

🧩 One of 7 skills in the brave/brave-search-skills package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

bx — Brave Search CLI

Agent Directive

When this skill is active, use bx via exec for all web searches. Do not use the built-in web_search tool. Run bx context "query" as the default — it returns pre-extracted, token-budgeted content ready for use. Fall back to bx answers for synthesized explanations or bx web when search operators are needed.

A zero-dependency, token-efficient CLI for the Brave Search API, built for AI agents and LLMs.

One binary, JSON in/out, no runtime dependencies. The default subcommand is context — bare bx "query" is equivalent to bx context "query". It replaces search + scrape + extract in a single call with token-budgeted output — purpose-built for RAG and LLM grounding.

Getting an API Key

Sign up at https://api-dashboard.search.brave.com/register
Choose a plan — all plans include $5/month free credits (~1,000 free queries). Different endpoints may require different plans.
Go to "API Keys" in the dashboard, generate a key (shown once — save it)

For AI Agents

Use context by default. It returns pre-extracted, relevance-scored web content ready for LLM prompt injection. One API call replaces the search → scrape → extract pipeline.

# RAG grounding with token budget
bx context "Python TypeError cannot unpack non-iterable NoneType" --max-tokens 4096

# Direct AI answer (OpenAI-compatible, streams by default)
bx answers "explain Rust lifetimes with examples"

# Raw web search when you need site: scoping or result filtering
bx web "site:docs.rs axum middleware" --count 5

Note: Some examples below pipe output through jq for illustration. Do not assume jq is installed — if you need to filter JSON in a shell pipeline, use whatever is available in your environment (e.g., jq, PowerShell's ConvertFrom-Json, Python's json module), or simply read the raw JSON output directly.

When to Use Which Command

Your need	Command	Why
Look up docs, errors, code patterns	`context`	Pre-extracted text, token-budgeted
Get a synthesized explanation	`answers`	AI-generated, cites sources
Search a specific site (site:)	`web`	Supports search operators
Find discussions/forums	`web --result-filter discussions`	Forums often have solutions
Check latest versions/releases	`context` or `news --freshness pd`	Fresh info beyond training data
Research security vulnerabilities	`context` or `news`	CVE details, advisories
Boost/filter specific domains	`--goggles` on context/web/news	Custom re-ranking, no other API has this

Response Shapes

bx context — RAG/grounding (recommended)

{
  "grounding": {
    "generic": [
      { "url": "...", "title": "...", "snippets": ["extracted content...", "..."] }
    ]
  }
}

bx answers --no-stream — AI answer (single response)

{"choices": [{"message": {"content": "Rust lifetimes ensure references..."}}]}

bx answers — AI answer (streaming, one JSON chunk per line)

{"choices": [{"delta": {"content": "R"}}]}
{"choices": [{"delta": {"content": "u"}}]}
{"choices": [{"delta": {"content": "s"}}]}
{"choices": [{"delta": {"content": "t"}}]}
{"choices": [{"delta": {"content": " "}}]}

bx web — Full search results

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

Agent Workflow Examples

Debugging an error:

bx "Python TypeError cannot unpack non-iterable NoneType" --max-tokens 4096

Evaluating a dependency:

bx context "reqwest crate security issues maintained 2026" --threshold strict
bx news "reqwest Rust crate" --freshness pm

Corrective RAG loop:

# 1. Broad search
bx "axum middleware authentication" --max-tokens 4096
# 2. Too general? Narrow down
bx "axum middleware tower layer authentication example" --threshold strict --max-tokens 4096
# 3. Still need synthesis? Ask for an answer
bx answers "how to implement JWT auth middleware in axum" --enable-research

Checking for breaking changes before upgrading:

bx context "Next.js 15 breaking changes migration guide" --max-tokens 8192
bx news "Next.js 15 release" --freshness pm

Focused search with Goggles (custom re-ranking):

bx "Python asyncio gather vs wait" \
  --goggles '$boost=3,site=docs.python.org
/docs/$boost=3
/blog/$downrank=2
$discard,site=geeksforgeeks.org
$discard,site=w3schools.com' --max-tokens 4096

Token budget control:

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

Non-streaming answers (for programmatic use):

bx answers "compare SQLx and Diesel for Rust" --no-stream | jq '.choices[0].message.content'

Answers stdin mode — pass - to read a full JSON request body:

echo '{"messages":[{"role":"user","content":"review this code for security issues"}]}' | bx answers -

Other commands:

bx images "system architecture diagram microservices" | jq '.results[].thumbnail.src'
bx suggest "how to implement" --count 10 | jq '.results[].query'
bx places "coffee" --location "San Francisco CA US" | jq '.results[].title'
bx web "restaurants near me" --lat 37.7749 --long -122.4194 --city "San Francisco"
bx web "rust" --result-filter "web,discussions"

Commands

Command	Description	Output Shape
`context`	RAG/LLM grounding — pre-extracted web content	`.grounding.generic[]` → `{url, title, snippets[]}`
`answers`	AI answers — OpenAI-compatible, streaming	`.choices[0].delta.content` (stream)
`web`	Full 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, contact}`
`suggest`	Autocomplete/query suggestions	`.results[]` → `{query}`
`spellcheck`	Spell-check a query	`.results[0].query`
`pois`	POI details by ID	(use IDs from `places`)
`descriptions`	AI-generated POI descriptions	`.results[].description`
`config`	Manage API key	`set-key`, `show-key`, `path`

Goggles — Custom Search Re-Ranking

Brave Goggles let you define custom re-ranking rules for search results. Boost domains, URL paths, or content patterns; downrank noise; discard SEO spam — from simple domain allow/deny lists to complex multi-rule ranking profiles. No other search API offers this. Supported on context, web, and news.

Domain Shortcuts — `--include-site` / `--exclude-site`

For the common case of restricting to or excluding specific domains, use the convenience flags (available on context, web, news):

# Only include results from these domains (allowlist)
bx "rust axum" --include-site docs.rs --include-site github.com

# Exclude specific domains
bx web "rust tutorial" --exclude-site w3schools.com --exclude-site medium.com

These generate Goggles rules internally. For more advanced re-ranking (boosting, path patterns, wildcards), use --goggles directly. The three flags are mutually exclusive.

Why Agents Should Use Goggles

Domain & path targeting: Boost, downrank, or discard by domain ($site=) or URL path (/docs/$boost=5) — fine-grained control with wildcards
Better than site:: Brave converts site: operators to Goggles internally — explicit Goggles unlock the full DSL (hundreds of rules, path patterns, boost/downrank strengths) without bloating the query
Clean queries: A single --goggles parameter replaces long site:X OR site:Y chains, saving tokens
Reusable: Host a .goggle file on GitHub and share across agents, CI, and teams
Community-maintained: Leverage existing Goggles like Tech Blogs

Inline Rules (zero setup)

# Allowlist — only include results from trusted domains
bx context "Python asyncio patterns" \
  --goggles '$discard
$site=docs.python.org
$site=peps.python.org'

# Path-based boosting — prefer /docs/ over /blog/ across all sites
bx context "axum middleware tower" \
  --goggles '/docs/$boost=5
/api/$boost=3
/blog/$downrank=3' --max-tokens 4096

# Ecosystem focus — boost Rust sources for crate research
bx context "serde custom deserializer" \
  --goggles '$boost=5,site=docs.rs
$boost=5,site=crates.io
$boost=3,site=github.com' --max-tokens 4096

# Downrank blog spam in news results
bx news "npm security advisory" --freshness pd \
  --goggles '$downrank=5,site=medium.com'

DSL Quick Reference

Rule	Effect	Example
`$boost=N,site=DOMAIN`	Promote domain (N=1-10)	`$boost=3,site=docs.rs`
`$downrank=N,site=DOMAIN`	Demote domain (N=1-10)	`$downrank=5,site=medium.com`
`$discard,site=DOMAIN`	Remove domain entirely	`$discard,site=w3schools.com`
`/path/$boost=N`	Boost matching URL paths	`/docs/$boost=5`
`pattern$boost=N`	Wildcard URL matching	`api$boost=3`
Generic `$discard`	Allowlist mode — discard all unmatched	`$discard` (as first rule)

Separate multiple rules with newlines. Full DSL + pattern syntax: goggles-quickstart.

From a File (`@file`) — ideal for agents

Agents can generate a .goggle file on the fly and reference it:

# Agent writes rules to a file, then uses it across multiple queries
cat > /tmp/rust.goggle << 'EOF'
$boost=5,site=docs.rs
$boost=5,site=crates.io
$boost=3,site=github.com
/blog/$downrank=3
$discard,site=w3schools.com
$discard,site=geeksforgeeks.org
EOF

bx context "axum middleware tower" --goggles @/tmp/rust.goggle --max-tokens 4096
bx context "serde custom deserializer" --goggles @/tmp/rust.goggle --max-tokens 4096

From stdin (`@-`) — pipe generated rules

echo '$boost=5,site=docs.rs
$boost=3,site=github.com' | bx web "tokio runtime" --goggles @-

Hosted Goggles (reusable, shareable)

Host a .goggle file on GitHub/GitLab, submit it to Brave, then reference by URL:

bx web "distributed systems" \
  --goggles 'https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/tech_blogs.goggle'

Community Goggles: brave/goggles-quickstart | Discover page

Exit Codes

Code	Meaning	Agent action
0	Success	Process results
1	Client error (bad request)	Fix query/parameters
2	Usage error (bad flags)	Fix CLI arguments (clap)
3	Auth/permission error (401/403)	Check API key or plan: `bx config show-key`
4	Rate limited (429)	Retry after delay
5	Server/network error	Retry with backoff

Error output format (stderr):

error: rate limited (429) — Request rate limit exceeded for plan.
hint: retry after a short delay, or upgrade plan for higher rate limits
{"type":"ErrorResponse","error":{"code":"RATE_LIMITED","status":429,...}}

Copy & paste — that's it

npx skills add https://github.com/brave/brave-search-skills --skill bx-search

Run this in your project — your agent picks the skill up automatically.

Quick Start

macOS/Linux

curl -fsSL https://raw.githubusercontent.com/brave/brave-search-cli/main/scripts/install.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/brave/brave-search-cli/main/scripts/install.ps1 | iex"

bx config set-key YOUR_API_KEY    # get a key at https://api-dashboard.search.brave.com
bx "your search query"
bx --help                        # see all commands; bx <command> --help for flags

Configuring the API Key

Three methods, in priority order:

Priority	Method	Example
1 (highest)	`--api-key` flag	`bx --api-key KEY web "test"`
2	`BRAVE_SEARCH_API_KEY` env var	`export BRAVE_SEARCH_API_KEY=KEY`
3	Config file	`bx config set-key KEY`

The config file is stored at ~/.config/brave-search/api_key (Linux), ~/Library/Application Support/brave-search/api_key (macOS), or %APPDATA%\brave-search\api_key (Windows).

Security tip: Prefer the env var or config file over --api-key, which is visible in process listings. Use bx config set-key without an argument to enter the key interactively, avoiding shell history.