open-index/open-npm huggingface dataset:
npm package: @kennyfrc/websearch
Description: Brave Search CLI with batch support and locale-aware headers
Latest version: 2.0.1

# websearch

`websearch` is a Bun-powered CLI that calls the Brave Search API, automatically enabling operators and extra snippets while supporting single or batched queries.

## Tutorial

Follow these steps to run your first search.

1. Install dependencies:

   ```bash
   bun install
   ```

2. Create `~/.config/webserch/config.toml` with your Brave token:

   ```toml
   apiKey = "YOUR_BRAVE_API_TOKEN"
   ```

3. Execute a query:

   ```bash
   bun run src/main.ts query --q "hello world"
   ```

   The CLI prints the top results with their extra snippets. Repeat the command with different queries as needed.

## How-to guides

- **Override defaults for a single query**
  - Supply flags like `--country=us --lang=en-US --count=5 --offset=10` alongside `--q`.
- **Run multiple queries in one invocation**
  - Use `--batch` to provide a list: `bun run src/main.ts query --batch "bun runtime" "brave search api limits"`.
- **Compile a standalone binary**
  - Run `bun run build`, then execute `node dist/main.js query --q "typescript"` without Bun.

## Reference

- **Command**
  - `websearch query --q <string> --country <code> --lang <code> --count <int> --offset <int> --freshness <window> --batch <string...>`
  - `--q` is optional when `--batch` is provided; extra snippets and operators are always enabled.
- **Flags**
  - `--country`: two-letter ISO code; uppercased automatically.
  - `--lang`: language tag; normalized to `en-US` style.
  - `--count` / `--offset`: positive integers validated by Commander.
  - `--freshness`: Brave freshness window such as `d1`, `w1`, or `m6`.
  - `--batch`: runs each query sequentially, reusing other options.
- **Configuration**
  - File: `~/.config/webserch/config.toml`
    - Keys: `apiKey`, `endpoint`, `defaultCountry`, `defaultLanguage`, `defaultFreshness`.
  - Environment overrides: `WEBSEARCH_API_KEY`, `BRAVE_API_KEY`, `BRAVE_SEARCH_API_KEY`.
- **Headers**
  - `Accept-Language` and `Accept-Location` derive from CLI flags or system locale hints.
  - `User-Agent` identifies the CLI and Bun runtime.

## Explanation

- Bun ships direct TypeScript execution, removing separate build steps during development.
- Brave requires `extra_snippets=true` and `operators=true` for richer responses; the CLI enforces both, along with `Accept-*` headers taken from host locales.
- Configuration falls back from environment variables to TOML to avoid leaking API keys into command histories.
- Batch execution reuses network headers but handles errors per query, so one failure does not abort the remaining searches.