---
title: "SearXNG CLI: private web search for AI agents · Stefan Preu"
description: "searxng is an open-source CLI for your own SearXNG instance, built for AI agents: TOON output, validated formats, cache-only runs and a command contract."
url: https://preu.at/work/searxng-cli
updated: 2026-10-19
---

# SearXNG CLI

web search for agents through a SearXNG instance you choose: compact results, a cache for repeatable runs, and output you can validate before you trust it.

- install: `npm install -g searxng-cli`
- version: 2026.7.31 · 31 Jul 2026
- commands: `searxng`, `searxng-cli`
- node: ≥ 22.12
- license: MIT
- source: [github.com/unbraind/searxng-cli](https://github.com/unbraind/searxng-cli)
- works with: [SearXNG](https://searxng.org)

## what it’s for

searxng sends queries to a SearXNG metasearch instance and returns the results as TOON by default, or JSON, JSON lines, CSV, markdown, YAML, XML, RSS or HTML. any upstream SearXNG parameter can be passed through, so the CLI never hides a feature of the instance.

searching changes nothing, so the guard rails here are about trust and repeatability: knowing where a result came from, getting the same answer twice, and failing loudly when there is nothing to find.

## what it covers

search over GET and POST, autocomplete, engines and categories, time ranges, presets, persistent cache, instance health, engine errors, Prometheus metrics, OpenSearch metadata.

## built for agents: results you can check

an agent acting on a search result should know where it came from and whether it is complete.

- **a contract agents can read.** prints the complete, versioned command contract, in TOON or as JSON for tool builders. `searxng commands --json`
- **modes for agents.** --agent trims output for language models, --agent-json adds validated compact JSON, --agent-ci is strict, offline-first and validated. `searxng --agent-json "query"`
- **repeatable from the cache.** answers from the local cache only, without touching the network. `searxng --offline-first "query"`
- **validate before you trust.** checks the output against the format’s schema; the schemas themselves are available with --schema-json. `searxng --format json --validate-output "query"`
- **fail loudly on nothing.** exits with code 2 when a search returns no results. machine formats also carry the source instance and a timestamp. `searxng --strict --json "query"`

## a first run

```sh
# # point it at your instance and test the connection
searxng --setup
searxng "your search query"
searxng --doctor
```

commands from the project’s README; what they print depends on your server. checked against the README at [dd47144](https://github.com/unbraind/searxng-cli/blob/dd4714404bdb9096931d7cbc7a9a7cf42d710355/README.md) (npm 2026.7.31) · [npm](https://www.npmjs.com/package/searxng-cli)

## same rules, four services

each service CLI pairs compact, structured output with discovery an agent can read and writes that have to be asked for.

- [Home Assistant CLI](https://preu.at/work/home-assistant-cli): Home Assistant from the command line, built for agents.
- [Jellyfin CLI](https://preu.at/work/jellyfin-cli): Jellyfin from the command line, built for agents.
- [Monica CLI](https://preu.at/work/monica-cli): your personal CRM from the command line, read-only by default.
- [PM CLI](https://preu.at/work/pm-cli): case study. project management is a context problem.

---

[preu.at](https://preu.at/) · Stefan Preu, agentic systems architect, based in austria · [every page for agents](https://preu.at/llms.txt) · this page in a browser: https://preu.at/work/searxng-cli