searxngr

KO | EN

gitlite — search

#open-source #python #react #hacktoberfest #java #cli #macos #ai #agent #rust #machine-learning #docker

★ 47 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# searxngr

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

![demo](https://raw.githubusercontent.com/scross01/searxngr/main/demo/demo.gif)

`searxngr` is a command-line interface (CLI) tool that allows you to perform web
searches using [SearXNG](https://github.com/searxng/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`](https://docs.astral.sh/uv/getting-started/installation/) package manager.

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

To install from source

```shell
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:

```shell
$ 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`:

```shell
$ 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:

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

### Configuration File

```ini
[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:

```shell
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.

```shell
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.

```txt
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:

```shell
# 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:

```shell
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:

```shell
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**:

```shell
   # 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"
   ```

1. **Scripting and automation** where explicit argument handling is preferred:

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

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

```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:

```shell
# "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

```shell
# 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.

```ini
[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](https://github.com/scross01/fetch) and glow
[github.com/charmbracelet/glow](glow)

```shell
brew install grow
uv tool install github.com/scross01/fetch
```

create `fetch-glow.sh` script

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

Make it executable

```shell
chmod +x fetch-glow.sh
```

Run `searxngr` with the following

```shell
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`.

```yaml
search:
  formats:
    - html
    - json
```

searxngr

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README