sxng-cli 1.0.7 → 1.0.8

package/README.md

@@ -1,131 +1,182 @@
-# SearXNG CLI
-
-A command-line interface for searching with SearXNG, a privacy-respecting meta search engine. Supports deep multi-round search with knowledge graph, session accumulation, and content extraction.
-
-## Installation
+# 🔍 SXNG CLI
+
+<p align="center">
+  <b>A powerful command-line interface for <a href="https://github.com/searxng/searxng">SearXNG</a></b><br>
+  Privacy-respecting web search from your terminal
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sxng-cli">
+    <img src="https://img.shields.io/npm/v/sxng-cli?style=flat-square&color=cb3837" alt="npm version">
+  </a>
+  <a href="https://www.npmjs.com/package/sxng-cli">
+    <img src="https://img.shields.io/npm/dm/sxng-cli?style=flat-square&color=cb3837" alt="npm downloads">
+  </a>
+  <a href="https://github.com/hkwuks/sxng-cli/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/hkwuks/sxng-cli?style=flat-square&color=green" alt="license">
+  </a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=flat-square" alt="node version">
+</p>
+
+## ✨ Features
+
+- 🔎 **Multi-Engine Search** — Search across Google, Bing, DuckDuckGo, GitHub, StackOverflow, and 30+ engines simultaneously
+- 🔄 **Dynamic Discovery** — Auto-fetches available engines and categories from your SearXNG server
+- 📄 **Multiple Formats** — Markdown (LLM-optimized), JSON, CSV, or HTML output
+- 🧠 **Deep Search** — Multi-round iterative research with session accumulation and knowledge graph
+- 🔍 **Content Extraction** — Extract full article content from search results
+- 🗂️ **Session Management** — Accumulate search results across multiple rounds with deduplication
+- 🕸️ **Knowledge Graph** — Build semantic graphs of entities and relationships
+- ⚡ **Fast & Lightweight** — Built with TypeScript, minimal dependencies
+- 🔧 **Flexible Config** — Environment variables, config file, or interactive setup
+- 🏥 **Health Check** — Verify server connectivity instantly
+- 🌐 **Proxy Support** — HTTP/HTTPS proxy configuration
+
+## 📦 Installation
 
 ```bash
 npm install -g sxng-cli
-# or
-pnpm add -g sxng-cli
-# or
-yarn global add sxng-cli
-```
-
-## Quick Start
-
-1. Set up a SearXNG server:
-```bash
-docker run -d --name searxng -p 8080:8080 searxng/searxng
 ```
 
-2. Create a configuration file:
-```bash
-cp searxng.config.example.json searxng.config.json
-# Edit the file with your settings
-```
+Or from source:
 
-3. Run a search:
 ```bash
-sxng "your search query"
+git clone https://github.com/hkwuks/sxng-cli.git
+cd sxng-cli/cli
+npm install
+npm run build
+npm link
 ```
 
-## Configuration
-
-Configuration can be provided via:
-1. Environment variables (highest priority)
-2. Config file: `./searxng.config.json` or `~/.sxng/config.json`
-3. Default values (lowest priority)
-
-See `searxng.config.example.json` for an example configuration.
-
-## Usage
-
-### Basic Search
+## 🚀 Quick Start
+
+1. **Configure the CLI:**
+   ```bash
+   sxng init
+   ```
+   Or set environment variable:
+   ```bash
+   export SEARXNG_BASE_URL=http://your-searxng-instance:8080
+   ```
+
+2. **Perform a search:**
+   ```bash
+   sxng "TypeScript tutorial"
+   ```
+
+## 📖 Usage
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `sxng init` | Interactive configuration setup |
+| `sxng <query>` | Perform a web search |
+| `sxng --queries "q1,q2"` | Multi-query search with RRF fusion |
+| `sxng extract --urls <urls>` | Extract content from web pages |
+| `sxng --session new` | Create deep search session |
+| `sxng session-list` | List all sessions |
+| `sxng session-delete <session-name>` | Delete a session |
+| `sxng graph-add <session>` | Add entities to knowledge graph |
+| `sxng query-graph <session>` | Query knowledge graph |
+| `sxng --health` | Check SearXNG server health |
+| `sxng --engines-list` | List available search engines from server |
+| `sxng --categories-list` | List available categories from server |
+
+### Search Options
+
+| Option | Description |
+|--------|-------------|
+| `-e, --engines <list>` | Comma-separated list of search engines (e.g., `google,github`) |
+| `-c, --categories <list>` | Comma-separated list of categories (e.g., `it,science`) |
+| `-l, --limit <n>` | Maximum number of results (default: 10) |
+| `-p, --page <n>` | Page number for pagination |
+| `--lang <code>` | Language code (e.g., `en`, `zh`, `ja`) |
+| `--time <range>` | Time range: `day`, `week`, `month`, `year`, `all` |
+| `-f, --format <fmt>` | Output format: `md`, `json`, `csv`, `html` (default: md) |
+| `--queries <list>` | Multi-query with RRF fusion (e.g., `q1,q2,q3`) |
+| `--session <session-name>` | Session directory or `new` for deep search |
+| `--owner <session-name>` | Session owner identifier |
+| `--desc <text>` | Session description |
+
+### Examples
 
 ```bash
-# Simple search
-sxng "TypeScript tutorial"
+# Basic search (outputs Markdown by default)
+sxng "machine learning"
 
-# Limit results
-sxng "TypeScript tutorial" --limit 5
-
-# Use specific engines
-sxng --engines google,github "react hooks"
+# Output as JSON
+sxng --format json "machine learning"
 
-# Search in specific categories
-sxng --categories it,science "machine learning"
+# Search with specific engines
+sxng --engines google,duckduckgo "privacy tools"
 
-# Recent results only
-sxng --time week "latest news"
+# Search IT and Science categories
+sxng --categories it,science "kubernetes tutorial"
 
-# Output as JSON
-sxng -f json "docker tutorial"
+# Limit results and filter by time
+sxng --limit 5 --time week "latest AI news"
 
-# Check server health
-sxng --health
+# Multi-query search with RRF fusion
+sxng --queries "tokio tutorial,rust async basics,async-std guide"
 
-# List available engines
+# List available engines (fetched from server)
 sxng --engines-list
-
-# List available categories
-sxng --categories-list
 ```
 
