exa-search-cli 0.1.0__py3-none-any.whl

exa_cli/main.py

@@ -0,0 +1,222 @@
+import argparse
+import json
+import os
+import re
+import sys
+import textwrap
+
+from exa_py import Exa
+from exa_py.api import ContentsOptions
+
+TEXT_PREVIEW_LEN = 2000
+
+CATEGORIES = [
+    "news", "tweet", "github", "paper", "company",
+    "research paper", "financial report", "personal site",
+    "pdf", "linkedin profile",
+]
+
+
+def _client() -> Exa:
+    key = os.environ.get("EXA_API_KEY")
+    if not key:
+        sys.exit("EXA_API_KEY not set. Export your key: export EXA_API_KEY=your-key")
+    return Exa(api_key=key)
+
+
+def _dump_json(data) -> None:
+    if hasattr(data, "__dict__"):
+        print(json.dumps(data.__dict__, default=str, ensure_ascii=False, indent=2))
+    else:
+        print(json.dumps(data, default=str, ensure_ascii=False, indent=2))
+
+
+def _meta(r) -> str:
+    parts = []
+    if getattr(r, "published_date", None):
+        parts.append(r.published_date[:10])
+    if getattr(r, "author", None):
+        parts.append(r.author)
+    return "  ·  ".join(parts) if parts else ""
+
+
+def _clean(text: str) -> str:
+    text = re.sub(r"(\[\.\.\.\]\s*){2,}", "[...]\n", text)
+    lines = [ln for ln in text.splitlines() if not re.fullmatch(r"\s*\d{0,3}\s*", ln)]
+    return "\n".join(lines).strip()
+
+
+def _snippet(r, full_text: bool = False) -> str:
+    text = getattr(r, "text", None) or ""
+    highlights = getattr(r, "highlights", None) or []
+
+    if full_text and text:
+        preview = text[:TEXT_PREVIEW_LEN]
+        tail = "…" if len(text) > TEXT_PREVIEW_LEN else ""
+        return textwrap.fill(preview + tail, width=100)
+
+    if highlights:
+        parts = []
+        for h in highlights:
+            cleaned = _clean(h.strip())
+            if cleaned:
+                parts.append(textwrap.fill(cleaned, width=100))
+        return "\n\n".join(parts)
+
+    if text:
+        preview = text.strip()[:600]
+        return textwrap.fill(preview + ("…" if len(text) > 600 else ""), width=100)
+
+    return ""
+
+
+def _print_results(results, response, full_text: bool = False) -> None:
+    for i, r in enumerate(results, 1):
+        title = getattr(r, "title", None) or "(no title)"
+        url = getattr(r, "url", "") or getattr(r, "id", "")
+        meta = _meta(r)
+        snippet = _snippet(r, full_text)
+
+        print(f"[{i}] {title}")
+        print(f"    {url}")
+        if meta:
+            print(f"    {meta}")
+        if snippet:
+            indented = "\n".join("    " + line for line in snippet.splitlines())
+            print(indented)
+        print()
+
+    cost = getattr(response, "cost_dollars", None)
+    t = getattr(response, "search_time", None)
+    cost_str = f"${cost.total:.4f}" if cost and hasattr(cost, "total") else ""
+    time_str = f"{t/1000:.1f}s" if t else ""
+    footer = "  ·  ".join(filter(None, [f"{len(results)} results", cost_str, time_str]))
+    print(f"── {footer} ──")
+
+
+def _split_domains(value: str | None) -> list[str] | None:
+    if not value:
+        return None
+    return [d.strip() for d in value.split(",") if d.strip()]
+
+
+def search() -> None:
+    p = argparse.ArgumentParser(
+        description="Exa web search",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""examples:
+  exa-search "python async frameworks" -n 5
+  exa-search "latest AI news" --category news --start-date 2024-01-01
+  exa-search "rust web" --include-domain github.com,crates.io
+  exa-search "similar to this" --similar https://example.com
+  exa-search "query" --json | jq '.'
+""",
+    )
+    p.add_argument("query", nargs="?", help="search query (omit when using --similar)")
+    p.add_argument("-n", "--num-results", type=int, default=8)
+    p.add_argument("-t", "--type", choices=["auto", "keyword", "neural"], default="auto")
+    p.add_argument("--text", action="store_true", help="fetch and show full page text")
+    p.add_argument("--category", choices=CATEGORIES, metavar="CATEGORY",
+                   help=f"filter by content type: {', '.join(CATEGORIES)}")
+    p.add_argument("--start-date", metavar="YYYY-MM-DD", help="published on or after this date")
+    p.add_argument("--end-date", metavar="YYYY-MM-DD", help="published on or before this date")
+    p.add_argument("--include-domain", metavar="DOMAINS",
+                   help="only include these domains (comma-separated)")
+    p.add_argument("--exclude-domain", metavar="DOMAINS",
+                   help="exclude these domains (comma-separated)")
+    p.add_argument("--similar", metavar="URL", help="find pages similar to this URL")
+    p.add_argument("--json", action="store_true", help="raw JSON output")
+    args = p.parse_args()
+
+    if not args.query and not args.similar:
+        p.error("provide a query or --similar URL")
+
+    exa = _client()
+    highlights = {"num_sentences": 5, "highlights_per_url": 2}
+    contents = ContentsOptions(
+        text=True if args.text else False,
+        highlights=highlights,
+    )
+
+    kwargs: dict = dict(
+        num_results=args.num_results,
+        type=args.type,
+        contents=contents,
+    )
+    if args.category:
+        kwargs["category"] = args.category
+    if args.start_date:
+        kwargs["start_published_date"] = args.start_date
+    if args.end_date:
+        kwargs["end_published_date"] = args.end_date
+    if args.include_domain:
+        kwargs["include_domains"] = _split_domains(args.include_domain)
+    if args.exclude_domain:
+        kwargs["exclude_domains"] = _split_domains(args.exclude_domain)
+
+    if args.similar:
+        result = exa.find_similar(args.similar, **{k: v for k, v in kwargs.items()
+                                                    if k not in ("type",)})
+    else:
+        result = exa.search(args.query, **kwargs)
+
+    if args.json:
+        _dump_json(result)
+    else:
+        _print_results(result.results, result, full_text=args.text)
+
+
+def crawl() -> None:
+    p = argparse.ArgumentParser(
+        description="Exa URL crawl — extract full page content",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""examples:
+  exa-crawl https://example.com
+  exa-crawl https://arxiv.org/abs/2303.08774 -c 10000
+  exa-crawl https://example.com --json
+""",
+    )
+    p.add_argument("url")
+    p.add_argument("-c", "--max-chars", type=int, default=5000,
+                   help="max characters to return (default: 5000)")
+    p.add_argument("--json", action="store_true", help="raw JSON output")
+    args = p.parse_args()
+
+    exa = _client()
+    result = exa.get_contents([args.url], text={"max_characters": args.max_chars})
+
+    if args.json:
+        _dump_json(result)
+    else:
+        _print_results(result.results, result, full_text=True)
+
+
+def research() -> None:
+    p = argparse.ArgumentParser(
+        description="Exa deep research — AI-powered research task",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""examples:
+  exa-research "explain transformer attention mechanisms"
+  exa-research "quantum computing current state" --model exa-research-pro
+  exa-research "topic" --json
+""",
+    )
+    p.add_argument("topic")
+    p.add_argument("-m", "--model", default="exa-research",
+                   choices=["exa-research", "exa-research-pro"])
+    p.add_argument("--json", action="store_true", help="raw JSON output")
+    args = p.parse_args()
+
+    exa = _client()
+    result = exa.research.create_task(instructions=args.topic, model=args.model)
+
+    if args.json:
+        _dump_json(result)
+    else:
+        task_id = getattr(result, "id", None) or getattr(result, "task_id", str(result))
+        status = getattr(result, "status", "submitted")
+        print(f"Research task created")
+        print(f"  ID:     {task_id}")
+        print(f"  Model:  {args.model}")
+        print(f"  Status: {status}")
+        print(f"\nCheck status: exa-research-status {task_id}")

exa_search_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: exa-search-cli
+Version: 0.1.0
+Summary: AI-agent friendly CLI for Exa — neural web search, URL crawling, and deep research from the terminal.
+Project-URL: Homepage, https://github.com/nolan-vale/exa-cli
+Project-URL: Repository, https://github.com/nolan-vale/exa-cli
+Project-URL: Issues, https://github.com/nolan-vale/exa-cli/issues
+Author: Nolan Vale
+Maintainer: Nolan Vale Tools
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,automation,cli,developer-tools,exa,exa-search,llm-tools,search,search-automation,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: exa-py>=1.0.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+[中文](README.zh-CN.md) · [Русский](README.ru.md) · [Português](README.pt-BR.md) · [Español](README.es.md) · [日本語](README.ja.md) · [한국어](README.ko.md)
+
+<!--
+  COVER IMAGE — generate with this prompt, save as docs/cover.png, then uncomment below.
+
+  Prompt (Midjourney / DALL-E 3 / Stable Diffusion XL):
+  "A sleek dark terminal window filled with glowing cyan and blue search results streaming
+  in real-time, abstract neural network nodes forming a luminous web in the background,
+  minimalist developer aesthetic, pure black background, neon accent colors,
+  wide cinematic banner, 2:1 aspect ratio, no text, no UI chrome"
+
+  <img src="docs/cover.png" alt="exa-cli" width="100%">
+-->
+
+# exa-cli
+
+CLI for [Exa](https://exa.ai) — neural web search, URL crawling, and AI deep research from the terminal.
+
+[![PyPI](https://img.shields.io/pypi/v/exa-cli?color=0ea5e9&label=PyPI)](https://pypi.org/project/exa-cli/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-0ea5e9.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-0ea5e9.svg)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/nolan-vale/exa-cli?style=social)](https://github.com/nolan-vale/exa-cli)
+
+</div>
+
+---
+
+## What it does
+
+`exa-cli` wraps the [Exa API](https://exa.ai) in three terminal commands. Exa is a search API built for AI applications — it searches by meaning, not keywords, which means it finds relevant pages even when the exact words are not present in the content.
+
+`exa-search` searches the web. `exa-crawl` extracts clean readable text from any URL without HTML. `exa-research` submits a deep research task where Exa AI reads the web and synthesizes a structured answer.
+
+Every command outputs clean `--json` for use in scripts, pipelines, and AI agent workflows.
+
+## Who it is for
+
+- Developers who want web search access from shell scripts and automation pipelines
+- AI agent developers who need structured, parseable web search output
+- Researchers collecting, filtering, and crawling web content programmatically
+- Anyone using Claude Code, Codex, Cursor, or Windsurf who wants to give their agent web access
+
+## Features
+
+- Neural (semantic) search — finds pages by meaning, not keyword matching
+- Find pages similar to any URL
+- Filter by content type: `news`, `tweet`, `github`, `research paper`, `pdf`, and more
+- Filter by date range and domain
+- Full page text extraction from any URL (no HTML)
+- AI deep research tasks with synthesized answers
+- Clean `--json` output for every command
+
+## Installation
+
+```bash
+uv tool install exa-cli
+```
+
+> No `uv`? Run `curl -LsSf https://astral.sh/uv/install.sh | sh`, or use `pip install exa-search-cli`.
+
+## Quick start
+
+Get your API key at [exa.ai](https://exa.ai) (free tier available):
+
+```bash
+export EXA_API_KEY=your-key-here
+exa-search "how do transformers work" --category "research paper"
+```
+
+## Usage
+
+```bash
+# Neural search
+exa-search "vision language models 2025" -n 10
+
+# Find similar pages to a URL
+exa-search --similar https://github.com/astral-sh/uv
+
+# Filter by content type and date
+exa-search "AI papers" --category "research paper" --start-date 2025-01-01
+
+# Only specific domains
+exa-search "documentation" --include-domain docs.python.org,docs.rs
+
+# Exclude noisy domains
+exa-search "tutorial" --exclude-domain medium.com,dev.to
+
+# Crawl a page, get clean text
+exa-crawl https://example.com -c 8000
+
+# Deep research task
+exa-research "current state of quantum error correction"
+
+# JSON output for pipelines
+exa-search "topic" --json | jq -r '.results[].url'
+```
+
+**All flags — `exa-search`:**
+
+| Flag | Default | Description |
+|---|---|---|
+| `-n` / `--num-results` | `8` | Number of results |
+| `-t` / `--type` | `auto` | `auto` · `keyword` · `neural` |
+| `--text` | off | Fetch and show full page text |
+| `--category` | — | `news` · `tweet` · `github` · `research paper` · `pdf` · `company` · `personal site` · `linkedin profile` · `financial report` |
+| `--start-date` | — | Published on or after `YYYY-MM-DD` |
+| `--end-date` | — | Published on or before `YYYY-MM-DD` |
+| `--include-domain` | — | Comma-separated domains to include only |
+| `--exclude-domain` | — | Comma-separated domains to exclude |
+| `--similar` | — | Find pages similar to this URL |
+| `--json` | off | Raw JSON output |
+
+**All flags — `exa-crawl`:** `-c` / `--max-chars` (default `5000`), `--json`
+
+**All flags — `exa-research`:** `-m` / `--model` (`exa-research` or `exa-research-pro`), `--json`
+
+## AI agent usage
+
+`exa-cli` is stateless, read-only, and exits cleanly — designed to be called by AI coding assistants.
+
+```bash
+# Search and extract URLs (most common agent pattern)
+exa-search "topic" --json | jq -r '.results[].url'
+
+# Search → crawl first result
+exa-search "topic" --json \
+  | jq -r '.results[0].url' \
+  | xargs exa-crawl -c 6000
+
+# Find similar pages to a reference URL
+exa-search --similar https://example.com --json
+
+# Deep research, get synthesized answer
+exa-research "topic" --json
+```
+
+JSON schema for `exa-search --json`:
+```json
+{
+  "results": [
+    {
+      "title": "...",
+      "url": "...",
+      "published_date": "2025-01-15T00:00:00.000Z",
+      "author": "...",
+      "highlights": ["excerpt..."],
+      "text": "full text if --text was passed"
+    }
+  ]
+}
+```
+
+See [AGENTS.md](AGENTS.md) for full schemas, exit codes, and environment reference.
+
+→ [Full documentation](docs/USAGE.md)
+
+## Project metadata
+
+- **Author:** Nolan Vale
+- **Brand:** Nolan Vale Tools
+- **Focus:** search automation, CLI workflows, AI-agent tooling, developer productivity
+- **License:** MIT
+
+---
+
+Built by [Nolan Vale](https://github.com/nolan-vale)  
+Part of **Nolan Vale Tools** — practical open-source utilities for search, automation, AI agents, and developer workflows.

exa_search_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+exa_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+exa_cli/main.py,sha256=rKsVmBprIm_7IlyzqL2me0aglKpt4H4KzV0xOiY_wzc,7764
+exa_search_cli-0.1.0.dist-info/METADATA,sha256=4QoGWmwoJ8nsJIZr6fh7r7vnsSiV5bH8hYlg9Cva-v8,6925
+exa_search_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+exa_search_cli-0.1.0.dist-info/entry_points.txt,sha256=cWblC0c1HncTveE30siqjM-OEW807vlXRyTHUiSyLt0,119
+exa_search_cli-0.1.0.dist-info/licenses/LICENSE,sha256=iU6yWXwU1TUXTWL1SKS4m2eGnMBQ1EA6n4ZlRpGAm-c,1067
+exa_search_cli-0.1.0.dist-info/RECORD,,

exa_search_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

exa_search_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+exa-crawl = exa_cli.main:crawl
+exa-research = exa_cli.main:research
+exa-search = exa_cli.main:search

exa_search_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nolan Vale
+
+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.