omnisearch-cli 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OmniSearch SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# omnisearch-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> High-performance command-line interface for multi-provider web search retrieval, powered by [`omnisearch-sdk`](https://www.npmjs.com/package/omnisearch-sdk).
+
+Search across Google, Brave, Bing, DuckDuckGo, Tavily, Perplexity, PubMed, Arxiv, GitHub, and more directly from your terminal or shell scripts.
+
+---
+
+## ⚡ Quick Start
+
+Run directly with `npx` (no installation required):
+
+```bash
+# Basic web search (auto-detects configured providers or falls back to DuckDuckGo)
+npx omnisearch-cli "autonomous AI agents"
+
+# Search specific engine (e.g. Brave, PubMed, GitHub)
+npx omnisearch-cli "CRISPR gene editing" -p pubmed -n 5
+
+# Recent news (past 24h) with JSON output for piping to jq
+npx omnisearch-cli "latest AI models" -p brave -f day --type news --json
+```
+
+Or install globally:
+
+```bash
+npm install -g omnisearch-cli
+# or
+pnpm add -g omnisearch-cli
+
+omnisearch "quantum computing" -n 5
+```
+
+---
+
+## 🛠 Command-Line Options
+
+```text
+Usage:
+  omnisearch "<query>" [options]
+
+Options:
+  -p, --provider <name>     Search provider to use (default: auto-detect)
+  -f, --freshness <period>  Filter by recency: day, week, month, year
+  -s, --strategy <mode>     Execution mode: parallel, fallback, race (default: parallel)
+  -n, --max-results <num>   Maximum results to return (default: 10)
+  --type <type>             Search type: web, news (default: web)
+  --dedupe                  Enable canonical URL deduplication
+  --json                    Output raw JSON (ideal for scripting and jq)
+  -h, --help                Show help message
+```
+
+---
+
+## 🌐 Supported Providers
+
+The CLI automatically detects providers based on available environment variables:
+
+| Provider Flag | Engine | Requires API Key? | Environment Variables |
+| :--- | :--- | :--- | :--- |
+| `-p duckduckgo` | DuckDuckGo | **No** (Zero-config) | None |
+| `-p pubmed` | PubMed / NCBI | **No** (Zero-config) | None |
+| `-p arxiv` | Arxiv Preprints | **No** (Zero-config) | None |
+| `-p semanticscholar` | Semantic Scholar | **No** (Zero-config) | None |
+| `-p github` | GitHub Search | **Optional** | `GITHUB_TOKEN` |
+| `-p brave` | Brave Search | **Yes** | `BRAVE_API_KEY` |
+| `-p google` | Google Search | **Yes** | `GOOGLE_API_KEY`, `GOOGLE_CX` |
+| `-p bing` | Bing Web Search | **Yes** | `BING_API_KEY` |
+| `-p you` | You.com Search | **Yes** | `YOU_API_KEY` |
+| `-p tavily` | Tavily Search | **Yes** | `TAVILY_API_KEY` |
+| `-p exa` | Exa Neural Search | **Yes** | `EXA_API_KEY` |
+| `-p perplexity` | Perplexity AI | **Yes** | `PERPLEXITY_API_KEY` |
+| `-p parallel` | Parallel Search | **Yes** | `PARALLEL_API_KEY` |
+| `-p serpapi` | SerpAPI | **Yes** | `SERPAPI_API_KEY` |
+| `-p searxng` | SearXNG | **Yes** | `SEARXNG_BASE_URL` |
+
+---
+
+## 💡 Examples
+
+### 1. Multi-Engine Cascading Fallback
+Try Brave first; if rate-limited or unavailable, gracefully fall back to DuckDuckGo:
+```bash
+omnisearch "TypeScript 6 release date" --strategy fallback
+```
+
+### 2. Live Shell Scripting with `jq`
+Fetch the top 3 URLs in JSON:
+```bash
+omnisearch "Rust memory safety" --json | jq '.[].url'
+```
+
+### 3. Academic Paper Discovery
+```bash
+omnisearch "transformer architecture attention is all you need" -p arxiv -n 3
+```
+
+---
+
+## 📄 License
+
+MIT © [OmniSearch SDK Contributors](https://github.com/gbks121/omnisearch-sdk)

package/dist/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { parseArgs } from "util";
+import {
+  createArxivProvider,
+  createBingProvider,
+  createBraveProvider,
+  createDuckDuckGoProvider,
+  createExaProvider,
+  createGitHubProvider,
+  createGoogleProvider,
+  createParallelProvider,
+  createPerplexityProvider,
+  createPubMedProvider,
+  createSearXNGProvider,
+  createSemanticScholarProvider,
+  createSerpApiProvider,
+  createTavilyProvider,
+  createYouProvider,
+  webSearch
+} from "omnisearch-sdk";
+function showHelp() {
+  console.log(`
+OmniSearch CLI - High-performance multi-provider search
+
+Usage:
+  omnisearch "<query>" [options]
+
+Options:
+  -p, --provider <name>     Provider to use (brave, google, duckduckgo, etc.) Default: auto
+  -f, --freshness <period>  Freshness filter (day, week, month, year)
+  -s, --strategy <mode>     Execution strategy (parallel, fallback, race) Default: parallel
+  -n, --max-results <num>   Maximum results to return. Default: 10
+  --type <type>             Search type (web, news). Default: web
+  --dedupe                  Enable canonical URL deduplication
+  --json                    Output raw JSON results
+  -h, --help                Show this help message
+
+Environment Variables:
+  BRAVE_API_KEY, GOOGLE_API_KEY, GOOGLE_CX, TAVILY_API_KEY, EXA_API_KEY,
+  PERPLEXITY_API_KEY, BING_API_KEY, YOU_API_KEY, PARALLEL_API_KEY, SERPAPI_API_KEY
+`);
+}
+function resolveProviders(providerName) {
+  const env = process.env;
+  const name = providerName?.toLowerCase();
+  const registry = {
+    duckduckgo: () => createDuckDuckGoProvider(),
+    arxiv: () => createArxivProvider(),
+    pubmed: () => createPubMedProvider(),
+    github: () => createGitHubProvider({ apiKey: env.GITHUB_TOKEN || env.GITHUB_API_KEY }),
+    brave: () => env.BRAVE_API_KEY || env.BRAVE_SEARCH_API_KEY ? createBraveProvider({ apiKey: env.BRAVE_API_KEY || env.BRAVE_SEARCH_API_KEY }) : null,
+    google: () => env.GOOGLE_API_KEY && env.GOOGLE_CX ? createGoogleProvider({ apiKey: env.GOOGLE_API_KEY, cx: env.GOOGLE_CX }) : null,
+    tavily: () => env.TAVILY_API_KEY ? createTavilyProvider({ apiKey: env.TAVILY_API_KEY }) : null,
+    exa: () => env.EXA_API_KEY ? createExaProvider({ apiKey: env.EXA_API_KEY }) : null,
+    perplexity: () => env.PERPLEXITY_API_KEY ? createPerplexityProvider({ apiKey: env.PERPLEXITY_API_KEY }) : null,
+    bing: () => env.BING_API_KEY ? createBingProvider({ apiKey: env.BING_API_KEY }) : null,
+    you: () => env.YOU_API_KEY ? createYouProvider({ apiKey: env.YOU_API_KEY }) : null,
+    parallel: () => env.PARALLEL_API_KEY ? createParallelProvider({ apiKey: env.PARALLEL_API_KEY }) : null,
+    serpapi: () => env.SERPAPI_API_KEY ? createSerpApiProvider({ apiKey: env.SERPAPI_API_KEY }) : null,
+    searxng: () => env.SEARXNG_BASE_URL ? createSearXNGProvider({ baseUrl: env.SEARXNG_BASE_URL }) : null,
+    semanticscholar: () => createSemanticScholarProvider()
+  };
+  if (name) {
+    const factory = registry[name];
+    if (!factory) {
+      console.error(`Unknown provider: ${name}`);
+      process.exit(1);
+    }
+    const instance = factory();
+    if (!instance) {
+      console.error(`Missing required environment variables/API keys for provider: ${name}`);
+      process.exit(1);
+    }
+    return [instance];
+  }
+  const available = [];
+  for (const [_, factory] of Object.entries(registry)) {
+    const inst = factory();
+    if (inst) available.push(inst);
+  }
+  if (available.length === 0) {
+    available.push(createDuckDuckGoProvider());
+  }
+  return available;
+}
+async function runCli() {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      provider: { type: "string", short: "p" },
+      freshness: { type: "string", short: "f" },
+      strategy: { type: "string", short: "s", default: "parallel" },
+      "max-results": { type: "string", short: "n", default: "10" },
+      type: { type: "string", default: "web" },
+      dedupe: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    },
+    allowPositionals: true
+  });
+  if (values.help || positionals.length === 0) {
+    showHelp();
+    return;
+  }
+  const query = positionals.join(" ").trim();
+  const providers = resolveProviders(values.provider);
+  const maxResults = Number.parseInt(values["max-results"] ?? "10", 10);
+  const strategy = values.strategy;
+  const freshness = values.freshness;
+  const searchType = values.type;
+  try {
+    const results = await webSearch({
+      query,
+      provider: providers,
+      maxResults,
+      strategy,
+      freshness,
+      searchType,
+      deduplicate: values.dedupe
+    });
+    if (values.json) {
+      console.log(JSON.stringify(results, null, 2));
+      return;
+    }
+    if (results.length === 0) {
+      console.log(`No results found for "${query}".`);
+      return;
+    }
+    console.log(`
+Found ${results.length} results for "${query}":
+`);
+    results.forEach((item, idx) => {
+      console.log(`${idx + 1}. [${item.provider}] ${item.title}`);
+      console.log(`   ${item.url}`);
+      if (item.snippet) {
+        console.log(`   ${item.snippet.slice(0, 160)}${item.snippet.length > 160 ? "..." : ""}`);
+      }
+      if (item.publishedDate) {
+        console.log(`   Published: ${item.publishedDate}`);
+      }
+      console.log("");
+    });
+  } catch (error) {
+    console.error("Search error:", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+runCli();
+export {
+  runCli
+};

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "omnisearch-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Command-line interface for OmniSearch SDK",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "omnisearch": "./dist/index.js",
+    "omnisearch-cli": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "omnisearch-sdk": "5.0.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
 }