-### Multi-Query Search
-
-Run multiple queries with RRF (Reciprocal Rank Fusion) result fusion and deduplication:
-
-```bash
-sxng --queries "tokio tutorial,rust async basics,tokio vs async-std"
-```
+## ⚙️ Configuration
 
-### Content Extraction
+Configuration priority (highest to lowest):
+1. Environment variables
+2. Local config file (`./sxng.config.json`)
+3. Global config file (`~/sxng-cli/sxng.config.json`)
+4. Default values
 
-Extract full article content from web pages:
+### Environment Variables
 
-```bash
-# Extract from specific URLs
-sxng extract --urls "https://example.com/article1,https://example.com/article2"
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SEARXNG_BASE_URL` | SearXNG server URL | *(required)* |
+| `SEARXNG_DEFAULT_ENGINE` | Default search engine | *(none)* |
+| `SEARXNG_ALLOWED_ENGINES` | Comma-separated allowed engines | *(all)* |
+| `SEARXNG_DEFAULT_LIMIT` | Default result limit | `10` |
+| `SEARXNG_DEFAULT_FORMAT` | Default output format (`md`, `json`, `csv`, `html`) | `md` |
+| `SEARXNG_USE_PROXY` | Use proxy (`true`/`false`) | `false` |
+| `SEARXNG_PROXY_URL` | Proxy URL | *(none)* |
+| `SEARXNG_TIMEOUT` | Request timeout in ms | `10000` |
 
-# Extract from search results JSON file
-sxng extract --from-json search-results.json
+### Config File
+
+Create `sxng.config.json`:
+
+```json
+{
+  "baseUrl": "http://localhost:8080",
+  "defaultEngine": "",
+  "allowedEngines": [],
+  "defaultLimit": 10,
+  "defaultFormat": "md",
+  "useProxy": false,
+  "proxyUrl": "",
+  "timeout": 10000
+}
 ```
 
-## Deep Search
+## 🧠 Deep Search
 
 Deep search enables multi-round iterative research with session accumulation and knowledge graph building.
 
