searxngr

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

demo

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.

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 .

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.my-instance.local
Disable SSL verification (y/N)? y
Connection successful.
Initial setting created. Run 'searxngr --config' again to edit all settings.

The setup will:

Prompt for your SearXNG instance URL
If using HTTPS, ask whether to disable SSL verification
Validate that the instance is reachable
Create the configuration file
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
# 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 - Timeout in seconds. Default is 30.
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

Options

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

usage: searxngr [-h] [--searxng-url SEARXNG_URL] [-c [CATEGORY ...]] [--config] [-d] [-e [ENGINE ...]] [-x] [-j]
                [--http-method METHOD] [--timeout SECONDS] [--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] [-v] [-F] [-M] [-N] [-S] [-V]
                [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_OPT
explicit search query (alternative to positional query)
--searxng-url SEARXNG_URL
SearXNG instance URL (default: NOT SET)
-c, --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, --engines [ENGINE ...]
list of engines to use for the search (default: NOT SET)
-x, --expand          Show complete url in search results
-m N, --max-content-words N
maximum number of words to display in result content
before truncating (default: 128); N=0 disables
-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)
--json                output the search results in JSON format and exit
-l, --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, --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       search sites using site: operator
-t, --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)
-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)

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:

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"

Scripting and automation where explicit argument handling is preferred:

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

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 grow
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

NAME

SYNOPSIS

INFO

DESCRIPTION

README