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 --country --lang --count --offset --freshness --batch
- --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.