> ## Documentation Index
> Fetch the complete documentation index at: https://beige.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Brave Search Plugin

{/* Run: pnpm run docs:sync-toolkit */}

Web search using the Brave Search API — a fast, privacy-focused alternative to Google.

## Installation

Install this tool individually:

```bash theme={null}
beige tools install github:matthias-hausberger/beige-toolkit/tools/brave-search
```

Or install all tools from the toolkit:

```bash theme={null}
# From npm
beige tools install npm:@matthias-hausberger/beige-toolkit

# From GitHub
beige tools install github:matthias-hausberger/beige-toolkit
```

## Configuration

| Key              | Default  | Description                                                                                                                                                      |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`         | *(none)* | Brave Search API key. Get one at [brave.com/search/api](https://brave.com/search/api/). Falls back to `BRAVE_API_KEY` environment variable if not set in config. |
| `maxResults`     | `10`     | Default number of results to return (1–20).                                                                                                                      |
| `timeoutSeconds` | `30`     | HTTP request timeout in seconds.                                                                                                                                 |

## Prerequisites

| Requirement          | Details                                                                                                                                |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Brave Search API key | Create an account at [brave.com/search/api](https://brave.com/search/api/) and generate a key. Free tier covers \~2,000 queries/month. |

## Config Examples

**Basic setup with API key:**

```json5 theme={null}
{
  tools: {
    "brave-search": {
      "config": {
        "apiKey": "BSA_your_api_key_here",
      },
    },
  },
}
```

**Using environment variable:**

```bash theme={null}
export BRAVE_API_KEY="BSA_your_api_key_here"
```

No `apiKey` in config needed — the plugin picks up `BRAVE_API_KEY` automatically.

**Custom result count and timeout:**

```json5 theme={null}
{
  tools: {
    "brave-search": {
      "config": {
        "apiKey": "BSA_your_api_key_here",
        "maxResults": 5,
        "timeoutSeconds": 20,
      },
    },
  },
}
```

## Usage

The plugin provides a `brave-search` tool with a single `search` subcommand:

```bash theme={null}
brave-search search <query>
brave-search search <query> --count <n>
brave-search search <query> --country <code>
brave-search search <query> --offset <n>
```

**Examples:**

```bash theme={null}
# Basic search
brave-search search "cloudflare workers documentation"

# Limit to 3 results
brave-search search "typescript best practices" --count 3

# German-language results
brave-search search "nachrichten heute" --country DE

# Pagination (skip first 10 results)
brave-search search "rust programming" --offset 10
```

## Output Format

Results are returned as a numbered list with title, URL, snippet, and age:

```
Search results for: cloudflare workers

1. Cloudflare Workers Documentation
   https://developers.cloudflare.com/workers/
   Build serverless applications with Cloudflare Workers. Run JavaScript and...

2. What are Cloudflare Workers?
   https://www.cloudflare.com/learning/serverless/what-is-cloudflare-workers/
   Cloudflare Workers is a serverless platform that allows you to deploy...

3. Getting Started with Workers
   https://developers.cloudflare.com/workers/get-started-guide/
   This guide walks you through creating and deploying your first Cloudflare...
   2 days ago
```

## Command Reference

| Command            | Description                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `search <query>`   | Search the web. Required.                                                                     |
| `--count <n>`      | Number of results to return (1–20). Overrides the config default.                             |
| `--country <code>` | 2-letter country code for region-specific results (e.g., `US`, `DE`, `GB`). Case-insensitive. |
| `--offset <n>`     | Pagination: skip first N results. Useful for loading more pages.                              |

**Tool name**: `brave-search`

## Error Reference

| Error                                 | Cause                                                                                      |
| ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `Brave Search API key not configured` | No `apiKey` in config and no `BRAVE_API_KEY` environment variable set.                     |
| `Brave Search API error 401`          | Invalid API key. Verify your key at [brave.com/search/api](https://brave.com/search/api/). |
| `Brave Search API error 429`          | Rate limit exceeded. Upgrade your plan or wait for quota reset.                            |
| `Search failed: network error`        | Network connectivity issue or request timeout.                                             |

## Implementation Details

* **Target**: Sandbox (runs inside the agent container)
* **API**: GET `https://api.search.brave.com/res/v1/web/search`
* **Auth**: `X-Subscription-Token` header
* **Timeout**: Configurable, defaults to 30 seconds
* **Rate limits**: Enforced by Brave based on your plan; the plugin does not cache results

## API Limits

Brave Search API is rate-limited by plan:

| Plan   | Queries/month                                   |
| ------ | ----------------------------------------------- |
| Free   | \~2,000                                         |
| Search | $5/month for 1,000 queries (includes $5 credit) |

Monitor usage at [brave.com/search/api](https://brave.com/search/api/) to avoid unexpected charges.

## Privacy

Brave Search is privacy-focused:

* No user tracking
* No personal data retention
* Queries sent directly to Brave's API
* No search history stored by the plugin