-### Session Management
-
-```bash
-# Create a new session with auto-generated name
-sxng --session new --owner "research-agent" --desc "Rust async research" "rust async ecosystem"
-
-# List all sessions
-sxng session-list
-
-# Delete a specific session
-sxng session-delete <session-name>
-
-# Delete sessions older than N hours
-sxng session-delete --older 24
-```
-
-### Deep Search Workflow
-
-The deep search flow follows an iterative loop: search → extract → analyze → build graph → decide.
+### Quick Example
 
 ```bash
-# Round 1: Create session and search
-sxng --session new --owner "agent-1" --desc "async ecosystem research" "rust async ecosystem"
-# Note the returned session path, e.g., ~/.sxng/sessions/<session-name>
+# Create a session and search
+sxng --session new --owner "researcher" --desc "Rust async study" "rust async ecosystem"
 
 # Extract content from results
-sxng extract --session ~/.sxng/sessions/<session-name>
+sxng extract --session <session-name>
 
-# Add entities and relationships to knowledge graph
-sxng graph-add ~/.sxng/sessions/<session-name> --data '{
+# Add knowledge graph entities
+sxng graph-add <session-name> --data '{
   "entities": [
     {"label": "tokio", "entityType": "runtime", "score": 0.95},
     {"label": "async-std", "entityType": "runtime", "score": 0.85}
@@ -135,67 +186,44 @@ sxng graph-add ~/.sxng/sessions/<session-name> --data '{
   ]
 }'
 
-# Query the knowledge graph
-sxng query-graph ~/.sxng/sessions/<session-name> --seeds "tokio" --depth 2
-
-# Round 2: Search with multiple queries (results accumulate in session)
-sxng --session ~/.sxng/sessions/<session-name> --queries "tokio vs async-std comparison,rust async benchmark 2024"
+# Query the graph
+sxng query-graph <session-name> --seeds "tokio" --depth 2
 
-# Extract again and continue the loop...
+# Continue research (results accumulate)
+sxng --session <session-name> --queries "tokio vs async-std,benchmark 2024"
 ```
 
-### Session Data Structure
+### Session Management
 
-Each session stores three files in `~/.sxng/sessions/<session-name>/`:
+| Command | Description |
+|---------|-------------|
+| `sxng --session new` | Create new auto-named session |
+| `sxng --session <session-name>` | Use session by name |
+| `sxng session-list` | List all sessions with stats |
+| `sxng session-delete <session-name>` | Delete specific session |
+| `sxng session-delete --older <hours>` | Delete old sessions |
 
-- **`results.json`** — Accumulated search result pool (URL dedup, multi-round accumulation)
-- **`graph.json`** — Knowledge graph (structural + semantic layers)
-- **`meta.json`** — Session metadata (owner, description, timestamps)
+**Session Path Resolution:**
+- Pure name (e.g., `my-session`) → `~/.sxng/sessions/my-session`
+- Full path (e.g., `/custom/path/session`) → used as-is
+- `new` → auto-generate unique name under `~/.sxng/sessions/`
 
 ### Knowledge Graph
 
-The graph has two layers:
-
-**Structural Layer** (auto-built by CLI every search):
-
-| Node type | Prefix | Attributes |
-|-----------|--------|------------|
-| query | `q:` | label, query, round |
-| result | `r:` | label, url, title, rank |
-| domain | `d:` | label, domain |
-
-**Semantic Layer** (added via `graph-add`):
-
-| Node type | Prefix | Attributes |
-|-----------|--------|------------|
-| entity | `e:` | label, entityType, score |
-
-## Options Reference
+**Structural Layer** (auto-built):
+- `q:` — Query nodes
+- `r:` — Result nodes
+- `d:` — Domain nodes
 
-| Option | Short | Description | Example |
-|--------|-------|-------------|---------|
-| `--limit` | `-l` | Max results | `-l 20` |
-| `--engines` | `-e` | Specific search engines | `-e google,github` |
-| `--categories` | `-c` | Filter by category | `-c it,science` |
-| `--page` | `-p` | Pagination | `-p 2` |
-| `--lang` | | Result language | `--lang zh` |
-| `--time` | | Time filter | `--time week` |
-| `--format` | `-f` | Output format | `-f json` |
-| `--queries` | | Multi-query with RRF fusion | `--queries "q1,q2,q3"` |
-| `--session` | | Session directory or "new" | `--session new` |
-| `--owner` | | Session owner identifier | `--owner "agent-1"` |
-| `--desc` | | Session description | `--desc "research topic"` |
+**Semantic Layer** (via `graph-add`):
+- `e:` — Entity nodes with type and score
 
-## Environment Variables
+## 🔗 Links
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SEARXNG_BASE_URL` | SearXNG server URL | `http://localhost:8080` |
-| `SEARXNG_DEFAULT_LIMIT` | Default result limit | `10` |
-| `SEARXNG_TIMEOUT` | Request timeout in ms | `10000` |
-| `SEARXNG_USE_PROXY` | Use proxy (`true`/`false`) | `false` |
-| `SEARXNG_PROXY_URL` | Proxy URL | (none) |
+- **GitHub:** https://github.com/hkwuks/sxng-cli
+- **npm:** https://www.npmjs.com/package/sxng-cli
+- **SearXNG:** https://github.com/searxng/searxng
 
-## License
+## 📄 License
 
-MIT
+MIT

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "sxng-cli",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "SearXNG CLI - Web Search Tool",
+  "homepage": "https://github.com/hkwuks/sxng-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hkwuks/sxng-cli.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hkwuks/sxng-cli/issues"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",