brave-search

A TypeScript client for the Brave Search API. Works as both an importable SDK and a CLI tool.

Supports Web Search and News Search.

Setup

npm install
npm run build

Set your API key:

export BRAVE_SEARCH_API_KEY="your-api-key"

Get a key from the Brave Search API dashboard.

CLI Usage

# Web search
brave-search web "typescript generics"

# News search
brave-search news "artificial intelligence"

# With options
brave-search web "climate change" --count 5 --freshness pw --country US

# Show help
brave-search --help

CLI Options

| Option | Description | | ------------------- | --------------------------------------------------- | | --count <n> | Number of results (web: 1-20, news: 1-50) | | --offset <n> | Page offset (0-9) | | --country <code> | 2-char country code (default: ALL) | | --lang <code> | Search language (default: en) | | --freshness <val> | pd, pw, pm, py, or YYYY-MM-DDtoYYYY-MM-DD | | --safesearch <val>| off, moderate, strict | | --extra-snippets | Include extra snippets |

Output is JSON printed to stdout. Errors go to stderr.

SDK Usage

import { BraveSearchClient } from "brave-search";

const client = new BraveSearchClient(); // reads BRAVE_SEARCH_API_KEY from env
// or: new BraveSearchClient("your-api-key")

// Web search
const webResults = await client.webSearch({ q: "typescript generics", count: 5 });
console.log(webResults.web?.results);

// News search
const newsResults = await client.newsSearch({ q: "artificial intelligence", count: 10 });
console.log(newsResults.results);

Exported Types

import type {
  WebSearchParams,
  WebSearchResponse,
  WebSearchResult,
  NewsSearchParams,
  NewsSearchResponse,
  NewsSearchResult,
  SafeSearch,
  Freshness,
} from "brave-search";

Development

make install       # Install dependencies
make build         # Compile TypeScript
make dev           # Watch mode
make lint          # Type-check
make test          # Run tests
make test-watch    # Tests in watch mode
make clean         # Remove dist/

Publishing

Prerequisites

• An npm account
• Logged in via npm login

Steps

1. Update the version in package.json following semver:

   npm version patch   # bug fixes (1.0.0 -> 1.0.1)
   npm version minor   # new features (1.0.0 -> 1.1.0)
   npm version major   # breaking changes (1.0.0 -> 2.0.0)

2. Build and test:

   make clean
   make build
   make test

3. Do a dry run to verify what will be published:

   npm publish --dry-run

4. Publish:

   npm publish

   For scoped packages (e.g. @yourorg/brave-search), add --access public on the first publish.

What gets published

The files field in package.json controls which files are included. Make sure dist/ is listed. You can verify the package contents with:

npm pack --dry-run

Linking locally

To test the package locally before publishing:

npm link
brave-search web "test query"

License

ISC