searxngr

SearXNG from the command line, inspired by ddgr and googler.

searxngr is a command-line interface (CLI) tool that allows you to perform web searches using SearXNG instances directly from your terminal. It provides rich-formatted search results with support for various search categories and advanced filtering options.

Key Features

• 💻 Terminal-based interface with colorized output
• 🚂 Search engines selection (bing, duckduckgo, google, etc)
• 📰 Support for search categories (general, news, images, videos, science, etc.)
• 👷 Safe search filtering (none, moderate, strict)
• 📅 Time-range filtering (day, week, month, year)
• 👨‍💻 JSON output option for scripting
• 🤖 Automatic configuration with first-time setup
• 🐧 Cross-platform support (macOS, Linux, Windows)

Installation

Installation requires the uv package manager.

Homebrew (macOS / Linux)

brew tap scross01/tools
brew install searxngr

uv

To try it without installing (runs from the repo's default branch; add @v0.9.0 to pin a release tag):

uvx git+https://github.com/scross01/searxngr

To install (recommended for regular and interactive use):

uv tool install https://github.com/scross01/searxngr.git

To install from source

git clone https://github.com/scross01/searxngr.git
cd searxngr
uv venv && source .venv/bin/activate # (optional)
uv sync
uv tool install .

Contributing

Development setup, building, and running the tests (including the docker integration suite) are documented in CONTRIBUTING.md. Contributions are accepted through pull requests.

Configuration

The searxngr configuration is stored in $XDG_CONFIG_HOME/searxngr/config.ini, on Mac and Linux this is typical under $HOME/.config and on Windows its under %APPDATA%.

First-Time Setup

On first run, if no configuration exists, searxngr will show an error with guidance:

$ searxngr "search query"
Error: No SearXNG instance URL set. Use --searxng-url or run `searxngr --config`
Run `searxngr --help` for more options

To set up configuration, run searxngr --config:

$ searxngr --config
creating initial configuration file /root/.config/searxngr/config.ini
Enter your SearXNG instance URL [https://searxng.example.com]: https://searxng.example.com
Disable SSL verification (y/N)? y
Connection successful.
Initial setting created. Run 'searxngr --config' again to edit all settings.

The setup will:

1. Prompt for your SearXNG instance URL
2. If using HTTPS, ask whether to disable SSL verification
3. Validate that the instance is reachable
4. Create the configuration file
5. Show the location and how to edit settings later

Configuration File

[searxngr]
searxng_url = https://searxng.example.com
# result_count = 10
# categories = general news social+media
# safe_search = strict
# engines = google duckduckgo brave
# expand = false
# language = en
# http_method = GET
# timeout = 30.0
# retries = 2
# no_verify_ssl = false
# no_user_agent = false
# no_color = false
# url_handler = open
# secondary_url_handler =

Configuration options

• searxng_url - set the URL of your SearXNG instance.
• searxng_user - username for basic auth. Optional
• searxng_password - password for basic auth. Optional
• results_per_page - the number results to output per page on the terminal. Default is 10.
• categories - the categories to use for the search. Options include news, videos, images, music, map, science, it, files, social+media. Uses general search if not set.
• safe_search - set the safe search level to none, moderate, or strict. Uses server default if not set.
• engines - use the specified engines for the search. Uses server default if not set.
• expand - show the result URL in the results list. Default is false.
• language - set the search language, e.g. en, en-CA, fr, es, de, etc.
• http_method - use either GET or POST requests to the SearXNG API. Default is GET
• timeout - HTTP timeout in seconds per attempt. Default is 30.
• retries - Retry transient transport or HTTP 500/502/503/504 failures, with backoff. Default is 2; use 0 to disable (maximum 5).
• no_verify_ssl - disable SSL verification if you are hosting SearXNG with self-signed certificated. Default is false.
• no_user_agent - Clear the user agent. Default is false.
• no_color - disable color terminal output. Default is false.
• url_handler - command to open URLs in the browser. Default varies by platform (open on macOS, xdg-open on Linux, explorer on Windows).
• secondary_url_handler - alternative command to open URLs using secondary handler. Falls back to url_handler if not set. Useful for different browsers or command-line tools.

Usage

Basic Usage

To start the interactive search console using the configured settings:

searxngr why is the sky blue

Console output without interactive mode and configuration file

You can use searxngr without a configuration file by specifying the SearXNG instance URL directly. To display search results to the console without entering the interactive prompt use the --np (or --noprompt) flag, and the -x (or --expand) to include search result URL.

searxngr --searxng-url https://searxng.example.com --noprompt --expand "search query"

This is useful for one-off searches without setting up configuration and scripted automation where you want to pass the instance URL dynamically and return the results to integrate searxngr into pipelines or other commands

Scripting

searxngr --json 'C++ & C# differences' > results.json

JSON mode returns one server page. Search diagnostics go to stderr; a failed search with no results exits nonzero, while a successful search with no matches returns []. Partial results are retained when other engines fail. Interactive prompting is disabled when stdin or stdout is not a terminal (or pass --np).

A reachable SearXNG server with JSON output enabled is still required. Enable multiple working engines on that server so one blocked engine does not disable all searches; the CLI does not bypass CAPTCHAs or change servers automatically.

searxngr --json --retries 2 'search query'

Options

Command line options can be used to modify the output and override the configuration defaults.

usage: searxngr [-h] [-q QUERY] [--searxng-url SEARXNG_URL]
                [-c [CATEGORY ...]] [--config] [-d] [-e [ENGINE ...]] [-x]
                [-j] [--http-method METHOD] [--timeout SECONDS]
                [--retries {0,1,2,3,4,5}] [--json] [-l LANGUAGE]
                [--list-categories] [--list-engines] [--lucky]
                [--no-verify-ssl] [--nocolor] [--np] [--noua] [-n N]
                [--safe-search FILTER] [-w SITE] [-t TIME_RANGE] [--unsafe]
                [--url-handler UTIL] [--secondary-url-handler UTIL] [-v] [-F]
                [-M] [-N] [-S] [-V] [-m N]
                [QUERY ...]

Perform a search using SearXNG

positional arguments:
  QUERY                 search query (optional if -q/--query is used)

options:
  -h, --help            show this help message and exit
  -q QUERY, --query QUERY
                        explicit search query (alternative to positional
                        query)
  --searxng-url SEARXNG_URL
                        SearXNG instance URL (default: NOT SET)
  -c [CATEGORY ...], --categories [CATEGORY ...]
                        list of categories to search in: general, news,
                        videos, images, music, map, science, it, files,
                        social+media (default: None)
  --config              open the default configuration file using system text
                        editor
  -d, --debug           show debug output
  -e [ENGINE ...], --engines [ENGINE ...]
                        list of engines to use for the search (default: NOT
                        SET)
  -x, --expand          Show complete url in search results
  -j, --first           open the first result in web browser and exit
  --http-method METHOD  HTTP method to use for search requests. GET or POST
                        (default: GET)
  --timeout SECONDS     HTTP request timeout in seconds (default: 30.0)
  --retries {0,1,2,3,4,5}
                        retries per request for transient transport/5xx
                        failures (default: 2)
  --json                output the search results in JSON format and exit
  -l LANGUAGE, --language LANGUAGE
                        search results in a specific language (e.g., 'en',
                        'de', 'fr')
  --list-categories     list available categories
  --list-engines        list available engines
  --lucky               opens a random result in web browser and exit
  --no-verify-ssl       do not verify SSL certificates of server (not
                        recommended)
  --nocolor             disable colored output
  --np, --noprompt      just search and exit, do not prompt
  --noua                disable user agent
  -n N, --num N         show N results per page (default: 10); N=0 uses the
                        servers default per page
  --safe-search FILTER  Filter results for safe search. Use 'none',
                        'moderate', or 'strict' (default: strict)
  -w SITE, --site SITE  search sites using site: operator
  -t TIME_RANGE, --time-range TIME_RANGE
                        search results within a specific time range (day,
                        week, month, year)
  --unsafe              allow unsafe search results (same as --safe-search
                        none)
  --url-handler UTIL    Command to open URLs in the browser (default: open)
  --secondary-url-handler UTIL
                        Command to open URLs using secondary handler
  -v, --version         show program's version number and exit
  -F, --files           show results from files section. (same as --categories
                        files)
  -M, --music           show results from music section. (same as --categories
                        music)
  -N, --news            show results from news section. (same as --categories
                        news)
  -S, --social          show results from videos section. (same as
                        --categories social+media)
  -V, --videos          show results from videos section. (same as
                        --categories videos)
  -m N, --max-content-words N
                        maximum number of words to display in result content
                        before truncation (default: 128); N=0 disables
                        truncation

Listing Available Engines and Categories

You can view the available search engines and categories supported by your SearXNG instance using the following options:

# List all available search engines
searxngr --list-engines

# List all available search categories
searxngr --list-categories

These options fetch the current list of engines and categories directly from your configured SearXNG instance and display them in a formatted table. The engine listing includes the engine name, URL, supported bang commands, categories, and reliability score. The category listing shows each category along with the engines that support it.

Query Input Options

searxngr provides flexible ways to specify your search query to handle various use cases and avoid argument parsing conflicts.

Positional Query (Traditional)

The traditional approach uses positional arguments:

searxngr "search query here"
searxngr search query here

Explicit Query Option (-q/--query)

The -q/--query option provides an explicit way to specify your search query:

searxngr -q "search query here"
searxngr --query "search query here"

When to Use -q/--query

The -q/--query option is particularly useful in the following scenarios:

1. Multiple options that might consume arguments:

   # Problem: -e might consume "my query" as its value
   searxngr -e brave "my query"
   
   # Solution: Use -q to explicitly specify the query
   searxngr -e brave -q "my query"

2. Scripting and automation where explicit argument handling is preferred:

   # Script-friendly approach
   searxngr -q "$SEARCH_QUERY" -e "$ENGINES"

3. Complex queries with special characters that might be misinterpreted by the shell:

   searxngr -q "search with 'quotes' and $variables"

Query Priority

When both positional arguments and -q/--query are provided, the -q/--query option takes precedence:

# "explicit query" will be used, not "positional query"
searxngr "positional query" -q "explicit query"

Interactive Console Engine Management

When you run searxngr without the --noprompt flag, you enter an interactive console where you can dynamically change search engines during your session.

Engine Management Commands

Use the e command followed by engine names to modify your search engine selection:

Basic Engine Replacement

# Replace current engines with specific ones
e duckduckgo google brave

# Add engines to current selection
e +bing +yahoo

# Remove engines from current selection
e -bing -yahoo

Secondary URL Handler

The --secondary-url-handler option allows you to configure an alternative method for opening URLs alongside the default handler. This can be useful for having the option to open a link in an alternative browser, or using a command-line tool to fetch content and formate output to the console.

[searxngr]
searxng_url = https://searxng.example.com
url_handler = open                    # System default browser
secondary_url_handler = firefox       # Firefox browser

Usage:

• Regular number input (1, 2, 3...) opens in default browser
• o 1, o 2, o 3... opens in secondary browser (Firefox)

Example for formated text output in the console

The follow example shows how to use command line tools to fetch and format the url content for console output. This uses github.com/scross01/fetch and glow github.com/charmbracelet/glow

brew install glow
uv tool install github.com/scross01/fetch

create fetch-glow.sh script

#!/bin/bash
fetch "$1" | glow

Make it executable

chmod +x fetch-glow.sh

Run searxngr with the following

searxngr "my search query" --secondary-url-handler /path/to/fetch-glow.sh

use o 1, o 2, o 3... to open the result in the console using fetch and glow

Troubleshooting

Error:: Client error '429 Too Many Requests' for url 'https://searxng.example.com'

The SearXNG server is limiting access to the search API. Update server limiter setting or disable limiter for private instances in the service searxng/settings.toml

Error: Could not decode JSON response.

The SearXNG instance may be returning the results in html format. On the SearXNG servers you need to modify the supported search formats to include json in searxng/settings.yml.

search:
  formats:
    - html
    - json