preu.at / work / searxng-cli

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.

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

● commands from the READMEsearxng 2026.7.31
# point it at your instance and test the connectionsearxng --setupsearxng "your search query"searxng --doctor
commands from the project’s README; what they print depends on your server.

checked against the README at dd47144 (npm 2026.7.31) · npm

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.