bx — Brave Search CLI

Directive pour agent

Quand cette compétence est active, utilisez bx via exec pour toutes les recherches web. N'utilisez pas l'outil web_search intégré. Exécutez bx context "query" par défaut — cela retourne du contenu pré-extrait et optimisé en tokens, prêt à l'emploi. Basculez sur bx answers pour les explications synthétisées ou sur bx web quand des opérateurs de recherche sont nécessaires.

Un CLI sans dépendances, économe en tokens, pour l'API Brave Search, conçu pour les agents IA et les LLM.

Un seul binaire, JSON en entrée/sortie, zéro dépendances d'exécution. La sous-commande par défaut est context — un simple bx "query" équivaut à bx context "query". Cela remplace recherche + scraping + extraction en un seul appel avec sortie optimisée en tokens — conçu spécifiquement pour RAG et l'ancrage LLM.

Démarrage rapide

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    # obtenez une clé sur https://api-dashboard.search.brave.com
bx "votre requête de recherche"
bx --help                        # voir toutes les commandes ; bx <command> --help pour les flags

Obtenir une clé API

1. Inscrivez-vous sur https://api-dashboard.search.brave.com/register
2. Choisissez un plan — tous les plans incluent 5 $/mois de crédits gratuits (~1 000 requêtes gratuites). Différents points de terminaison peuvent nécessiter des plans différents.
3. Allez à « API Keys » dans le tableau de bord, générez une clé (affichée une seule fois — sauvegardez-la)

Configuration de la clé API

Trois méthodes, par ordre de priorité :

Le fichier de config est stocké à ~/.config/brave-search/api_key (Linux), ~/Library/Application Support/brave-search/api_key (macOS), ou %APPDATA%\brave-search\api_key (Windows).

Conseil de sécurité : Préférez la variable d'env ou le fichier de config plutôt que --api-key, qui est visible dans les listes de processus. Utilisez bx config set-key sans argument pour entrer la clé de manière interactive, en évitant l'historique shell.

Pour les agents IA

Utilisez context par défaut. Cela retourne du contenu web pré-extrait et scoré par pertinence, prêt pour l'injection dans les prompts LLM. Un appel API remplace le pipeline recherche → scraping → extraction.

# Ancrage RAG avec budget de tokens
bx context "Python TypeError cannot unpack non-iterable NoneType" --max-tokens 4096

# Réponse IA directe (compatible OpenAI, streaming par défaut)
bx answers "explain Rust lifetimes with examples"

# Recherche web brute quand vous avez besoin de scoping site: ou filtrage de résultats
bx web "site:docs.rs axum middleware" --count 5

Note : Certains exemples ci-dessous canalisent la sortie via jq à titre illustratif. Ne supposez pas que jq est installé — si vous avez besoin de filtrer du JSON dans un pipeline shell, utilisez ce qui est disponible dans votre environnement (p. ex. jq, ConvertFrom-Json de PowerShell, le module json de Python), ou lisez simplement directement la sortie JSON brute.

Quand utiliser quelle commande

Formes de réponse

bx context — RAG/ancrage (recommandé)

{
  "grounding": {
    "generic": [
      { "url": "...", "title": "...", "snippets": ["contenu extrait...", "..."] }
    ]
  }
}

bx answers --no-stream — Réponse IA (réponse unique)

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

bx answers — Réponse IA (streaming, un chunk JSON par ligne)

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

bx web — Résultats de recherche complets

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

Exemples de workflow d'agent

Déboguer une erreur :

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

Évaluer une dépendance :

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

Boucle RAG corrective :

# 1. Recherche large
bx "axum middleware authentication" --max-tokens 4096
# 2. Trop général ? Affinez
bx "axum middleware tower layer authentication example" --threshold strict --max-tokens 4096
# 3. Besoin d'une synthèse ? Demandez une réponse
bx answers "how to implement JWT auth middleware in axum" --enable-research

