searxng-ai-kit

SearXNG AI Kit

AI-powered search for your terminal, code, and AI assistants

An AI-enhanced command-line interface, Python library, and MCP server for the SearXNG privacy-respecting metasearch engine. Research topics with AI assistance, search the web from your terminal, integrate into Python projects, or connect AI assistants with support for 180+ search engines.

Features

🔍 CLI tool - Search from your terminal with AI-enhanced research capabilities
🤖 AI chat - Ask questions and get comprehensive research using 180+ search engines
🐍 Python library - Programmatic search and AI-powered content retrieval
🔌 MCP server - AI assistant integration with advanced research tools
📦 Standalone binaries - Pre-built executables for Linux and macOS

Installation

Download a Standalone Binary (Recommended)

The recommended install path is to download the pre-built binary for your platform from the GitHub releases page.

The source install path has to build and vendor a pinned SearXNG wheel before the CLI can run, so it is slower and more involved than a normal uv tool install. Use the binary unless you are developing the project or intentionally updating the pinned upstream SearXNG version.

Release binaries are currently published for Linux and macOS. Windows binaries are disabled for now because the current pybin Windows package launcher is not native yet.

After downloading, make the binary executable and put it somewhere on your PATH:

chmod +x searxng-ai-kit-*
./searxng-ai-kit-* --help

Install from Source with uv (Advanced)

Use this path when you want to develop the project, inspect the vendored SearXNG build, or update the pinned SearXNG commit.

Prerequisites:

• Python 3.11+
• uv

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh git clone https://github.com/nikvdp/searxng-ai-kit
cd searxng-ai-kit # Build the pinned SearXNG wheel and set up the local environment
uv run python dev-setup.py # Install as a uv tool
uv tool install . # Verify
searxng --help

Development Setup

# Clone and set up for development
git clone https://github.com/nikvdp/searxng-ai-kit
cd searxng-ai-kit # Build SearXNG wheel, generate configs, sync dependencies
python dev-setup.py # Test
uv run searxng search "test" --engines duckduckgo

The build system automatically:

• Installs Python 3.11+ via uv
• Builds SearXNG wheel with proper dependency isolation
• Handles modern type annotations (str | Exception)
• Generates local configuration files

Usage Examples

Basic Search

# Simple search with default engines
searxng search "python tutorial" # Search with specific engines
searxng search "machine learning" --engines duckduckgo,startpage # Search in specific category
searxng search "neural networks" --category science

Engine Management

# List all available engines (compact overview)
searxng engines # List common engines only (clean 4-column layout)
searxng engines --common # List engines in specific category
searxng engines --category general # List only common engines in a category
searxng engines --category general --common # Search while disabling specific engines
searxng search "web development" --disable google,bing

Output Formats

# Human-readable output (default)
searxng search "AI research" # JSON output for scripting
searxng search "data science" --format json # JSON output with specific engines
searxng search "rust programming" --engines duckduckgo --format json > results.json

Advanced Options

# Search with language preference
searxng search "tutorial python" --lang fr # Search with safe search enabled
searxng search "programming" --safe 1 # Search recent results only
searxng search "tech news" --time week --category news # Search specific page
searxng search "javascript" --page 2

URL Content Retrieval

# Fetch content from a single URL
searxng fetch-urls "https://example.com" # Fetch content from multiple URLs in parallel
searxng fetch-urls "https://site1.com" "https://site2.com" "https://site3.com" # Human-readable output (default)
searxng fetch-urls "https://example.com" # JSON output for scripting
searxng fetch-urls "https://docs.python.org" --format json > content.json # Control concurrency for rate limiting
searxng fetch-urls url1 url2 url3 --concurrent 2

Browse Available Options

# List all search categories
searxng categories # Get help for any command
searxng search --help
searxng engines --help

Available Categories

• general - General web search (51 engines)
• images - Image search (34 engines)
• videos - Video search (29 engines)
• news - News search (18 engines)
• science - Scientific publications (9 engines)
• it - IT/Programming resources (44 engines)
• music - Music search (10 engines)
• files - File search (17 engines)
• maps - Map search (3 engines)
• And many more...

Common Engines

