Metadata-Version: 2.4
Name: searxng-cli
Version: 0.1.0
Summary: Self-contained SearXNG search CLI and Python library: in-process metasearch without a web server
Author-email: Pliosauroideas <Pliosauroide@protonmail.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/Pliosauroideas/searxng-cli
Project-URL: Repository, https://github.com/Pliosauroideas/searxng-cli
Project-URL: Source, https://github.com/Pliosauroideas/searxng-cli
Keywords: searxng,search,metasearch,cli,privacy,web-search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: babel<3,>=2.18
Requires-Dist: certifi>=2026.7
Requires-Dist: flask<4,>=3.1.3
Requires-Dist: flask-babel<5,>=4
Requires-Dist: httpx[http2]<1,>=0.28.1
Requires-Dist: httpx-socks[asyncio]<1,>=0.10
Requires-Dist: isodate<1,>=0.7.2
Requires-Dist: jinja2<4,>=3.1.6
Requires-Dist: lxml<7,>=6.1
Requires-Dist: markdown-it-py<5,>=4.2
Requires-Dist: msgspec<0.22,>=0.21.1
Requires-Dist: pygments<3,>=2.20
Requires-Dist: python-dateutil<3,>=2.9
Requires-Dist: pyyaml<7,>=6.0.3
Requires-Dist: sniffio<2,>=1.3
Requires-Dist: typer<1,>=0.27
Requires-Dist: typing-extensions>=4.16
Requires-Dist: valkey<7,>=6.1
Requires-Dist: whitenoise<7,>=6.12
Dynamic: license-file

# searxng-cli

A self-contained, in-process [SearXNG](https://github.com/searxng/searxng) search
CLI and Python library. It embeds a trimmed SearXNG search core, does not start
a web server, and writes one JSON object to stdout per invocation.

## Install

Requires Python 3.11 or newer.

```bash
pip install searxng-cli
```

With `uv`:

```bash
uv tool install searxng-cli
uvx searxng-cli "query"
```

## CLI usage

```bash
searxng-cli "SearXNG CLI" --engines github --max-results 5
searxng-cli "quantum computing" --category science
searxng-cli "AI agent framework" --category it --max-results 5
searxng-cli "量子计算" --language zh-CN
searxng-cli --list-engines
```

Output is JSON:

```json
{
  "query": "SearXNG CLI",
  "results": [{"url": "...", "title": "...", "content": "...", "engine": "github", "score": 1.0}],
  "engine_stats": {"github": {"elapsed_sec": 0.8, "error": null}},
  "elapsed_sec": 0.8,
  "result_count": 1
}
```

When `--engines` is omitted, the package uses the curated per-category engine
whitelist shipped in `searxng_cli/settings/searxng_pack_settings.yml`. Override
the settings file with the `SEARXNG_CLI_SETTINGS` environment variable:

```bash
SEARXNG_CLI_SETTINGS=/path/to/searxng_pack_settings.yml searxng-cli "query"
```

## Python library

```python
import searxng_cli

listing = searxng_cli.list_engines()
result = searxng_cli.search(
    "SearXNG CLI",
    engines="github",
    category="it",
    language="all",
    max_results=5,
    timeout=15,
)

print(result["result_count"])
for item in result["results"]:
    print(item["title"], item["url"])
```

`searxng_cli.search()` performs its first SearXNG initialization inside the
current process. Long-running applications that need to switch settings files
between searches should run those searches in separate processes; the CLI
already follows that one-process-per-search model.

## Network and engines

SearXNG engines contact upstream services directly. Some engines may be
unreachable without a proxy in certain networks. Configure a proxy in the
settings file or use `SEARXNG_CLI_SETTINGS` with a custom SearXNG YAML file.

## License

This package embeds and derives from SearXNG and is licensed under
[AGPL-3.0-or-later](LICENSE). All third-party copyright notices remain intact
in the vendored source tree.
