> ## Documentation Index
> Fetch the complete documentation index at: https://kestrel.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

```bash theme={null}
kestrelsearch search "python dataclasses" --top-k 3
```

## Produce JSON for an agent

```bash theme={null}
kestrelsearch search "recent Python packaging changes" \
  --time-filter m \
  --top-k 3 \
  --output json
```

To save only the machine-readable output:

```bash theme={null}
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:

```bash theme={null}
kestrelsearch search "OpenAI news" --no-fetch
```

## Search more than one provider

```bash theme={null}
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:

```bash theme={null}
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](/guides/multi-query-search)
or [install the agent skill](/guides/agent-integration).