⭐ Most Popular:

• duckduckgo - Privacy-focused search
• startpage - Google results without tracking
• brave - Independent search index
• google - Google search
• bing - Microsoft search
• qwant - European search engine

Testing the CLI

Test Basic Functionality

# Test categories listing
uv run searxng categories
# Or: searxng categories # Test clean engine listing (shows popular engines in 4 columns)
uv run searxng engines --common
# Or: searxng engines --common # Test engine overview (compact category summary)
uv run searxng engines
# Or: searxng engines # Test simple search
uv run searxng search "test query" --engines duckduckgo
# Or: searxng search "test query" --engines duckduckgo

Test Different Output Formats

# Test human-readable output
uv run searxng search "python" --engines duckduckgo | head -20
# Or: searxng search "python" --engines duckduckgo | head -20 # Test JSON output
uv run searxng search "programming" --engines duckduckgo --format json | jq .
# Or: searxng search "programming" --engines duckduckgo --format json | jq .

Test Multiple Engines

# Test with multiple engines
uv run searxng search "web development" --engines duckduckgo,startpage
# Or: searxng search "web development" --engines duckduckgo,startpage # Test engine filtering
uv run searxng search "javascript" --category general --disable google,bing
# Or: searxng search "javascript" --category general --disable google,bing

Test Categories

# Test different categories
uv run searxng search "machine learning" --category science --engines arxiv
# Or: searxng search "machine learning" --category science --engines arxiv uv run searxng search "react tutorial" --category it --engines github
# Or: searxng search "react tutorial" --category it --engines github uv run searxng search "funny cats" --category images --engines duckduckgo_images
# Or: searxng search "funny cats" --category images --engines duckduckgo_images

Building Executable (Optional)

To create a standalone executable:

# Sync development dependencies (includes PyInstaller)
uv sync # Build with PyInstaller (no code signing)
uv run pyinstaller searxng.spec # Test the executable
./dist/searxng --help
./dist/searxng search "test" --engines duckduckgo

Code Signing (macOS only)

For distribution on macOS, you can optionally enable code signing if you have a valid Developer ID certificate:

# Set environment variables for code signing
export PYINSTALLER_CODESIGN_IDENTITY="Developer ID Application: Your Name"
export PYINSTALLER_ENTITLEMENTS_FILE="entitlements.plist" # optional # Build with code signing
uv run pyinstaller searxng.spec

Note: The executable may have some engine loading issues. The Python version is recommended for full functionality.

AI Assistant Integration

SearXNG AI Kit includes an AI assistant feature that combines web search capabilities with powerful language models. The assistant can perform parallel searches and fetch content from multiple URLs to provide comprehensive research and answers.

Ask Command (One-Shot Q&A)

# Ask a question using the default model
searxng ask "What are the latest developments in quantum computing?" # Use a model from the registry
searxng ask "Research renewable energy trends" --model "opencode/big-pickle" # Use a LiteLLM model string directly
searxng ask "Explain AI" --model "openai/gpt-4o-mini" # Get JSON output for programmatic use
searxng ask "Compare Python vs JavaScript" --format json # Read prompt from stdin for longer questions
echo "Analyze the current state of renewable energy adoption globally, including recent policy changes and technological breakthroughs" | searxng ask # Interactive stdin mode
searxng ask
# (then type your question and press Ctrl+D) # Pipe from file
searxng ask < my_research_question.txt

Chat Command (Interactive Conversations)

# Start an interactive chat session (uses default model)
searxng chat # Use a model from the registry
searxng chat --model "opencode/glm-4.7" # Use a LiteLLM model string directly
searxng chat --model "openai/gpt-4o-mini" # Use OpenRouter models
searxng chat --model "openrouter/anthropic/claude-3.5-sonnet" # Use custom API endpoint
searxng chat --base-url "https://api.openai.com/v1"

The chat command maintains conversation history and allows follow-up questions:

You: What's the weather like in Tokyo?
Assistant: [searches for current Tokyo weather information] You: How about tomorrow?
Assistant: [remembers we're discussing Tokyo weather and searches for tomorrow's forecast] You: What should I wear?
Assistant: [provides clothing recommendations based on the weather information from previous searches]

