---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content. Lightweight, no browser required.
script: search.js
---
# Brave Search
Web search and content extraction using the official Brave Search API. No browser required.
**Script location:** `$PI_CODING_AGENT_DIR/skills/brave-search/`
## Setup
Requires a Brave Search API account with a free subscription. A credit card is required to create the free subscription (you won't be charged).
1. Create an account at https://api-dashboard.search.brave.com/register
2. Create a "Free AI" subscription (2,000 queries/month free)
3. Create an API key
4. Add to your agenix secrets (`secrets/env-vars.age`):
```bash
export BRAVE_SEARCH_API_KEY="your-api-key-here"
```
5. Dependencies are pre-installed via Nix (no manual npm install needed)
## Search
```bash
$PI_CODING_AGENT_DIR/skills/brave-search/search.js "query" # Basic search (5 results)
$PI_CODING_AGENT_DIR/skills/brave-search/search.js "query" -n 10 # More results (max 20)
$PI_CODING_AGENT_DIR/skills/brave-search/search.js "query" --content # Include page content as markdown
$PI_CODING_AGENT_DIR/skills/brave-search/search.js "query" --freshness pw # Results from last week
$PI_CODING_AGENT_DIR/skills/brave-search/search.js "query" --freshness 2024-01-01to2024-06-30 # Date range
$PI_CODING_AGENT_DIR/skills/brave-search/search.js "query" --country DE # Results from Germany
$PI_CODING_AGENT_DIR/skills/brave-search/search.js "query" -n 3 --content # Combined options
```
### Options
- `-n <num>` - Number of results (default: 5, max: 20)
- `--content` - Fetch and include page content as markdown
- `--country <code>` - Two-letter country code (default: US)
- `--freshness <period>` - Filter by time:
- `pd` - Past day (24 hours)
- `pw` - Past week
- `pm` - Past month
- `py` - Past year
- `YYYY-MM-DDtoYYYY-MM-DD` - Custom date range
## Extract page content
```bash
$PI_CODING_AGENT_DIR/skills/brave-search/content.js https://example.com/article
```
Fetches a URL and extracts readable content as markdown.
## Output format
```
--- Result 1 ---
Title: Page Title
Link: https://example.com/page
Age: 2 days ago
Snippet: Description from search results
Content: (if --content flag used)
Markdown content extracted from the page...
--- Result 2 ---
...
--- Rate Limit Info ---
Requests remaining: 1999/2000
Plan quota remaining: 1999/2000
Resets at: 2/6/2026, 12:00:00 AM
```
## Rate Limits (Free Plan)
- **2,000 queries/month** included free
- 1 query/second rate limit
- Rate limit info shown after each search
- Paid plans available at https://api-dashboard.search.brave.com/app/plans
## When to use
- Searching for documentation or API references
- Looking up facts or current information
- Fetching content from specific URLs
- Any task requiring web search without interactive browsing