qry

justestif.github.io/qry

A terminal-native, agent-first web search CLI. Routes queries through swappable built-in adapters and always outputs JSON.

qry "what is the latest version of numpy"

[
  {
    "title": "NumPy 2.0 Release Notes",
    "url": "https://numpy.org/doc/stable/release/2.0.0-notes.html",
    "snippet": "NumPy 2.0.0 is the first major release since 2006..."
  }
]

Install

Homebrew:

brew install justEstif/tap/qry

npm (alternative):

npm install -g @justestif/qry

mise:

mise cache clear
mise use -g go:github.com/justestif/qry@latest
mise reshim

Adapters

Adapters are built-in packages that do the actual searching. They implement a common interface.

Adapter	Source	Key required
brave-api	Brave Search API	✓
brave-scrape	Brave Search (scraping)	✗
ddg-scrape	DuckDuckGo Lite (scraping)	✗
exa	Exa AI (via MCP)	✗
github	GitHub Search API	✗ (optional)
searx	SearXNG (self-hostable)	✗
stackoverflow	Stack Exchange API	✗ (optional)
wikipedia	Wikipedia / MediaWiki API	✗

Configure

Create ~/.config/qry/config.toml:

Use ${VAR} syntax in adapter config values — qry expands them from the environment at runtime so secrets never live in the file:

[adapters.brave-api.config]
  api_key = "${BRAVE_API_KEY}"

[defaults]
  num     = 10
  timeout = "5s"

[routing]
  mode = "first"
  pool = ["ddg-scrape", "brave-scrape"]

Agent usage

An agent skill is available for one-line install into any supported agent:

npx skills add justestif/qry -g -y

Browse skills at skills.sh.

---

Run qry --agent-info (or -A) to get a JSON description of the tool and your current configuration — useful for agents to orient themselves before making search calls:

qry --agent-info

The output includes the tool description, available flags, routing mode explanations, and each configured adapter with its availability status. Adapter config maps show ${VAR} template strings rather than resolved values, so secrets are never exposed.

Routing modes

• first — tries adapters in order, returns on first success. Fast, good for most use cases.
• merge — queries all adapters concurrently, deduplicates by URL, returns combined results.

More

See docs/ for full documentation:

• docs/architecture.md — how qry works internally
• docs/schema.md — config and JSON schemas
• docs/adapters.md — how to build your own adapter