Chat Features:

• Conversation Memory: Remembers all previous messages in the session
• Context Awareness: References earlier parts of the conversation
• Chat History: Automatically saves conversations to markdown files
• Model Display: Shows model name (e.g., o3) instead of generic "Assistant"
• Progress Indicator: Animated spinner while waiting for AI responses
• Exit Commands: Type exit, quit, bye, or press Ctrl+C to end
• Web Search: Full access to search tools during conversations
• Tool Visibility: Shows search queries and URL fetches in real-time

Chat History Location:

• Saved to: ~/.local/share/searxng-ai-kit/chats/ (XDG Base Directory spec)
• Format: chat-YYYY-MM-DD_HH-MM-SS-modelname.md
• Example: chat-2025-06-29_14-30-15-o3.md

Model Registry

SearXNG AI Kit uses a model registry to manage AI model configurations. Models from various providers can be imported and used with simple names.

List Available Models

# List all models in registry
searxng models list # Show details for a specific model
searxng models show "opencode/big-pickle"

Set Default Model

# Set a default model (used when --model not specified)
searxng models set-default "opencode/big-pickle" # Show current default
searxng models set-default

Import from OpenCode

If you use OpenCode, you can import your configured models:

# Preview what would be imported
searxng models import opencode --dry-run # Import models from OpenCode config
searxng models import opencode

This imports models from ~/.config/opencode/opencode.jsonc and ~/.local/share/opencode/auth.json.

Using Models

# Use a model from the registry
searxng ask "What is quantum computing?" --model "opencode/big-pickle" # Use with chat
searxng chat --model "opencode/glm-4.7" # If default is set, just run without --model
searxng ask "Explain machine learning"

The --model flag accepts:

• Registry names: opencode/big-pickle, cli-proxy-api/claude-sonnet-4
• LiteLLM strings: openai/gpt-4o, anthropic/claude-3-5-sonnet

Manual Model Management

# Add a model manually
searxng models add "my-model" --type openai --model-id gpt-4o --api-key "sk-..." # Remove a model
searxng models remove "my-model" # Edit models file directly
searxng models edit

Models are stored in ~/.config/searxng/models.toml.

API Key Configuration

Set one of these environment variables (used when model doesn't have stored API key):

# OpenAI (recommended)
export OPENAI_API_KEY="your-openai-key" # OpenRouter (access to many models)
export OPENROUTER_API_KEY="your-openrouter-key" # Anthropic
export ANTHROPIC_API_KEY="your-anthropic-key" # Google
export GOOGLE_API_KEY="your-google-key"

OpenRouter Integration

OpenRouter provides access to many AI models through a single API. SearXNG Kit has native OpenRouter support:

# Set OpenRouter API key
export OPENROUTER_API_KEY="your-openrouter-key" # Use OpenRouter models with native prefix
searxng ask "Analyze market trends" --model "openrouter/openai/gpt-4o-mini"
searxng ask "Technical research" --model "openrouter/anthropic/claude-3.5-sonnet" # Use custom base URL (alternative method)
searxng ask "Question" --base-url "https://openrouter.ai/api/v1" --model "openai/gpt-4o-mini"

CLI Proxy API Integration

SearXNG AI Kit integrates with CLI Proxy API to provide access to multiple AI providers through their OAuth and subscription plans - no API keys needed! Use your existing Claude Pro, ChatGPT Plus, or Gemini Advanced subscriptions.

Step 1: Install CLI Proxy API

Download the latest release from GitHub:

# macOS (Apple Silicon)
curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-darwin-arm64 -o cli-proxy-api
chmod +x cli-proxy-api
sudo mv cli-proxy-api /usr/local/bin/ # macOS (Intel)
curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-darwin-amd64 -o cli-proxy-api
chmod +x cli-proxy-api
sudo mv cli-proxy-api /usr/local/bin/ # Linux (x64)
curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-linux-amd64 -o cli-proxy-api
chmod +x cli-proxy-api
sudo mv cli-proxy-api /usr/local/bin/

Or build from source: https://github.com/router-for-me/CLIProxyAPI