Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

feat: add Exa CLI harness for AI-powered web search and answers

Teo Gonzalez Collazob1c9dd4f0d12
diff --git a/.gitignore b/.gitignore
index 3119a2176..6f46ad437 100644
--- a/.gitignore
+++ b/.gitignore
@@ -207,3 +207,4 @@ assets/gen_typing_gif.py
!/notebooklm/agent-harness/
!/intelwatch/agent-harness/
!/intelwatch/
+!/exa/
diff --git a/exa/agent-harness/EXA.md b/exa/agent-harness/EXA.md
new file mode 100644
index 000000000..d6e44dd1c
--- /dev/null
+++ b/exa/agent-harness/EXA.md
@@ -0,0 +1,107 @@
+# EXA — Architecture & Design
+
+## Overview
+
+`cli-anything-exa` is a CLI harness for the [Exa API](https://exa.ai), an AI-native search
+engine built on neural embeddings rather than keyword matching. This harness makes all
+core Exa capabilities available to any AI coding agent (Claude Code, Codex, OpenCode, etc.)
+via a structured, stateful command-line interface.
+
+## Backend
+
+Exa exposes a REST API wrapped by the official `exa-py` Python SDK.
+Authentication uses `EXA_API_KEY` from the environment — no server process is required.
+
+## Command Hierarchy
+
+```
+cli-anything-exa [--json]
+├── search <query> Neural/keyword/deep web search
+├── similar <url> Find pages related to a URL
+├── contents <url> [url …] Fetch full-text or highlighted page content
+├── answer <query> LLM-synthesised answer with citations
+├── server status Verify API key and connectivity
+└── session
+ ├── status Session summary
+ └── history Per-query history (most recent first)
+```
+
+## State Model
+
+Session state (search history) is held in memory in `core/session.py`. It is scoped to
+the process lifetime and is intended for REPL use — agents in non-interactive mode
+receive stateless JSON responses on each invocation.
+
+## Output Strategy
+
+All commands emit human-readable output by default and structured JSON when `--json` is
+passed at the root level. JSON output is the recommended mode for agent pipelines.
+
+JSON result shape for search/similar/contents:
+```json
+{
+ "results": [
+ {
+ "title": "...",
+ "url": "...",
+ "published_date": "...",
+ "author": "...",
+ "highlights": ["..."], // when --content highlights
+ "text": "...", // when --content text
+ "summary": "..." // when --content summary
+ }
+ ],
+ "cost_dollars": {"total": 0.005}
+}
+```
+
+JSON result shape for answer:
+```json
+{
+ "answer": "...",
+ "citations": [{"title": "...", "url": "..."}],
+ "cost_dollars": {"total": 0.003}
+}
+```
+
+## Design Decisions
+
+**`highlights` as default content mode** — Exa highlights are 10× more token-efficient
+than full text and are sufficient for most agent retrieval tasks. Full text is available
+via `--content text` when needed.
+
+**No streaming in v1** — The `answer` endpoint supports SSE streaming but CLI streaming
+complicates JSON parsing for agents. Deferred to a future iteration.
+
+**Research commands deferred** — Exa's async deep researcher (`/research/v1`) has a
+start→poll→get lifecycle that warrants a separate v2 PR with proper state persistence.
+
+**Category slugs use hyphens** — CLI uses `research-paper`, `personal-site`,
+`financial-report` (hyphenated) for shell-friendliness; the backend maps these to the
+API's space-separated values.
+
+## File Layout
+
+```
+exa/agent-harness/
+├── setup.py
+├── EXA.md (this file)
+└── cli_anything/exa/
+ ├── __init__.py
+ ├── __main__.py
+ ├── exa_cli.py Entry point, Click command tree, REPL
+ ├── README.md Setup and usage guide
+ ├── core/
+ │ ├── search.py web_search(), find_similar(), get_contents()
+ │ ├── answer.py get_answer()
+ │ └── session.py In-session history and status
+ ├── utils/
+ │ ├── exa_backend.py SDK client init, contents/category helpers
+ │ └── repl_skin.py Shared REPL terminal UI
+ ├── skills/
+ │ └── SKILL.md Agent-discoverable skill definition
+ └── tests/
+ ├── TEST.md
+ ├── test_core.py Unit tests (no API calls)
+ └── test_full_e2e.py E2E tests (real API, requires EXA_API_KEY)
+```
diff --git a/exa/agent-harness/cli_anything/exa/README.md b/exa/agent-harness/cli_anything/exa/README.md
new file mode 100644
index 000000000..41763cbbf
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/README.md
@@ -0,0 +1,86 @@
+# cli-anything-exa
+
+Agent-native CLI harness for [Exa](https://exa.ai) — AI-powered web search, similar-page discovery, full-text content extraction, and LLM-synthesised answers.
+
+## HOW TO RUN
+
+### 1. Prerequisites
+
+- Python 3.10+
+- An Exa API key — get one free at [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
+
+### 2. Install
+
+```bash
+pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=exa/agent-harness
+```
+
+Or from source (development):
+
+```bash
+cd exa/agent-harness
+pip install -e .
+```
+
+### 3. Configure
+
+```bash
+export EXA_API_KEY="your-api-key-here"
+```
+
+### 4. Verify
+
+```bash
+cli-anything-exa server status
+```
+
+Expected output:
+```
+[OK] API key valid — Exa reachable
+```
+
+### 5. Use
+
+**Web search:**
+```bash
+cli-anything-exa search "large language models 2024" --type deep --content highlights
+```
+
+**Find similar pages:**
+```bash
+cli-anything-exa similar https://arxiv.org/abs/2303.08774 --num-results 5
+```
+
+**Fetch page contents:**
+```bash
+cli-anything-exa contents https://exa.ai --content text
+```
+
+**LLM answer with citations:**
+```bash
+cli-anything-exa answer "What makes Exa different from Google?"
+```
+
+**JSON output (for agents):**
+```bash
+cli-anything-exa --json search "AI safety papers" --num-results 3
+```
+
+**Interactive REPL:**
+```bash
+cli-anything-exa
+```
+
+## Running Tests
+
+**Unit tests** (no API key required):
+```bash
+cd exa/agent-harness
+pip install -e ".[dev]"
+pytest cli_anything/exa/tests/test_core.py -v
+```
+
+**End-to-end tests** (requires `EXA_API_KEY`):
+```bash
+pytest cli_anything/exa/tests/test_full_e2e.py -v
+```
diff --git a/exa/agent-harness/cli_anything/exa/__init__.py b/exa/agent-harness/cli_anything/exa/__init__.py
new file mode 100644
index 000000000..9e01acd84
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/__init__.py
@@ -0,0 +1 @@
+# cli_anything.exa namespace package
diff --git a/exa/agent-harness/cli_anything/exa/__main__.py b/exa/agent-harness/cli_anything/exa/__main__.py
new file mode 100644
index 000000000..e4f8723b9
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/__main__.py
@@ -0,0 +1,3 @@
+"""Allow running as python -m cli_anything.exa"""
+from cli_anything.exa.exa_cli import main
+main()
diff --git a/exa/agent-harness/cli_anything/exa/core/__init__.py b/exa/agent-harness/cli_anything/exa/core/__init__.py
new file mode 100644
index 000000000..062dc5a63
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/core/__init__.py
@@ -0,0 +1 @@
+# cli_anything.exa.core
diff --git a/exa/agent-harness/cli_anything/exa/core/answer.py b/exa/agent-harness/cli_anything/exa/core/answer.py
new file mode 100644
index 000000000..0801c5867
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/core/answer.py
@@ -0,0 +1,48 @@
+"""
+core/answer.py — LLM-synthesised answers with citations via Exa.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli_anything.exa.utils.exa_backend import get_client
+
+
+def get_answer(query: str) -> dict[str, Any]:
+ """Ask Exa a question and receive an LLM-synthesised answer with citations.
+
+ Args:
+ query: Natural-language question.
+
+ Returns:
+ Dict with keys: answer (str), citations (list[dict]).
+ """
+ client = get_client()
+ response = client.answer(query, text=False)
+ return _answer_to_dict(response)
+
+
+def _answer_to_dict(response: Any) -> dict[str, Any]:
+ """Convert an exa-py AnswerResponse to a plain dict."""
+ out: dict[str, Any] = {}
+
+ answer_text = getattr(response, "answer", None)
+ if answer_text is not None:
+ out["answer"] = answer_text
+
+ citations = []
+ for r in getattr(response, "results", []) or []:
+ cite: dict[str, Any] = {}
+ for attr in ("title", "url", "published_date", "author"):
+ val = getattr(r, attr, None)
+ if val is not None:
+ cite[attr] = val
+ citations.append(cite)
+ out["citations"] = citations
+
+ cost = getattr(response, "cost_dollars", None)
+ if cost is not None:
+ out["cost_dollars"] = cost
+
+ return out
diff --git a/exa/agent-harness/cli_anything/exa/core/search.py b/exa/agent-harness/cli_anything/exa/core/search.py
new file mode 100644
index 000000000..7390bc072
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/core/search.py
@@ -0,0 +1,135 @@
+"""
+core/search.py — Web search, find-similar, and get-contents operations.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli_anything.exa.utils.exa_backend import (
+ build_contents_param,
+ get_client,
+ CATEGORY_SLUG_MAP,
+)
+
+
+def web_search(
+ query: str,
+ *,
+ num_results: int = 10,
+ search_type: str = "auto",
+ category: str | None = None,
+ include_domains: tuple[str, ...] = (),
+ exclude_domains: tuple[str, ...] = (),
+ start_date: str | None = None,
+ end_date: str | None = None,
+ location: str | None = None,
+ content_mode: str = "highlights",
+ freshness: str = "smart",
+) -> dict[str, Any]:
+ """Execute a web search via the Exa API.
+
+ Returns the raw SearchResponse as a dict.
+ """
+ client = get_client()
+
+ api_category = CATEGORY_SLUG_MAP.get(category) if category else None
+ contents = build_contents_param(content_mode, freshness)
+
+ kwargs: dict[str, Any] = {
+ "num_results": num_results,
+ "type": search_type,
+ }
+ if api_category:
+ kwargs["category"] = api_category
+ if include_domains:
+ kwargs["include_domains"] = list(include_domains)
+ if exclude_domains:
+ kwargs["exclude_domains"] = list(exclude_domains)
+ if start_date:
+ kwargs["start_published_date"] = start_date
+ if end_date:
+ kwargs["end_published_date"] = end_date
+ if location:
+ kwargs["user_location"] = location
+ if contents:
+ kwargs["contents"] = contents
+
+ response = client.search(query, **kwargs)
+ return _response_to_dict(response)
+
+
+def find_similar(
+ url: str,
+ *,
+ num_results: int = 10,
+ content_mode: str = "highlights",
+) -> dict[str, Any]:
+ """Find pages similar to the given URL."""
+ client = get_client()
+ contents = build_contents_param(content_mode, "smart")
+
+ kwargs: dict[str, Any] = {"num_results": num_results}
+ if contents:
+ kwargs["contents"] = contents
+
+ response = client.find_similar(url, **kwargs)
+ return _response_to_dict(response)
+
+
+def get_contents(
+ urls: list[str],
+ *,
+ content_mode: str = "text",
+ freshness: str = "smart",
+) -> dict[str, Any]:
+ """Fetch full page contents for one or more URLs."""
+ client = get_client()
+
+ kwargs: dict[str, Any] = {}
+ if content_mode == "text":
+ kwargs["text"] = {"max_characters": 10_000}
+ elif content_mode == "highlights":
+ kwargs["highlights"] = {"max_characters": 4_000}
+ elif content_mode == "summary":
+ kwargs["summary"] = True
+
+ if freshness == "always":
+ kwargs["max_age_hours"] = 0
+ elif freshness == "never":
+ kwargs["max_age_hours"] = -1
+
+ response = client.get_contents(urls, **kwargs)
+ return _response_to_dict(response)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _response_to_dict(response: Any) -> dict[str, Any]:
+ """Convert an exa-py response object to a plain dict."""
+ if hasattr(response, "__dict__"):
+ raw = response.__dict__
+ else:
+ return {"results": []}
+
+ results = []
+ for r in raw.get("results", []):
+ item: dict[str, Any] = {}
+ for attr in (
+ "title", "url", "id", "published_date", "author",
+ "text", "highlights", "highlight_scores", "summary",
+ ):
+ val = getattr(r, attr, None)
+ if val is not None:
+ item[attr] = val
+ results.append(item)
+
+ out: dict[str, Any] = {"results": results}
+
+ cost = getattr(response, "cost_dollars", None)
+ if cost is not None:
+ out["cost_dollars"] = cost
+
+ return out
diff --git a/exa/agent-harness/cli_anything/exa/core/session.py b/exa/agent-harness/cli_anything/exa/core/session.py
new file mode 100644
index 000000000..a53f8d672
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/core/session.py
@@ -0,0 +1,55 @@
+"""
+core/session.py — In-session state for the interactive REPL.
+
+Tracks search history and current context so the REPL banner and
+`session history` command have something to display.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class _SearchEntry:
+ query: str
+ command: str # "search" | "similar" | "contents" | "answer"
+ result_count: int
+ timestamp: str = field(default_factory=lambda: datetime.now().strftime("%H:%M:%S"))
+
+
+_history: list[_SearchEntry] = []
+
+
+def record(query: str, command: str, result_count: int) -> None:
+ """Add an entry to the in-session history."""
+ _history.append(_SearchEntry(query=query, command=command, result_count=result_count))
+
+
+def get_history() -> list[dict[str, Any]]:
+ """Return history as a list of plain dicts (most recent first)."""
+ return [
+ {
+ "time": e.timestamp,
+ "command": e.command,
+ "query": e.query,
+ "results": e.result_count,
+ }
+ for e in reversed(_history)
+ ]
+
+
+def get_status() -> dict[str, Any]:
+ """Return a summary of the current session."""
+ return {
+ "total_queries": len(_history),
+ "commands_used": sorted({e.command for e in _history}) or [],
+ "last_query": _history[-1].query if _history else None,
+ }
+
+
+def clear() -> None:
+ """Clear all history (used in tests)."""
+ _history.clear()
diff --git a/exa/agent-harness/cli_anything/exa/exa_cli.py b/exa/agent-harness/cli_anything/exa/exa_cli.py
new file mode 100644
index 000000000..4256997cf
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/exa_cli.py
@@ -0,0 +1,413 @@
+"""
+exa_cli.py — CLI harness for Exa.
+
+Provides a stateful, agent-native command-line interface for the Exa API:
+ - web search (neural, keyword, or deep)
+ - find-similar pages
+ - fetch full page contents
+ - LLM-synthesised answers with citations
+
+Usage (non-interactive):
+ cli-anything-exa search "AI safety papers 2024" --type deep --content highlights
+ cli-anything-exa similar https://example.com --num-results 5
+ cli-anything-exa contents https://example.com --content text
+ cli-anything-exa answer "What is Exa's neural search?"
+ cli-anything-exa --json search "latest LLM benchmarks" --num-results 3
+ cli-anything-exa server status
+
+Usage (interactive REPL):
+ cli-anything-exa
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import click
+
+from cli_anything.exa.core import answer as answer_core
+from cli_anything.exa.core import search as search_core
+from cli_anything.exa.core import session as session_core
+from cli_anything.exa.utils.exa_backend import check_connectivity
+
+# ---------------------------------------------------------------------------
+# Global state
+# ---------------------------------------------------------------------------
+
+_json_output: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _out(data: Any) -> None:
+ """Emit output in JSON or human-readable form."""
+ if _json_output:
+ click.echo(json.dumps(data, indent=2, default=str))
+ else:
+ _pretty(data)
+
+
+def _pretty(data: Any) -> None:
+ """Render a result dict in a human-readable format."""
+ if isinstance(data, dict):
+ if "results" in data:
+ _print_results(data)
+ elif "answer" in data:
+ _print_answer(data)
+ elif "ok" in data:
+ status = "OK" if data["ok"] else "ERROR"
+ click.echo(f"[{status}] {data.get('message', '')}")
+ elif "total_queries" in data:
+ click.echo(f"Queries this session : {data['total_queries']}")
+ click.echo(f"Commands used : {', '.join(data['commands_used']) or 'none'}")
+ if data["last_query"]:
+ click.echo(f"Last query : {data['last_query']}")
+ else:
+ # Generic dict fallback
+ for k, v in data.items():
+ click.echo(f"{k}: {v}")
+ elif isinstance(data, list):
+ for item in data:
+ _pretty(item)
+ else:
+ click.echo(str(data))
+
+
+def _print_results(data: dict[str, Any]) -> None:
+ results = data.get("results", [])
+ if not results:
+ click.echo("No results returned.")
+ return
+ click.echo(f"{'─' * 72}")
+ for i, r in enumerate(results, 1):
+ title = r.get("title") or "(no title)"
+ url = r.get("url", "")
+ date = r.get("published_date", "")
+ author = r.get("author", "")
+
+ click.echo(f"{i:>2}. {title}")
+ click.echo(f" {url}")
+ meta_parts = []
+ if date:
+ meta_parts.append(date[:10])
+ if author:
+ meta_parts.append(f"by {author}")
+ if meta_parts:
+ click.echo(f" {' · '.join(meta_parts)}")
+
+ if r.get("highlights"):
+ for h in r["highlights"]:
+ click.echo(f" › {h.strip()}")
+ elif r.get("summary"):
+ click.echo(f" {r['summary'].strip()}")
+ elif r.get("text"):
+ snippet = r["text"][:300].replace("\n", " ").strip()
+ click.echo(f" {snippet}…")
+ click.echo()
+
+ cost = data.get("cost_dollars")
+ if cost:
+ total = cost.get("total", "") if isinstance(cost, dict) else cost
+ click.echo(f"Cost: ${total}")
+ click.echo(f"{'─' * 72}")
+
+
+def _print_answer(data: dict[str, Any]) -> None:
+ click.echo(f"\n{data.get('answer', '')}\n")
+ citations = data.get("citations", [])
+ if citations:
+ click.echo("Sources:")
+ for i, c in enumerate(citations, 1):
+ click.echo(f" {i}. {c.get('title') or c.get('url', '')}")
+ click.echo(f" {c.get('url', '')}")
+ cost = data.get("cost_dollars")
+ if cost:
+ total = cost.get("total", "") if isinstance(cost, dict) else cost
+ click.echo(f"\nCost: ${total}")
+
+
+def _err(msg: str) -> None:
+ if _json_output:
+ click.echo(json.dumps({"error": msg}))
+ else:
+ click.echo(f"Error: {msg}", err=True)
+
+
+def _handle_errors(fn):
+ """Decorator: catch RuntimeError / Exception and emit consistent errors."""
+ import functools
+
+ @functools.wraps(fn)
+ def wrapper(*args, **kwargs):
+ try:
+ return fn(*args, **kwargs)
+ except RuntimeError as exc:
+ _err(str(exc))
+ sys.exit(1)
+ except Exception as exc: # noqa: BLE001
+ _err(f"Unexpected error: {exc}")
+ sys.exit(1)
+
+ return wrapper
+
+
+# ---------------------------------------------------------------------------
+# CLI root
+# ---------------------------------------------------------------------------
+
[email protected](invoke_without_command=True)
[email protected]("--json", "use_json", is_flag=True, help="Emit machine-readable JSON output.")
+def cli(ctx: click.Context, use_json: bool) -> None:
+ """CLI harness for Exa — AI-powered web search and answer engine.
+
+ Run without a subcommand to enter the interactive REPL.
+ Set EXA_API_KEY in your environment before use.
+ """
+ global _json_output
+ _json_output = use_json
+ ctx.ensure_object(dict)
+
+ if ctx.invoked_subcommand is None:
+ ctx.invoke(repl)
+
+
+# ---------------------------------------------------------------------------
+# search
+# ---------------------------------------------------------------------------
+
+_SEARCH_TYPES = click.Choice(
+ ["auto", "fast", "instant", "deep", "deep-reasoning"],
+ case_sensitive=False,
+)
+_CONTENT_CHOICES = click.Choice(
+ ["highlights", "text", "summary", "none"],
+ case_sensitive=False,
+)
+_FRESHNESS_CHOICES = click.Choice(
+ ["smart", "always", "never"],
+ case_sensitive=False,
+)
+_CATEGORY_CHOICES = click.Choice(
+ ["company", "people", "research-paper", "news", "personal-site", "financial-report"],
+ case_sensitive=False,
+)
+
+
[email protected]("--type", "search_type", default="auto", show_default=True,
+ type=_SEARCH_TYPES, help="Search mode.")
[email protected]("--num-results", "-n", default=10, show_default=True,
+ type=click.IntRange(1, 100), help="Number of results (1–100).")
[email protected]("--category", type=_CATEGORY_CHOICES, default=None,
+ help="Restrict to a specialised index.")
[email protected]("--content", "content_mode", default="highlights", show_default=True,
+ type=_CONTENT_CHOICES, help="Content to include with each result.")
[email protected]("--freshness", default="smart", show_default=True,
+ type=_FRESHNESS_CHOICES,
+ help="Livecrawl policy: smart=cache+fallback, always=force-fresh, never=cache-only.")
[email protected]("--include-domains", multiple=True, metavar="DOMAIN",
+ help="Restrict results to these domains (repeatable).")
[email protected]("--exclude-domains", multiple=True, metavar="DOMAIN",
+ help="Exclude results from these domains (repeatable).")
[email protected]("--from", "start_date", default=None, metavar="DATE",
+ help="Only results published after this date (ISO 8601, e.g. 2024-01-01).")
[email protected]("--to", "end_date", default=None, metavar="DATE",
+ help="Only results published before this date (ISO 8601).")
[email protected]("--location", default=None, metavar="CC",
+ help="Geo-bias results to this two-letter country code (e.g. US).")
+@_handle_errors
+def search_cmd(
+ query: str,
+ search_type: str,
+ num_results: int,
+ category: str | None,
+ content_mode: str,
+ freshness: str,
+ include_domains: tuple[str, ...],
+ exclude_domains: tuple[str, ...],
+ start_date: str | None,
+ end_date: str | None,
+ location: str | None,
+) -> None:
+ """Search the web using Exa's neural or deep search."""
+ result = search_core.web_search(
+ query,
+ num_results=num_results,
+ search_type=search_type,
+ category=category,
+ include_domains=include_domains,
+ exclude_domains=exclude_domains,
+ start_date=start_date,
+ end_date=end_date,
+ location=location,
+ content_mode=content_mode,
+ freshness=freshness,
+ )
+ session_core.record(query, "search", len(result.get("results", [])))
+ _out(result)
+
+
+# ---------------------------------------------------------------------------
+# similar
+# ---------------------------------------------------------------------------
+
[email protected]("--num-results", "-n", default=10, show_default=True,
+ type=click.IntRange(1, 100), help="Number of results.")
[email protected]("--content", "content_mode", default="highlights", show_default=True,
+ type=_CONTENT_CHOICES, help="Content to include with each result.")
+@_handle_errors
+def similar_cmd(url: str, num_results: int, content_mode: str) -> None:
+ """Find pages similar to a given URL."""
+ result = search_core.find_similar(url, num_results=num_results, content_mode=content_mode)
+ session_core.record(url, "similar", len(result.get("results", [])))
+ _out(result)
+
+
+# ---------------------------------------------------------------------------
+# contents
+# ---------------------------------------------------------------------------
+
[email protected]("contents")
[email protected]("urls", nargs=-1, required=True)
[email protected]("--content", "content_mode", default="text", show_default=True,
+ type=click.Choice(["text", "highlights", "summary"], case_sensitive=False),
+ help="Content to retrieve.")
[email protected]("--freshness", default="smart", show_default=True,
+ type=_FRESHNESS_CHOICES,
+ help="Livecrawl policy.")
+@_handle_errors
+def contents_cmd(urls: tuple[str, ...], content_mode: str, freshness: str) -> None:
+ """Fetch full page contents for one or more URLs."""
+ result = search_core.get_contents(list(urls), content_mode=content_mode, freshness=freshness)
+ session_core.record(str(urls[0]), "contents", len(result.get("results", [])))
+ _out(result)
+
+
+# ---------------------------------------------------------------------------
+# answer
+# ---------------------------------------------------------------------------
+
+@_handle_errors
+def answer_cmd(query: str) -> None:
+ """Get an LLM-synthesised answer with cited sources."""
+ result = answer_core.get_answer(query)
+ session_core.record(query, "answer", len(result.get("citations", [])))
+ _out(result)
+
+
+# ---------------------------------------------------------------------------
+# server
+# ---------------------------------------------------------------------------
+
+def server_group() -> None:
+ """Server and API connectivity commands."""
+
+
+@server_group.command("status")
+@_handle_errors
+def server_status() -> None:
+ """Check that the Exa API is reachable with your API key."""
+ result = check_connectivity()
+ _out(result)
+
+
+# ---------------------------------------------------------------------------
+# session
+# ---------------------------------------------------------------------------
+
+def session_group() -> None:
+ """Inspect the current REPL session state."""
+
+
+@session_group.command("status")
+def session_status() -> None:
+ """Show a summary of activity in this session."""
+ _out(session_core.get_status())
+
+
+@session_group.command("history")
+def session_history() -> None:
+ """List queries made in this session (most recent first)."""
+ history = session_core.get_history()
+ if _json_output:
+ click.echo(json.dumps(history, indent=2))
+ else:
+ if not history:
+ click.echo("No queries yet.")
+ return
+ click.echo(f"{'Time':<10} {'Cmd':<10} {'Results':<9} Query")
+ click.echo("─" * 72)
+ for entry in history:
+ click.echo(
+ f"{entry['time']:<10} {entry['command']:<10} "
+ f"{entry['results']:<9} {entry['query']}"
+ )
+
+
+# ---------------------------------------------------------------------------
+# REPL
+# ---------------------------------------------------------------------------
+
+def repl() -> None:
+ """Start the interactive REPL (default when no subcommand is given)."""
+ try:
+ from cli_anything.exa.utils.repl_skin import ReplSkin
+ except ImportError:
+ click.echo("prompt-toolkit is required for REPL mode: pip install prompt-toolkit")
+ sys.exit(1)
+
+ skin = ReplSkin(
+ software_name="Exa",
+ version="1.0.0",
+ accent_color="cyan",
+ skill_package="cli_anything.exa",
+ )
+ skin.print_banner()
+
+ while True:
+ try:
+ user_input = skin.prompt()
+ except (KeyboardInterrupt, EOFError):
+ skin.print_goodbye()
+ break
+
+ line = user_input.strip()
+ if not line:
+ continue
+ if line.lower() in ("exit", "quit", "q"):
+ skin.print_goodbye()
+ break
+
+ # Dispatch the line as a CLI invocation
+ try:
+ args = line.split()
+ cli.main(args=args, standalone_mode=False)
+ except SystemExit:
+ pass
+ except Exception as exc: # noqa: BLE001
+ _err(str(exc))
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+ cli()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/exa/agent-harness/cli_anything/exa/skills/SKILL.md b/exa/agent-harness/cli_anything/exa/skills/SKILL.md
new file mode 100644
index 000000000..e57f81b89
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/skills/SKILL.md
@@ -0,0 +1,128 @@
+# Exa CLI Skill
+
+## Identity
+- **Name**: cli-anything-exa
+- **Version**: 1.0.0
+- **Category**: search
+- **Entry Point**: `cli-anything-exa`
+
+## What This CLI Does
+Provides an agent-native command-line interface to the Exa API — a neural search engine
+optimised for AI agent workflows. Supports web search across multiple modes (fast, deep,
+deep-reasoning), finding similar pages, fetching full-text or highlighted page contents,
+and getting LLM-synthesised answers with cited sources.
+
+## Prerequisites
+- Python >= 3.10
+- `pip install cli-anything-exa`
+- `export EXA_API_KEY="your-api-key"` (get one at https://dashboard.exa.ai/api-keys)
+
+## Installation
+```bash
+pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=exa/agent-harness
+```
+
+## Command Reference
+
+### search — Web search
+```bash
+cli-anything-exa search "<query>" [OPTIONS]
+
+Options:
+ --type auto|fast|instant|deep|deep-reasoning (default: auto)
+ --num-results / -n 1–100 (default: 10)
+ --category company|people|research-paper|news|personal-site|financial-report
+ --content highlights|text|summary|none (default: highlights)
+ --freshness smart|always|never (default: smart)
+ --include-domains DOMAIN (repeatable)
+ --exclude-domains DOMAIN (repeatable)
+ --from DATE ISO 8601 start published date
+ --to DATE ISO 8601 end published date
+ --location CC Two-letter country code for geo-bias
+```
+
+### similar — Find similar pages
+```bash
+cli-anything-exa similar "<url>" [--num-results N] [--content highlights|text|summary|none]
+```
+
+### contents — Fetch page contents
+```bash
+cli-anything-exa contents <url> [url ...] [--content text|highlights|summary] [--freshness smart|always|never]
+```
+
+### answer — LLM-synthesised answer with citations
+```bash
+cli-anything-exa answer "<question>"
+```
+
+### server status — Verify API key and connectivity
+```bash
+cli-anything-exa server status
+```
+
+### session — Inspect current REPL session
+```bash
+cli-anything-exa session status
+cli-anything-exa session history
+```
+
+## JSON Output
+All commands support `--json` at the root level for machine-readable output:
+```bash
+cli-anything-exa --json search "latest LLM papers" --num-results 5
+```
+
+## Common Agent Patterns
+
+### Fast keyword lookup
+```bash
+cli-anything-exa --json search "site:arxiv.org transformer architectures" --type fast --content highlights
+```
+
+### Deep research on a topic
+```bash
+cli-anything-exa --json search "EU AI Act compliance requirements 2024" --type deep --content text
+```
+
+### Academic paper discovery
+```bash
+cli-anything-exa --json search "retrieval augmented generation" --category research-paper --num-results 20
+```
+
+### Company intelligence
+```bash
+cli-anything-exa --json search "Anthropic funding history" --category company
+```
+
+### News monitoring
+```bash
+cli-anything-exa --json search "AI regulation news" --category news --from 2024-01-01
+```
+
+### Find related resources
+```bash
+cli-anything-exa --json similar https://arxiv.org/abs/2303.08774 --num-results 10
+```
+
+### Fetch full content for summarisation
+```bash
+cli-anything-exa --json contents https://example.com/article --content text
+```
+
+### Quick factual answer
+```bash
+cli-anything-exa --json answer "What is the context window of Claude 3.5 Sonnet?"
+```
+
+## Interactive REPL
+```bash
+cli-anything-exa # No subcommand → enters REPL
+```
+Type commands without the `cli-anything-exa` prefix. Type `exit` or `quit` to leave.
+
+## Notes
+- `highlights` content mode is 10× more token-efficient than `text` — prefer it for agent pipelines
+- `--type deep` triggers multi-step reasoning; slower but synthesises across many sources
+- `--category company` and `--category people` do not support date or domain-exclude filters
+- Cost per query is included in JSON output under `cost_dollars`
diff --git a/exa/agent-harness/cli_anything/exa/tests/TEST.md b/exa/agent-harness/cli_anything/exa/tests/TEST.md
new file mode 100644
index 000000000..84152da3f
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/tests/TEST.md
@@ -0,0 +1,118 @@
+# TEST.md — Exa CLI Harness Test Plan & Results
+
+## Test Strategy
+
+| Layer | File | API calls | Purpose |
+|-------|------|-----------|---------|
+| Unit | test_core.py | None (mocked) | Logic, flag parsing, output formatting |
+| E2E | test_full_e2e.py | Real Exa API | End-to-end correctness, field presence |
+
+## Unit Test Plan (`test_core.py`)
+
+### TestBuildContentsParam
+- [x] `none` mode returns `None`
+- [x] `highlights` mode sets `max_characters: 4000`
+- [x] `text` mode sets `max_characters: 10000`
+- [x] `summary` mode sets `summary: True`
+- [x] `freshness=always` sets `max_age_hours: 0`
+- [x] `freshness=never` sets `max_age_hours: -1`
+- [x] `freshness=smart` omits `max_age_hours`
+
+### TestCategorySlugMap
+- [x] Hyphenated slugs map correctly to API space-separated values
+- [x] Simple slugs pass through unchanged
+
+### TestSession
+- [x] Empty session returns zero totals
+- [x] `record()` adds entries visible in `get_history()`
+- [x] History returned most-recent-first
+- [x] Status reflects all distinct commands used
+
+### TestCLIHelp
+- [x] Root `--help` exits 0 and mentions "Exa"
+- [x] `search --help` shows all flags
+- [x] All subcommand `--help` exits exit code 0
+
+### TestSearchCLI
+- [x] Basic search calls `exa.search()` with correct query
+- [x] `--json` flag produces parseable JSON with `results` key
+- [x] `--type deep` is forwarded to SDK
+- [x] `--num-results 5` is forwarded to SDK
+- [x] `--include-domains` is forwarded to SDK
+- [x] Invalid `--type` value is rejected (exit != 0)
+
+### TestSimilarCLI
+- [x] Basic call invokes `exa.find_similar()`
+- [x] `--json` produces parseable JSON
+
+### TestContentsCLI
+- [x] Single URL invokes `exa.get_contents()`
+- [x] Multiple URLs forwarded as list
+
+### TestAnswerCLI
+- [x] Answer text appears in output
+- [x] `--json` produces `answer` and `citations` keys
+
+### TestServerCLI
+- [x] `[OK]` shown on success
+- [x] `[ERROR]` shown on failure
+- [x] `--json` produces `{"ok": true}`
+
+### TestSessionCLI
+- [x] `session status` shows query count after search
+- [x] `session history` shows "No queries" when empty
+- [x] `session history --json` returns a list
+
+### TestErrorHandling
+- [x] `RuntimeError` from backend produces `{"error": "..."}` in JSON mode
+- [x] Missing required argument exits non-zero
+
+## E2E Test Plan (`test_full_e2e.py`)
+
+Skipped automatically when `EXA_API_KEY` is not set.
+
+### TestServerStatusE2E
+- [ ] `server status` exits 0 and shows `[OK]`
+- [ ] `--json server status` returns `{"ok": true}`
+
+### TestSearchE2E
+- [ ] Basic search returns at least 1 result
+- [ ] Result objects contain `url` and `title`
+- [ ] `--content highlights` produces `highlights` array
+- [ ] `--content text` produces non-empty `text` string
+- [ ] `--category news` returns results
+- [ ] `--include-domains arxiv.org` — all result URLs contain `arxiv.org`
+- [ ] `--num-results 5` returns ≤ 5 results
+- [ ] Human-readable output contains `http`
+- [ ] Session is updated after search
+
+### TestSimilarE2E
+- [ ] `similar <url>` returns results
+- [ ] Results contain `url` and `title`
+
+### TestContentsE2E
+- [ ] `contents <url>` returns results
+- [ ] `--content text` result has non-empty `text`
+- [ ] Multiple URLs: at least 1 result returned
+
+### TestAnswerE2E
+- [ ] `answer <question>` returns `answer` string (> 10 chars)
+- [ ] `answer` result has `citations` list
+- [ ] Human-readable output is non-empty
+
+### TestEntryPoint
+- [ ] `cli-anything-exa --help` exits 0 via subprocess
+- [ ] `cli-anything-exa --json search ...` returns valid JSON via subprocess
+
+## Running Tests
+
+```bash
+# Unit tests only
+pytest cli_anything/exa/tests/test_core.py -v
+
+# E2E tests (requires EXA_API_KEY)
+EXA_API_KEY=your-key pytest cli_anything/exa/tests/test_full_e2e.py -v
+
+# All tests
+pytest cli_anything/exa/tests/ -v
+```
diff --git a/exa/agent-harness/cli_anything/exa/tests/__init__.py b/exa/agent-harness/cli_anything/exa/tests/__init__.py
new file mode 100644
index 000000000..4e91dc8ed
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/tests/__init__.py
@@ -0,0 +1 @@
+# cli_anything.exa.tests
diff --git a/exa/agent-harness/cli_anything/exa/tests/test_core.py b/exa/agent-harness/cli_anything/exa/tests/test_core.py
new file mode 100644
index 000000000..32f4e2c9c
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/tests/test_core.py
@@ -0,0 +1,396 @@
+"""
+test_core.py — Unit tests for the Exa CLI harness.
+
+All tests use mocks; no real API calls are made.
+Run with: pytest tests/test_core.py -v
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+from click.testing import CliRunner
+
+from cli_anything.exa.exa_cli import cli
+from cli_anything.exa.core import session as session_core
+from cli_anything.exa.utils.exa_backend import build_contents_param, CATEGORY_SLUG_MAP
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
[email protected](autouse=True)
+def clear_session():
+ """Reset session history before each test."""
+ session_core.clear()
+ yield
+ session_core.clear()
+
+
+def runner():
+ return CliRunner()
+
+
+def _mock_result(n: int = 2):
+ """Build a fake exa-py search result object using SimpleNamespace."""
+ results = [
+ SimpleNamespace(
+ title=f"Result {i + 1}",
+ url=f"https://example.com/{i + 1}",
+ id=f"https://example.com/{i + 1}",
+ published_date="2024-01-01",
+ author=None,
+ text=f"Body text for result {i + 1}.",
+ highlights=[f"Highlight for result {i + 1}."],
+ highlight_scores=[0.9],
+ summary=None,
+ )
+ for i in range(n)
+ ]
+ return SimpleNamespace(results=results, cost_dollars={"total": 0.005})
+
+
+def _mock_answer():
+ citation = SimpleNamespace(
+ title="Some Paper",
+ url="https://example.com/paper",
+ published_date="2024-01-01",
+ author="Jane Doe",
+ )
+ return SimpleNamespace(
+ answer="Exa uses neural embeddings for search.",
+ results=[citation],
+ cost_dollars={"total": 0.003},
+ )
+ return response
+
+
+# ---------------------------------------------------------------------------
+# Backend unit tests
+# ---------------------------------------------------------------------------
+
+class TestBuildContentsParam:
+ def test_none_mode_returns_none(self):
+ assert build_contents_param("none") is None
+
+ def test_highlights_mode(self):
+ result = build_contents_param("highlights")
+ assert "highlights" in result
+ assert result["highlights"]["max_characters"] == 4_000
+
+ def test_text_mode(self):
+ result = build_contents_param("text")
+ assert "text" in result
+ assert result["text"]["max_characters"] == 10_000
+
+ def test_summary_mode(self):
+ result = build_contents_param("summary")
+ assert result["summary"] is True
+
+ def test_freshness_always(self):
+ result = build_contents_param("highlights", freshness="always")
+ assert result["max_age_hours"] == 0
+
+ def test_freshness_never(self):
+ result = build_contents_param("highlights", freshness="never")
+ assert result["max_age_hours"] == -1
+
+ def test_freshness_smart_omits_key(self):
+ result = build_contents_param("highlights", freshness="smart")
+ assert "max_age_hours" not in result
+
+
+class TestCategorySlugMap:
+ def test_hyphenated_slugs_map_to_api_values(self):
+ assert CATEGORY_SLUG_MAP["research-paper"] == "research paper"
+ assert CATEGORY_SLUG_MAP["personal-site"] == "personal site"
+ assert CATEGORY_SLUG_MAP["financial-report"] == "financial report"
+
+ def test_simple_slugs_pass_through(self):
+ assert CATEGORY_SLUG_MAP["news"] == "news"
+ assert CATEGORY_SLUG_MAP["company"] == "company"
+
+
+# ---------------------------------------------------------------------------
+# Session unit tests
+# ---------------------------------------------------------------------------
+
+class TestSession:
+ def test_empty_session(self):
+ status = session_core.get_status()
+ assert status["total_queries"] == 0
+ assert status["last_query"] is None
+
+ def test_record_and_history(self):
+ session_core.record("test query", "search", 5)
+ history = session_core.get_history()
+ assert len(history) == 1
+ assert history[0]["query"] == "test query"
+ assert history[0]["results"] == 5
+
+ def test_history_most_recent_first(self):
+ session_core.record("first", "search", 1)
+ session_core.record("second", "answer", 2)
+ history = session_core.get_history()
+ assert history[0]["query"] == "second"
+ assert history[1]["query"] == "first"
+
+ def test_status_after_records(self):
+ session_core.record("q1", "search", 3)
+ session_core.record("q2", "answer", 1)
+ status = session_core.get_status()
+ assert status["total_queries"] == 2
+ assert "search" in status["commands_used"]
+ assert "answer" in status["commands_used"]
+ assert status["last_query"] == "q2"
+
+
+# ---------------------------------------------------------------------------
+# CLI parsing tests
+# ---------------------------------------------------------------------------
+
+class TestCLIHelp:
+ def test_root_help(self, runner):
+ result = runner.invoke(cli, ["--help"])
+ assert result.exit_code == 0
+ assert "Exa" in result.output
+
+ def test_search_help(self, runner):
+ result = runner.invoke(cli, ["search", "--help"])
+ assert result.exit_code == 0
+ assert "--type" in result.output
+ assert "--num-results" in result.output
+ assert "--content" in result.output
+
+ def test_similar_help(self, runner):
+ result = runner.invoke(cli, ["similar", "--help"])
+ assert result.exit_code == 0
+ assert "--num-results" in result.output
+
+ def test_contents_help(self, runner):
+ result = runner.invoke(cli, ["contents", "--help"])
+ assert result.exit_code == 0
+
+ def test_answer_help(self, runner):
+ result = runner.invoke(cli, ["answer", "--help"])
+ assert result.exit_code == 0
+
+ def test_server_status_help(self, runner):
+ result = runner.invoke(cli, ["server", "status", "--help"])
+ assert result.exit_code == 0
+
+ def test_session_help(self, runner):
+ result = runner.invoke(cli, ["session", "--help"])
+ assert result.exit_code == 0
+
+
+class TestSearchCLI:
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_basic_search(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.search.return_value = _mock_result(2)
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(cli, ["search", "AI research"])
+ assert result.exit_code == 0
+ mock_client.search.assert_called_once()
+ call_kwargs = mock_client.search.call_args
+ assert call_kwargs[0][0] == "AI research"
+
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_search_json_output(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.search.return_value = _mock_result(1)
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(cli, ["--json", "search", "test query"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "results" in data
+ assert len(data["results"]) == 1
+
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_search_type_flag(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.search.return_value = _mock_result(1)
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(cli, ["search", "deep query", "--type", "deep"])
+ assert result.exit_code == 0
+ _, kwargs = mock_client.search.call_args
+ assert kwargs.get("type") == "deep"
+
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_search_num_results_flag(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.search.return_value = _mock_result(5)
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(cli, ["search", "test", "--num-results", "5"])
+ assert result.exit_code == 0
+ _, kwargs = mock_client.search.call_args
+ assert kwargs.get("num_results") == 5
+
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_search_include_domains(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.search.return_value = _mock_result(1)
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(
+ cli, ["search", "test", "--include-domains", "arxiv.org", "--include-domains", "nature.com"]
+ )
+ assert result.exit_code == 0
+ _, kwargs = mock_client.search.call_args
+ assert "arxiv.org" in kwargs.get("include_domains", [])
+
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_search_invalid_type_rejected(self, mock_get_client, runner):
+ result = runner.invoke(cli, ["search", "test", "--type", "bogus"])
+ assert result.exit_code != 0
+
+
+class TestSimilarCLI:
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_basic_similar(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.find_similar.return_value = _mock_result(3)
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(cli, ["similar", "https://example.com"])
+ assert result.exit_code == 0
+ mock_client.find_similar.assert_called_once()
+
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_similar_json_output(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.find_similar.return_value = _mock_result(2)
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(cli, ["--json", "similar", "https://example.com"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "results" in data
+
+
+class TestContentsCLI:
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_basic_contents(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.get_contents.return_value = _mock_result(1)
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(cli, ["contents", "https://example.com"])
+ assert result.exit_code == 0
+ mock_client.get_contents.assert_called_once()
+
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_contents_multiple_urls(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.get_contents.return_value = _mock_result(2)
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(
+ cli, ["contents", "https://example.com/a", "https://example.com/b"]
+ )
+ assert result.exit_code == 0
+ args, _ = mock_client.get_contents.call_args
+ assert len(args[0]) == 2
+
+
+class TestAnswerCLI:
+ @patch("cli_anything.exa.core.answer.get_client")
+ def test_basic_answer(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.answer.return_value = _mock_answer()
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(cli, ["answer", "What is Exa?"])
+ assert result.exit_code == 0
+ assert "neural embeddings" in result.output
+
+ @patch("cli_anything.exa.core.answer.get_client")
+ def test_answer_json_output(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.answer.return_value = _mock_answer()
+ mock_get_client.return_value = mock_client
+
+ result = runner.invoke(cli, ["--json", "answer", "What is Exa?"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "answer" in data
+ assert "citations" in data
+
+
+class TestServerCLI:
+ @patch("cli_anything.exa.exa_cli.check_connectivity")
+ def test_server_status_ok(self, mock_check, runner):
+ mock_check.return_value = {"ok": True, "message": "API key valid — Exa reachable"}
+ result = runner.invoke(cli, ["server", "status"])
+ assert result.exit_code == 0
+ assert "OK" in result.output
+
+ @patch("cli_anything.exa.exa_cli.check_connectivity")
+ def test_server_status_error(self, mock_check, runner):
+ mock_check.return_value = {"ok": False, "message": "EXA_API_KEY not set"}
+ result = runner.invoke(cli, ["server", "status"])
+ assert result.exit_code == 0
+ assert "ERROR" in result.output
+
+ @patch("cli_anything.exa.exa_cli.check_connectivity")
+ def test_server_status_json(self, mock_check, runner):
+ mock_check.return_value = {"ok": True, "message": "OK"}
+ result = runner.invoke(cli, ["--json", "server", "status"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert data["ok"] is True
+
+
+class TestSessionCLI:
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_session_status_after_search(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.search.return_value = _mock_result(3)
+ mock_get_client.return_value = mock_client
+
+ runner.invoke(cli, ["search", "test query"])
+ result = runner.invoke(cli, ["session", "status"])
+ assert result.exit_code == 0
+ assert "1" in result.output # total_queries
+
+ def test_session_history_empty(self, runner):
+ result = runner.invoke(cli, ["session", "history"])
+ assert result.exit_code == 0
+ assert "No queries" in result.output
+
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_session_history_json(self, mock_get_client, runner):
+ mock_client = MagicMock()
+ mock_client.search.return_value = _mock_result(2)
+ mock_get_client.return_value = mock_client
+
+ runner.invoke(cli, ["search", "test"])
+ result = runner.invoke(cli, ["--json", "session", "history"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert isinstance(data, list)
+ assert data[0]["query"] == "test"
+
+
+class TestErrorHandling:
+ @patch("cli_anything.exa.core.search.get_client")
+ def test_runtime_error_produces_json_error(self, mock_get_client, runner):
+ mock_get_client.side_effect = RuntimeError("EXA_API_KEY environment variable is not set.")
+ result = runner.invoke(cli, ["--json", "search", "test"])
+ assert result.exit_code == 1
+ data = json.loads(result.output)
+ assert "error" in data
+
+ def test_missing_query_argument(self, runner):
+ result = runner.invoke(cli, ["search"])
+ assert result.exit_code != 0
diff --git a/exa/agent-harness/cli_anything/exa/tests/test_full_e2e.py b/exa/agent-harness/cli_anything/exa/tests/test_full_e2e.py
new file mode 100644
index 000000000..c2191974e
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/tests/test_full_e2e.py
@@ -0,0 +1,266 @@
+"""
+test_full_e2e.py — End-to-end tests against the real Exa API.
+
+Requires: EXA_API_KEY set in the environment.
+Run with: pytest tests/test_full_e2e.py -v
+
+These tests make real API calls and consume credits. They verify that:
+ - The CLI produces parseable JSON output
+ - Results contain expected fields
+ - All subcommands route correctly to the API
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+
+import pytest
+
+from click.testing import CliRunner
+from cli_anything.exa.exa_cli import cli
+from cli_anything.exa.core import session as session_core
+
+
+# ---------------------------------------------------------------------------
+# Skip guard
+# ---------------------------------------------------------------------------
+
+pytestmark = pytest.mark.skipif(
+ not os.environ.get("EXA_API_KEY"),
+ reason="EXA_API_KEY not set — skipping E2E tests",
+)
+
+
[email protected](autouse=True)
+def clear_session():
+ session_core.clear()
+ yield
+ session_core.clear()
+
+
+def runner():
+ return CliRunner()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_cli() -> list[str]:
+ """Return the command prefix to invoke cli-anything-exa."""
+ cmd = "cli-anything-exa"
+ result = subprocess.run(["which", cmd], capture_output=True, text=True)
+ if result.returncode == 0:
+ return [cmd]
+ # Fall back to module invocation
+ return [sys.executable, "-m", "cli_anything.exa"]
+
+
+def _run(*args: str) -> subprocess.CompletedProcess:
+ prefix = _resolve_cli()
+ return subprocess.run(
+ prefix + list(args),
+ capture_output=True,
+ text=True,
+ env={**os.environ},
+ )
+
+
+# ---------------------------------------------------------------------------
+# server status
+# ---------------------------------------------------------------------------
+
+class TestServerStatusE2E:
+ def test_status_ok(self):
+ proc = _run("server", "status")
+ assert proc.returncode == 0
+ assert "OK" in proc.stdout
+
+ def test_status_json(self):
+ proc = _run("--json", "server", "status")
+ assert proc.returncode == 0
+ data = json.loads(proc.stdout)
+ assert data["ok"] is True
+ assert "message" in data
+
+
+# ---------------------------------------------------------------------------
+# search
+# ---------------------------------------------------------------------------
+
+class TestSearchE2E:
+ def test_basic_search_returns_results(self, runner):
+ result = runner.invoke(cli, ["--json", "search", "large language models 2024"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "results" in data
+ assert len(data["results"]) > 0
+
+ def test_search_result_has_required_fields(self, runner):
+ result = runner.invoke(cli, ["--json", "search", "AI safety research", "--num-results", "3"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ r = data["results"][0]
+ assert "url" in r
+ assert "title" in r
+
+ def test_search_highlights_content(self, runner):
+ result = runner.invoke(
+ cli, ["--json", "search", "neural search algorithms", "--content", "highlights"]
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ r = data["results"][0]
+ assert "highlights" in r
+ assert isinstance(r["highlights"], list)
+ assert len(r["highlights"]) > 0
+
+ def test_search_text_content(self, runner):
+ result = runner.invoke(
+ cli, ["--json", "search", "machine learning overview", "--content", "text", "--num-results", "1"]
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ r = data["results"][0]
+ assert "text" in r
+ assert len(r["text"]) > 50
+
+ def test_search_category_news(self, runner):
+ result = runner.invoke(
+ cli, ["--json", "search", "AI regulation", "--category", "news", "--num-results", "3"]
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert len(data["results"]) > 0
+
+ def test_search_domain_filter(self, runner):
+ result = runner.invoke(
+ cli,
+ ["--json", "search", "machine learning", "--include-domains", "arxiv.org", "--num-results", "3"],
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ for r in data["results"]:
+ assert "arxiv.org" in r["url"]
+
+ def test_search_num_results_respected(self, runner):
+ result = runner.invoke(cli, ["--json", "search", "AI research", "--num-results", "5"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert len(data["results"]) <= 5
+
+ def test_search_human_readable_output(self, runner):
+ result = runner.invoke(cli, ["search", "Exa search API"])
+ assert result.exit_code == 0
+ assert "http" in result.output # URL is shown
+
+ def test_search_records_session(self, runner):
+ runner.invoke(cli, ["--json", "search", "test query"])
+ status = session_core.get_status()
+ assert status["total_queries"] == 1
+ assert status["last_query"] == "test query"
+
+
+# ---------------------------------------------------------------------------
+# similar
+# ---------------------------------------------------------------------------
+
+class TestSimilarE2E:
+ def test_basic_similar(self, runner):
+ result = runner.invoke(
+ cli, ["--json", "similar", "https://arxiv.org/abs/2303.08774", "--num-results", "3"]
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "results" in data
+ assert len(data["results"]) > 0
+
+ def test_similar_result_fields(self, runner):
+ result = runner.invoke(
+ cli, ["--json", "similar", "https://openai.com/research/gpt-4", "--num-results", "2"]
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ r = data["results"][0]
+ assert "url" in r
+ assert "title" in r
+
+
+# ---------------------------------------------------------------------------
+# contents
+# ---------------------------------------------------------------------------
+
+class TestContentsE2E:
+ def test_basic_contents(self, runner):
+ result = runner.invoke(
+ cli, ["--json", "contents", "https://exa.ai", "--content", "text"]
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "results" in data
+ assert len(data["results"]) > 0
+
+ def test_contents_text_field_present(self, runner):
+ result = runner.invoke(
+ cli, ["--json", "contents", "https://exa.ai", "--content", "text"]
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ r = data["results"][0]
+ assert "text" in r
+ assert len(r["text"]) > 0
+
+ def test_contents_multiple_urls(self, runner):
+ result = runner.invoke(
+ cli,
+ ["--json", "contents", "https://exa.ai", "https://arxiv.org", "--content", "highlights"],
+ )
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert len(data["results"]) >= 1
+
+
+# ---------------------------------------------------------------------------
+# answer
+# ---------------------------------------------------------------------------
+
+class TestAnswerE2E:
+ def test_basic_answer(self, runner):
+ result = runner.invoke(cli, ["--json", "answer", "What is Exa's neural search?"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "answer" in data
+ assert len(data["answer"]) > 10
+
+ def test_answer_has_citations(self, runner):
+ result = runner.invoke(cli, ["--json", "answer", "How does Exa differ from Google?"])
+ assert result.exit_code == 0
+ data = json.loads(result.output)
+ assert "citations" in data
+ assert isinstance(data["citations"], list)
+
+ def test_answer_human_readable(self, runner):
+ result = runner.invoke(cli, ["answer", "What is RAG in AI?"])
+ assert result.exit_code == 0
+ assert len(result.output.strip()) > 0
+
+
+# ---------------------------------------------------------------------------
+# subprocess (entry-point) smoke test
+# ---------------------------------------------------------------------------
+
+class TestEntryPoint:
+ def test_cli_entry_point_help(self):
+ proc = _run("--help")
+ assert proc.returncode == 0
+ assert "Exa" in proc.stdout
+
+ def test_cli_entry_point_search(self):
+ proc = _run("--json", "search", "Exa API overview", "--num-results", "2")
+ assert proc.returncode == 0
+ data = json.loads(proc.stdout)
+ assert "results" in data
diff --git a/exa/agent-harness/cli_anything/exa/utils/__init__.py b/exa/agent-harness/cli_anything/exa/utils/__init__.py
new file mode 100644
index 000000000..d71040bc2
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/utils/__init__.py
@@ -0,0 +1 @@
+# cli_anything.exa.utils
diff --git a/exa/agent-harness/cli_anything/exa/utils/exa_backend.py b/exa/agent-harness/cli_anything/exa/utils/exa_backend.py
new file mode 100644
index 000000000..c9589eb30
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/utils/exa_backend.py
@@ -0,0 +1,105 @@
+"""
+exa_backend.py — Exa API client wrapper.
+
+Initialises the exa-py SDK client from EXA_API_KEY and exposes lightweight
+helper functions used by the core modules.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+try:
+ from exa_py import Exa
+except ImportError as exc: # pragma: no cover
+ raise ImportError(
+ "exa-py is required: pip install exa-py"
+ ) from exc
+
+
+def get_client() -> Exa:
+ """Return an authenticated Exa client.
+
+ Raises:
+ SystemExit: if EXA_API_KEY is not set in the environment.
+ """
+ api_key = os.environ.get("EXA_API_KEY", "").strip()
+ if not api_key:
+ raise RuntimeError(
+ "EXA_API_KEY environment variable is not set.\n"
+ "Get a free key at https://dashboard.exa.ai/api-keys"
+ )
+ return Exa(api_key=api_key)
+
+
+def check_connectivity() -> dict[str, Any]:
+ """Verify the API key is valid by running a minimal search.
+
+ Returns a dict with keys: ok (bool), message (str).
+ """
+ try:
+ client = get_client()
+ client.search("test", num_results=1)
+ return {"ok": True, "message": "API key valid — Exa reachable"}
+ except RuntimeError as exc:
+ return {"ok": False, "message": str(exc)}
+ except Exception as exc: # noqa: BLE001
+ return {"ok": False, "message": f"Exa API error: {exc}"}
+
+
+def build_contents_param(
+ content_mode: str,
+ freshness: str = "smart",
+) -> dict[str, Any] | None:
+ """Translate CLI content/freshness flags into an exa-py `contents` dict.
+
+ Args:
+ content_mode: "text" | "highlights" | "summary" | "none"
+ freshness: "smart" | "always" | "never"
+
+ Returns:
+ A contents dict suitable for passing to exa.search() / exa.find_similar(),
+ or None if content_mode is "none".
+ """
+ if content_mode == "none":
+ return None
+
+ contents: dict[str, Any] = {}
+
+ if content_mode == "text":
+ contents["text"] = {"max_characters": 10_000}
+ elif content_mode == "highlights":
+ contents["highlights"] = {"max_characters": 4_000}
+ elif content_mode == "summary":
+ contents["summary"] = True
+
+ # Freshness maps to max_age_hours
+ if freshness == "always":
+ contents["max_age_hours"] = 0
+ elif freshness == "never":
+ contents["max_age_hours"] = -1
+ # "smart" → omit max_age_hours (SDK default: cache + livecrawl fallback)
+
+ return contents or None
+
+
+# Category values accepted by the Exa API
+VALID_CATEGORIES = {
+ "company",
+ "people",
+ "research paper",
+ "news",
+ "personal site",
+ "financial report",
+}
+
+# CLI slug → API value (hyphens to spaces for multi-word categories)
+CATEGORY_SLUG_MAP: dict[str, str] = {
+ "company": "company",
+ "people": "people",
+ "research-paper": "research paper",
+ "news": "news",
+ "personal-site": "personal site",
+ "financial-report": "financial report",
+}
diff --git a/exa/agent-harness/cli_anything/exa/utils/repl_skin.py b/exa/agent-harness/cli_anything/exa/utils/repl_skin.py
new file mode 100644
index 000000000..c7312348a
--- /dev/null
+++ b/exa/agent-harness/cli_anything/exa/utils/repl_skin.py
@@ -0,0 +1,521 @@
+"""cli-anything REPL Skin — Unified terminal interface for all CLI harnesses.
+
+Copy this file into your CLI package at:
+ cli_anything/<software>/utils/repl_skin.py
+
+Usage:
+ from cli_anything.<software>.utils.repl_skin import ReplSkin
+
+ skin = ReplSkin("shotcut", version="1.0.0")
+ skin.print_banner() # auto-detects skills/SKILL.md inside the package
+ prompt_text = skin.prompt(project_name="my_video.mlt", modified=True)
+ skin.success("Project saved")
+ skin.error("File not found")
+ skin.warning("Unsaved changes")
+ skin.info("Processing 24 clips...")
+ skin.status("Track 1", "3 clips, 00:02:30")
+ skin.table(headers, rows)
+ skin.print_goodbye()
+"""
+
+import os
+import sys
+
+# ── ANSI color codes (no external deps for core styling) ──────────────
+
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_ITALIC = "\033[3m"
+_UNDERLINE = "\033[4m"
+
+# Brand colors
+_CYAN = "\033[38;5;80m" # cli-anything brand cyan
+_CYAN_BG = "\033[48;5;80m"
+_WHITE = "\033[97m"
+_GRAY = "\033[38;5;245m"
+_DARK_GRAY = "\033[38;5;240m"
+_LIGHT_GRAY = "\033[38;5;250m"
+
+# Software accent colors — each software gets a unique accent
+_ACCENT_COLORS = {
+ "gimp": "\033[38;5;214m", # warm orange
+ "blender": "\033[38;5;208m", # deep orange
+ "inkscape": "\033[38;5;39m", # bright blue
+ "audacity": "\033[38;5;33m", # navy blue
+ "libreoffice": "\033[38;5;40m", # green
+ "obs_studio": "\033[38;5;55m", # purple
+ "kdenlive": "\033[38;5;69m", # slate blue
+ "shotcut": "\033[38;5;35m", # teal green
+}
+_DEFAULT_ACCENT = "\033[38;5;75m" # default sky blue
+
+# Status colors
+_GREEN = "\033[38;5;78m"
+_YELLOW = "\033[38;5;220m"
+_RED = "\033[38;5;196m"
+_BLUE = "\033[38;5;75m"
+_MAGENTA = "\033[38;5;176m"
+
+# ── Brand icon ────────────────────────────────────────────────────────
+
+# The cli-anything icon: a small colored diamond/chevron mark
+_ICON = f"{_CYAN}{_BOLD}◆{_RESET}"
+_ICON_SMALL = f"{_CYAN}▸{_RESET}"
+
+# ── Box drawing characters ────────────────────────────────────────────
+
+_H_LINE = "─"
+_V_LINE = "│"
+_TL = "╭"
+_TR = "╮"
+_BL = "╰"
+_BR = "╯"
+_T_DOWN = "┬"
+_T_UP = "┴"
+_T_RIGHT = "├"
+_T_LEFT = "┤"
+_CROSS = "┼"
+
+
+def _strip_ansi(text: str) -> str:
+ """Remove ANSI escape codes for length calculation."""
+ import re
+ return re.sub(r"\033\[[^m]*m", "", text)
+
+
+def _visible_len(text: str) -> int:
+ """Get visible length of text (excluding ANSI codes)."""
+ return len(_strip_ansi(text))
+
+
+class ReplSkin:
+ """Unified REPL skin for cli-anything CLIs.
+
+ Provides consistent branding, prompts, and message formatting
+ across all CLI harnesses built with the cli-anything methodology.
+ """
+
+ def __init__(self, software: str, version: str = "1.0.0",
+ history_file: str | None = None, skill_path: str | None = None):
+ """Initialize the REPL skin.
+
+ Args:
+ software: Software name (e.g., "gimp", "shotcut", "blender").
+ version: CLI version string.
+ history_file: Path for persistent command history.
+ Defaults to ~/.cli-anything-<software>/history
+ skill_path: Path to the SKILL.md file for agent discovery.
+ Auto-detected from the package's skills/ directory if not provided.
+ Displayed in banner for AI agents to know where to read skill info.
+ """
+ self.software = software.lower().replace("-", "_")
+ self.display_name = software.replace("_", " ").title()
+ self.version = version
+
+ # Auto-detect skill path from package layout:
+ # cli_anything/<software>/utils/repl_skin.py (this file)
+ # cli_anything/<software>/skills/SKILL.md (target)
+ if skill_path is None:
+ from pathlib import Path
+ _auto = Path(__file__).resolve().parent.parent / "skills" / "SKILL.md"
+ if _auto.is_file():
+ skill_path = str(_auto)
+ self.skill_path = skill_path
+ self.accent = _ACCENT_COLORS.get(self.software, _DEFAULT_ACCENT)
+
+ # History file
+ if history_file is None:
+ from pathlib import Path
+ hist_dir = Path.home() / f".cli-anything-{self.software}"
+ hist_dir.mkdir(parents=True, exist_ok=True)
+ self.history_file = str(hist_dir / "history")
+ else:
+ self.history_file = history_file
+
+ # Detect terminal capabilities
+ self._color = self._detect_color_support()
+
+ def _detect_color_support(self) -> bool:
+ """Check if terminal supports color."""
+ if os.environ.get("NO_COLOR"):
+ return False
+ if os.environ.get("CLI_ANYTHING_NO_COLOR"):
+ return False
+ if not hasattr(sys.stdout, "isatty"):
+ return False
+ return sys.stdout.isatty()
+
+ def _c(self, code: str, text: str) -> str:
+ """Apply color code if colors are supported."""
+ if not self._color:
+ return text
+ return f"{code}{text}{_RESET}"
+
+ # ── Banner ────────────────────────────────────────────────────────
+
+ def print_banner(self):
+ """Print the startup banner with branding."""
+ inner = 54
+
+ def _box_line(content: str) -> str:
+ """Wrap content in box drawing, padding to inner width."""
+ pad = inner - _visible_len(content)
+ vl = self._c(_DARK_GRAY, _V_LINE)
+ return f"{vl}{content}{' ' * max(0, pad)}{vl}"
+
+ top = self._c(_DARK_GRAY, f"{_TL}{_H_LINE * inner}{_TR}")
+ bot = self._c(_DARK_GRAY, f"{_BL}{_H_LINE * inner}{_BR}")
+
+ # Title: ◆ cli-anything · Shotcut
+ icon = self._c(_CYAN + _BOLD, "◆")
+ brand = self._c(_CYAN + _BOLD, "cli-anything")
+ dot = self._c(_DARK_GRAY, "·")
+ name = self._c(self.accent + _BOLD, self.display_name)
+ title = f" {icon} {brand} {dot} {name}"
+
+ ver = f" {self._c(_DARK_GRAY, f' v{self.version}')}"
+ tip = f" {self._c(_DARK_GRAY, ' Type help for commands, quit to exit')}"
+ empty = ""
+
+ # Skill path for agent discovery
+ skill_line = None
+ if self.skill_path:
+ skill_icon = self._c(_MAGENTA, "◇")
+ skill_label = self._c(_DARK_GRAY, " Skill:")
+ skill_path_display = self._c(_LIGHT_GRAY, self.skill_path)
+ skill_line = f" {skill_icon} {skill_label} {skill_path_display}"
+
+ print(top)
+ print(_box_line(title))
+ print(_box_line(ver))
+ if skill_line:
+ print(_box_line(skill_line))
+ print(_box_line(empty))
+ print(_box_line(tip))
+ print(bot)
+ print()
+
+ # ── Prompt ────────────────────────────────────────────────────────
+
+ def prompt(self, project_name: str = "", modified: bool = False,
+ context: str = "") -> str:
+ """Build a styled prompt string for prompt_toolkit or input().
+
+ Args:
+ project_name: Current project name (empty if none open).
+ modified: Whether the project has unsaved changes.
+ context: Optional extra context to show in prompt.
+
+ Returns:
+ Formatted prompt string.
+ """
+ parts = []
+
+ # Icon
+ if self._color:
+ parts.append(f"{_CYAN}◆{_RESET} ")
+ else:
+ parts.append("> ")
+
+ # Software name
+ parts.append(self._c(self.accent + _BOLD, self.software))
+
+ # Project context
+ if project_name or context:
+ ctx = context or project_name
+ mod = "*" if modified else ""
+ parts.append(f" {self._c(_DARK_GRAY, '[')}")
+ parts.append(self._c(_LIGHT_GRAY, f"{ctx}{mod}"))
+ parts.append(self._c(_DARK_GRAY, ']'))
+
+ parts.append(self._c(_GRAY, " ❯ "))
+
+ return "".join(parts)
+
+ def prompt_tokens(self, project_name: str = "", modified: bool = False,
+ context: str = ""):
+ """Build prompt_toolkit formatted text tokens for the prompt.
+
+ Use with prompt_toolkit's FormattedText for proper ANSI handling.
+
+ Returns:
+ list of (style, text) tuples for prompt_toolkit.
+ """
+ accent_hex = _ANSI_256_TO_HEX.get(self.accent, "#5fafff")
+ tokens = []
+
+ tokens.append(("class:icon", "◆ "))
+ tokens.append(("class:software", self.software))
+
+ if project_name or context:
+ ctx = context or project_name
+ mod = "*" if modified else ""
+ tokens.append(("class:bracket", " ["))
+ tokens.append(("class:context", f"{ctx}{mod}"))
+ tokens.append(("class:bracket", "]"))
+
+ tokens.append(("class:arrow", " ❯ "))
+
+ return tokens
+
+ def get_prompt_style(self):
+ """Get a prompt_toolkit Style object matching the skin.
+
+ Returns:
+ prompt_toolkit.styles.Style
+ """
+ try:
+ from prompt_toolkit.styles import Style
+ except ImportError:
+ return None
+
+ accent_hex = _ANSI_256_TO_HEX.get(self.accent, "#5fafff")
+
+ return Style.from_dict({
+ "icon": "#5fdfdf bold", # cyan brand color
+ "software": f"{accent_hex} bold",
+ "bracket": "#585858",
+ "context": "#bcbcbc",
+ "arrow": "#808080",
+ # Completion menu
+ "completion-menu.completion": "bg:#303030 #bcbcbc",
+ "completion-menu.completion.current": f"bg:{accent_hex} #000000",
+ "completion-menu.meta.completion": "bg:#303030 #808080",
+ "completion-menu.meta.completion.current": f"bg:{accent_hex} #000000",
+ # Auto-suggest
+ "auto-suggest": "#585858",
+ # Bottom toolbar
+ "bottom-toolbar": "bg:#1c1c1c #808080",
+ "bottom-toolbar.text": "#808080",
+ })
+
+ # ── Messages ──────────────────────────────────────────────────────
+
+ def success(self, message: str):
+ """Print a success message with green checkmark."""
+ icon = self._c(_GREEN + _BOLD, "✓")
+ print(f" {icon} {self._c(_GREEN, message)}")
+
+ def error(self, message: str):
+ """Print an error message with red cross."""
+ icon = self._c(_RED + _BOLD, "✗")
+ print(f" {icon} {self._c(_RED, message)}", file=sys.stderr)
+
+ def warning(self, message: str):
+ """Print a warning message with yellow triangle."""
+ icon = self._c(_YELLOW + _BOLD, "⚠")
+ print(f" {icon} {self._c(_YELLOW, message)}")
+
+ def info(self, message: str):
+ """Print an info message with blue dot."""
+ icon = self._c(_BLUE, "●")
+ print(f" {icon} {self._c(_LIGHT_GRAY, message)}")
+
+ def hint(self, message: str):
+ """Print a subtle hint message."""
+ print(f" {self._c(_DARK_GRAY, message)}")
+
+ def section(self, title: str):
+ """Print a section header."""
+ print()
+ print(f" {self._c(self.accent + _BOLD, title)}")
+ print(f" {self._c(_DARK_GRAY, _H_LINE * len(title))}")
+
+ # ── Status display ────────────────────────────────────────────────
+
+ def status(self, label: str, value: str):
+ """Print a key-value status line."""
+ lbl = self._c(_GRAY, f" {label}:")
+ val = self._c(_WHITE, f" {value}")
+ print(f"{lbl}{val}")
+
+ def status_block(self, items: dict[str, str], title: str = ""):
+ """Print a block of status key-value pairs.
+
+ Args:
+ items: Dict of label -> value pairs.
+ title: Optional title for the block.
+ """
+ if title:
+ self.section(title)
+
+ max_key = max(len(k) for k in items) if items else 0
+ for label, value in items.items():
+ lbl = self._c(_GRAY, f" {label:<{max_key}}")
+ val = self._c(_WHITE, f" {value}")
+ print(f"{lbl}{val}")
+
+ def progress(self, current: int, total: int, label: str = ""):
+ """Print a simple progress indicator.
+
+ Args:
+ current: Current step number.
+ total: Total number of steps.
+ label: Optional label for the progress.
+ """
+ pct = int(current / total * 100) if total > 0 else 0
+ bar_width = 20
+ filled = int(bar_width * current / total) if total > 0 else 0
+ bar = "█" * filled + "░" * (bar_width - filled)
+ text = f" {self._c(_CYAN, bar)} {self._c(_GRAY, f'{pct:3d}%')}"
+ if label:
+ text += f" {self._c(_LIGHT_GRAY, label)}"
+ print(text)
+
+ # ── Table display ─────────────────────────────────────────────────
+
+ def table(self, headers: list[str], rows: list[list[str]],
+ max_col_width: int = 40):
+ """Print a formatted table with box-drawing characters.
+
+ Args:
+ headers: Column header strings.
+ rows: List of rows, each a list of cell strings.
+ max_col_width: Maximum column width before truncation.
+ """
+ if not headers:
+ return
+
+ # Calculate column widths
+ col_widths = [min(len(h), max_col_width) for h in headers]
+ for row in rows:
+ for i, cell in enumerate(row):
+ if i < len(col_widths):
+ col_widths[i] = min(
+ max(col_widths[i], len(str(cell))), max_col_width
+ )
+
+ def pad(text: str, width: int) -> str:
+ t = str(text)[:width]
+ return t + " " * (width - len(t))
+
+ # Header
+ header_cells = [
+ self._c(_CYAN + _BOLD, pad(h, col_widths[i]))
+ for i, h in enumerate(headers)
+ ]
+ sep = self._c(_DARK_GRAY, f" {_V_LINE} ")
+ header_line = f" {sep.join(header_cells)}"
+ print(header_line)
+
+ # Separator
+ sep_parts = [self._c(_DARK_GRAY, _H_LINE * w) for w in col_widths]
+ sep_line = self._c(_DARK_GRAY, f" {'───'.join([_H_LINE * w for w in col_widths])}")
+ print(sep_line)
+
+ # Rows
+ for row in rows:
+ cells = []
+ for i, cell in enumerate(row):
+ if i < len(col_widths):
+ cells.append(self._c(_LIGHT_GRAY, pad(str(cell), col_widths[i])))
+ row_sep = self._c(_DARK_GRAY, f" {_V_LINE} ")
+ print(f" {row_sep.join(cells)}")
+
+ # ── Help display ──────────────────────────────────────────────────
+
+ def help(self, commands: dict[str, str]):
+ """Print a formatted help listing.
+
+ Args:
+ commands: Dict of command -> description pairs.
+ """
+ self.section("Commands")
+ max_cmd = max(len(c) for c in commands) if commands else 0
+ for cmd, desc in commands.items():
+ cmd_styled = self._c(self.accent, f" {cmd:<{max_cmd}}")
+ desc_styled = self._c(_GRAY, f" {desc}")
+ print(f"{cmd_styled}{desc_styled}")
+ print()
+
+ # ── Goodbye ───────────────────────────────────────────────────────
+
+ def print_goodbye(self):
+ """Print a styled goodbye message."""
+ print(f"\n {_ICON_SMALL} {self._c(_GRAY, 'Goodbye!')}\n")
+
+ # ── Prompt toolkit session factory ────────────────────────────────
+
+ def create_prompt_session(self):
+ """Create a prompt_toolkit PromptSession with skin styling.
+
+ Returns:
+ A configured PromptSession, or None if prompt_toolkit unavailable.
+ """
+ try:
+ from prompt_toolkit import PromptSession
+ from prompt_toolkit.history import FileHistory
+ from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+ from prompt_toolkit.formatted_text import FormattedText
+
+ style = self.get_prompt_style()
+
+ session = PromptSession(
+ history=FileHistory(self.history_file),
+ auto_suggest=AutoSuggestFromHistory(),
+ style=style,
+ enable_history_search=True,
+ )
+ return session
+ except ImportError:
+ return None
+
+ def get_input(self, pt_session, project_name: str = "",
+ modified: bool = False, context: str = "") -> str:
+ """Get input from user using prompt_toolkit or fallback.
+
+ Args:
+ pt_session: A prompt_toolkit PromptSession (or None).
+ project_name: Current project name.
+ modified: Whether project has unsaved changes.
+ context: Optional context string.
+
+ Returns:
+ User input string (stripped).
+ """
+ if pt_session is not None:
+ from prompt_toolkit.formatted_text import FormattedText
+ tokens = self.prompt_tokens(project_name, modified, context)
+ return pt_session.prompt(FormattedText(tokens)).strip()
+ else:
+ raw_prompt = self.prompt(project_name, modified, context)
+ return input(raw_prompt).strip()
+
+ # ── Toolbar builder ───────────────────────────────────────────────
+
+ def bottom_toolbar(self, items: dict[str, str]):
+ """Create a bottom toolbar callback for prompt_toolkit.
+
+ Args:
+ items: Dict of label -> value pairs to show in toolbar.
+
+ Returns:
+ A callable that returns FormattedText for the toolbar.
+ """
+ def toolbar():
+ from prompt_toolkit.formatted_text import FormattedText
+ parts = []
+ for i, (k, v) in enumerate(items.items()):
+ if i > 0:
+ parts.append(("class:bottom-toolbar.text", " │ "))
+ parts.append(("class:bottom-toolbar.text", f" {k}: "))
+ parts.append(("class:bottom-toolbar", v))
+ return FormattedText(parts)
+ return toolbar
+
+
+# ── ANSI 256-color to hex mapping (for prompt_toolkit styles) ─────────
+
+_ANSI_256_TO_HEX = {
+ "\033[38;5;33m": "#0087ff", # audacity navy blue
+ "\033[38;5;35m": "#00af5f", # shotcut teal
+ "\033[38;5;39m": "#00afff", # inkscape bright blue
+ "\033[38;5;40m": "#00d700", # libreoffice green
+ "\033[38;5;55m": "#5f00af", # obs purple
+ "\033[38;5;69m": "#5f87ff", # kdenlive slate blue
+ "\033[38;5;75m": "#5fafff", # default sky blue
+ "\033[38;5;80m": "#5fd7d7", # brand cyan
+ "\033[38;5;208m": "#ff8700", # blender deep orange
+ "\033[38;5;214m": "#ffaf00", # gimp warm orange
+}
diff --git a/exa/agent-harness/setup.py b/exa/agent-harness/setup.py
new file mode 100644
index 000000000..1f4d98455
--- /dev/null
+++ b/exa/agent-harness/setup.py
@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""
+setup.py for cli-anything-exa
+
+Install with: pip install -e .
+Or publish to PyPI: python -m build && twine upload dist/*
+"""
+
+from setuptools import setup, find_namespace_packages
+
+with open("cli_anything/exa/README.md", "r", encoding="utf-8") as fh:
+ long_description = fh.read()
+
+setup(
+ name="cli-anything-exa",
+ version="1.0.0",
+ author="cli-anything contributors",
+ author_email="",
+ description="CLI harness for Exa — AI-powered web search, similar-page discovery, and LLM-synthesized answers via the Exa API",
+ long_description=long_description,
+ long_description_content_type="text/markdown",
+ url="https://github.com/HKUDS/CLI-Anything",
+ packages=find_namespace_packages(include=["cli_anything.*"]),
+ classifiers=[
+ "Development Status :: 4 - Beta",
+ "Intended Audience :: Developers",
+ "Topic :: Software Development :: Libraries :: Python Modules",
+ "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+ "License :: OSI Approved :: MIT License",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.10",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ ],
+ python_requires=">=3.10",
+ install_requires=[
+ "click>=8.0.0",
+ "prompt-toolkit>=3.0.0",
+ "exa-py>=1.0.0",
+ ],
+ extras_require={
+ "dev": [
+ "pytest>=7.0.0",
+ "pytest-cov>=4.0.0",
+ ],
+ },
+ entry_points={
+ "console_scripts": [
+ "cli-anything-exa=cli_anything.exa.exa_cli:main",
+ ],
+ },
+ package_data={
+ "cli_anything.exa": ["skills/*.md"],
+ },
+ include_package_data=True,
+ zip_safe=False,
+)
diff --git a/registry.json b/registry.json
index a69bb4335..b341b174a 100644
--- a/registry.json
+++ b/registry.json
@@ -466,6 +466,20 @@
"category": "graphics",
"contributor": "Taeyoung96",
"contributor_url": "https://github.com/Taeyoung96"
+ },
+ {
+ "name": "exa",
+ "display_name": "Exa",
+ "version": "1.0.0",
+ "description": "AI-powered web search, similar-page discovery, and LLM-synthesised answers via the Exa API",
+ "requires": "EXA_API_KEY (free tier at exa.ai)",
+ "homepage": "https://exa.ai",
+ "install_cmd": "pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=exa/agent-harness",
+ "entry_point": "cli-anything-exa",
+ "skill_md": "exa/agent-harness/cli_anything/exa/skills/SKILL.md",
+ "category": "search",
+ "contributor": "tgonzalezc5",
+ "contributor_url": "https://github.com/tgonzalezc5"
}
]
}