SkillJavaScriptv0.2.0
brave-headless
Headless web search and content extraction via the Brave Search API.
878 downloads
kelexine
Updated Feb 19, 2026brave-search
Headless web search and content extraction via the Brave Search API.
Setup
Run once before first use:
cd <skill-root>
npm ci
Required environment variable:
export BRAVE_API_KEY="your-key-here"
Get a free API key at brave.com/search/api.
Usage
Search
node scripts/search.js "query" # Basic (5 results)
node scripts/search.js "query" -n 10 # Up to 20 results
node scripts/search.js "query" --content # Include page content
node scripts/search.js "query" -n 3 --content # Combined
node scripts/search.js "query" --json # Newline-delimited JSON
node scripts/search.js --help # Full options + env vars
Extract page content
node scripts/content.js https://example.com/article
node scripts/content.js https://example.com/article --json
node scripts/content.js https://example.com/article --max-length 8000
Output format (plain text)
--- Result 1 ---
Title: Page Title
URL: https://example.com/page
Snippet: Description from Brave Search
Content:
# Page Title
Extracted markdown content...
--- Result 2 ---
...
Pass --json to get one JSON object per line instead, suitable for piping.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Invalid input or configuration error |
2 | Page had no extractable content (content.js) |
130 | Interrupted (SIGINT) |
Configuration (environment variables)
All behaviour is configurable without touching code:
| Variable | Default | Description |
|---|---|---|
BRAVE_API_KEY | — | Required. Brave Search subscription token |
LOG_LEVEL | info | debug · info · warn · error · silent |
LOG_JSON | false | Emit logs as newline-delimited JSON to stderr |
FETCH_TIMEOUT_MS | 15000 | Per-page fetch timeout |
SEARCH_TIMEOUT_MS | 10000 | Brave API call timeout |
MAX_CONTENT_LENGTH | 5000 | Max chars of extracted content |
MAX_RETRY_ATTEMPTS | 3 | Retry attempts on transient errors |
RETRY_BASE_DELAY_MS | 500 | Base delay for exponential backoff |
RETRY_MAX_DELAY_MS | 30000 | Backoff delay cap |
CONCURRENCY_LIMIT | 3 | Parallel page fetches when --content is set |
CB_FAILURE_THRESHOLD | 5 | Consecutive failures before circuit opens |
CB_RESET_TIMEOUT_MS | 60000 | Circuit breaker reset window |
All variables are validated at startup — misconfigured runs fail immediately with a descriptive list of every bad value rather than crashing mid-execution.
Architecture
See references/ARCHITECTURE.md for a full module breakdown.
scripts/
├── search.js ← Search CLI entry point
├── content.js ← Content extraction CLI entry point
├── content-fetcher.js ← HTTP fetch + Readability + DOM fallback
├── config.js ← Schema-validated env config
├── circuit-breaker.js ← Fault isolation (CLOSED → OPEN → HALF_OPEN)
├── retry.js ← Exponential backoff with full jitter
├── concurrency.js ← Bounded parallel execution pool
├── utils.js ← htmlToMarkdown, smartTruncate, parseURL
├── logger.js ← Structured leveled logger → stderr
└── errors.js ← Typed error hierarchy