Quickstart

Run a search, retrieve page content, and produce structured results.

Quickstart

This guide walks through the most common Kestrel Search workflows.

Run a standard search

kestrelsearch search "python dataclasses"

By default, Kestrel Search:

1. Searches DuckDuckGo.
2. Fetches up to three times the requested result count.
3. Extracts readable content from those pages.
4. Re-ranks the candidates with BM25.
5. Returns the top five results.

Progress messages go to stderr. Results go to stdout.

Return fewer results

kestrelsearch search "python dataclasses" --top-k 3

Produce JSON for an agent

kestrelsearch search "recent Python packaging changes" \
  --time-filter m \
  --top-k 3 \
  --output json

To save only the machine-readable output:

kestrelsearch search "rust ownership" --output json > results.json

Run a faster snippet-only search

Skip page retrieval and BM25 ranking when search-result snippets are enough:

kestrelsearch search "OpenAI news" --no-fetch

Search more than one provider

kestrelsearch search "python typing" \
  --engine duckduckgo \
  --engine bing \
  --mode fanout

Run multiple queries

Repeat -q or --query to search several queries in one command. You do not need to provide a separate positional query:

kestrelsearch search \
  -q "python typing documentation" \
  -q "pyright documentation" \
  --engine duckduckgo \
  --engine bing \
  --mode fanout

The positional form remains available for a single query and can be combined with repeated --query options.

Continue with multi-query and multi-provider search or install the agent skill.