Vérifier les changements disruptifs avant une mise à jour :

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

Recherche ciblée avec Goggles (réclassement personnalisé) :

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

Contrôle du budget de tokens :

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

Réponses sans streaming (pour usage programmatique) :

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

Mode stdin des réponses — passez - pour lire un corps de requête JSON complet :

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

Autres commandes :

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"

Commandes

Goggles — Réclassement de recherche personnalisé

Brave Goggles vous permet de définir des règles de réclassement personnalisé pour les résultats de recherche. Boostez des domaines, des chemins URL ou des motifs de contenu ; réduisez le bruit ; éliminez le spam SEO — des listes simples d'autorisation/interdiction de domaines à des profils de classement multi-règles complexes. Aucune autre API de recherche ne l'offre. Supporté sur context, web, et news.

Raccourcis de domaine — --include-site / --exclude-site

Pour le cas courant de restriction à des domaines spécifiques ou d'exclusion, utilisez les flags de commodité (disponibles sur context, web, news) :

# Inclure uniquement les résultats de ces domaines (liste blanche)
bx "rust axum" --include-site docs.rs --include-site github.com

# Exclure des domaines spécifiques
bx web "rust tutorial" --exclude-site w3schools.com --exclude-site medium.com

Ceux-ci génèrent des règles Goggles en interne. Pour un réclassement plus avancé (boosting, motifs de chemin, wildcards), utilisez --goggles directement. Les trois flags s'excluent mutuellement.

Pourquoi les agents devraient utiliser Goggles

• Ciblage de domaine et chemin : Boostez, réduisez ou éliminez par domaine ($site=) ou chemin URL (/docs/$boost=5) — contrôle fin avec wildcards
• Mieux que site: : Brave convertit les opérateurs site: en Goggles en interne — les Goggles explicites déverrouillent le DSL complet (centaines de règles, motifs de chemin, intensités de boost/downrank) sans surcharger la requête
• Requêtes propres : Un seul paramètre --goggles remplace de longues chaînes site:X OR site:Y, économisant des tokens
• Réutilisable : Hébergez un fichier .goggle sur GitHub et partagez-le entre agents, CI et équipes
• Maintenu par la communauté : Exploitez les Goggles existants comme Tech Blogs

Règles intégrées (zéro configuration)

# Liste blanche — inclure uniquement les résultats de domaines de confiance
bx context "Python asyncio patterns" \
  --goggles '$discard
$site=docs.python.org
$site=peps.python.org'

# Boosting basé sur le chemin — préférez /docs/ à /blog/ sur tous les sites
bx context "axum middleware tower" \
  --goggles '/docs/$boost=5
/api/$boost=3
/blog/$downrank=3' --max-tokens 4096

# Focus écosystème — boostez les sources Rust pour la recherche de crates
bx context "serde custom deserializer" \
  --goggles '$boost=5,site=docs.rs
$boost=5,site=crates.io
$boost=3,site=github.com' --max-tokens 4096

# Réduisez le spam des blogs dans les résultats d'actualité
bx news "npm security advisory" --freshness pd \
  --goggles '$downrank=5,site=medium.com'

Référence rapide du DSL

Séparez plusieurs règles par des retours à la ligne. DSL complet + syntaxe de motif : goggles-quickstart.

Depuis un fichier (@file) — idéal pour les agents

Les agents peuvent générer un fichier .goggle à la volée et le référencer :

# L'agent écrit des règles dans un fichier, puis les utilise sur plusieurs requêtes
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

Depuis stdin (@-) — canalisez les règles générées

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

Goggles hébergés (réutilisable, partageables)

Hébergez un fichier .goggle sur GitHub/GitLab, soumettez-le à Brave, puis référencez par URL :

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

Goggles communautaires : brave/goggles-quickstart | Page de découverte

Codes de sortie

Format de sortie d'erreur (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,...}}