# Exa CLI — Exhaustive Agent Operating Manual

This document provides complete, unabridged reference material for autonomous LLM agents and automation scripts driving the `exa` command-line tool.

---

## 1. Invocation Principles

- **Binary Name:** `exa`
- **Output Formats:**
  - Standard output is formatted in readable YAML by default.
  - Supplying the global `--json` flag changes all output on `stdout` and `stderr` to structured JSON.
  - Warnings and interactive prompts are emitted to `stderr` exclusively, ensuring `stdout` contains only valid, parseable payloads.
- **Exit Codes:**
  - `0`: Success (`ok`)
  - `1`: Unclassified runtime failure (`error`)
  - `2`: Network timeout or connection drop (`network`) — retry once with exponential backoff
  - `3`: Authentication failure or key rejection (`auth_required`) — stop immediately and surface remediation to the human operator
  - `4`: Requested resource or entity missing (`not_found`) — do not retry
  - `5`: API rate limit exceeded (`rate_limited`) — back off before retrying
  - `6`: Invalid argument combination or schema validation error (`invalid_input`) — correct invocation arguments
  - `7`: No account or API key available (`no_account`) — configure an account or provide credentials

---

## 2. Authentication & Multi-Account Resolution

Credentials can be passed via:
1. `--account <name>` (short `-a <name>`): Looks up the specified account in `config.yaml` and decrypts the API key from the host OS keystore.
2. `--api-key <key>`: Explicit API key supplied on the command line.
3. `EXA_API_KEY`: Environment variable holding the API key.

When multiple accounts are configured, explicitly pass `--account <name>` to prevent ambiguous or accidental operations.

### Keystore Integration
- **macOS:** `/usr/bin/security` (macOS Keychain)
- **Windows:** DPAPI (Data Protection API via `windows-sys`)
- **Linux:** `secret-tool` (freedesktop.org Secret Service / GNOME Keyring / KWallet)
- **Plaintext Fallback:** Enabled only when `EXA_ALLOW_PLAINTEXT_STORE=1` is set.

---

## 3. Command Reference

### `exa search`
Performs web search queries against the Exa neural search engine.

```bash
exa search <QUERY> [OPTIONS]
```

**Arguments:**
- `<QUERY>`: Natural language query string (required).

**Options:**
- `--num <COUNT>`: Number of results to return (integer 1–100, default 10).
- `--type <TYPE>`: Search mode (`auto`, `fast`, `instant`, `deep-lite`, `deep`, `deep-reasoning`).
- `--category <CATEGORY>`: Restrict search results to a specific domain category:
  - `company`: Commercial organization websites.
  - `people`: Personal profiles and directory pages.
  - `news`: Current journalistic publications.
  - `research paper`: Academic preprints and scientific papers.
  - `personal site`: Personal blogs and portfolios.
  - `financial report`: Corporate financial filings and earnings reports.
- `--include-domains <DOMAINS>`: Comma-separated list of hostnames to whitelist (e.g. `github.com,arxiv.org`).
- `--exclude-domains <DOMAINS>`: Comma-separated list of hostnames to blacklist (e.g. `pinterest.com`).
- `--start-date <DATE>`: Minimum publication date in ISO 8601 format (e.g. `2025-01-01`).
- `--end-date <DATE>`: Maximum publication date in ISO 8601 format (e.g. `2026-06-01`).
- `--highlights`: Return query-relevant highlighted text snippets.
- `--highlights-chars <COUNT>`: Maximum character budget for highlights (default 4000).
- `--text`: Return full page contents converted to clean markdown.
- `--text-chars <COUNT>`: Maximum character budget for full page markdown text.
- `--summary`: Include an LLM-generated summary of each page.
- `--user-location <CODE>`: Two-letter ISO country code (e.g. `US`, `DE`, `GB`) to localize search relevance.
- `-a, --account <ACCOUNT>`: Target named account.
- `--api-key <KEY>`: Direct API key override.
- `--json`: Format output as raw JSON.

**Output Structure (`--json`):**
```json
{
  "results": [
    {
      "id": "https://example.com/article",
      "url": "https://example.com/article",
      "title": "Example Article Title",
      "score": 0.892,
      "publishedDate": "2026-01-15T12:00:00.000Z",
      "author": "Author Name",
      "text": "# Markdown text...",
      "highlights": ["Relevant excerpt snippet 1", "Relevant excerpt snippet 2"],
      "summary": "Concise summary generated by LLM."
    }
  ]
}
```

---

### `exa contents`
Extracts cleaned, LLM-ready markdown content and summaries from one or more explicit URLs.

```bash
exa contents <URLS> [OPTIONS]
```

**Arguments:**
- `<URLS>`: Comma-separated list of web URLs to scrape (required).

**Options:**
- `--text`: Return full page text as markdown.
- `--text-chars <COUNT>`: Maximum characters for text extraction.
- `--highlights`: Return query-relevant excerpts.
- `--highlights-chars <COUNT>`: Maximum characters for highlights.
- `--highlights-query <QUERY>`: Custom query directing the selection of highlights.
- `--summary`: Return LLM-generated summary.
- `--summary-query <QUERY>`: Custom guidance prompt for summary generation.
- `--max-age <HOURS>`: Maximum cache age in hours (`0` = always live crawl, `-1` = cache only).
- `--subpages <COUNT>`: Number of subpages to crawl and extract per URL.
- `--subpage-target <KEYWORDS>`: Comma-separated list of target keywords prioritizing subpage discovery (e.g. `about,pricing,docs`).
- `-a, --account <ACCOUNT>`: Target named account.
- `--api-key <KEY>`: Direct API key override.
- `--json`: Format output as raw JSON.

*Validation Rule:* At least one of `--text`, `--highlights`, or `--summary` (or their associated query/char options) must be provided.

---

### `exa answer`
Generates an AI-synthesized answer grounded in real-time web citations.

```bash
exa answer <QUERY> [OPTIONS]
```

**Arguments:**
- `<QUERY>`: The question to answer (required).

**Options:**
- `--text`: Include the full text content in the citation references.
- `-a, --account <ACCOUNT>`: Target named account.
- `--api-key <KEY>`: Direct API key override.
- `--json`: Format output as raw JSON.

**Output Structure (`--json`):**
```json
{
  "answer": "Grounded answer text synthesized from web sources.",
  "citations": [
    {
      "id": "https://example.com/source",
      "url": "https://example.com/source",
      "title": "Source Page Title",
      "text": "Full markdown text if --text was specified"
    }
  ]
}
```

---

### `exa find-similar`
Discovers web pages semantically or structurally similar to a reference URL.

```bash
exa find-similar <URL> [OPTIONS]
```

**Arguments:**
- `<URL>`: Reference seed URL (required).

**Options:**
- `--num <COUNT>`: Number of similar pages to return (integer 1–100, default 10).
- `--include-domains <DOMAINS>`: Comma-separated domain whitelist.
- `--exclude-domains <DOMAINS>`: Comma-separated domain blacklist.
- `--start-date <DATE>`: Minimum publication date (ISO 8601).
- `--end-date <DATE>`: Maximum publication date (ISO 8601).
- `--highlights`: Return query-relevant excerpts.
- `--highlights-chars <COUNT>`: Max characters for highlights.
- `--text`: Return full page text as markdown.
- `--text-chars <COUNT>`: Max characters for text.
- `--summary`: Return LLM-generated summary.
- `-a, --account <ACCOUNT>`: Target named account.
- `--api-key <KEY>`: Direct API key override.
- `--json`: Format output as raw JSON.

---

### `exa accounts`
Manages multi-tenant accounts and local OS keystore credentials.

#### `exa accounts add <NAME>`
```bash
exa accounts add <NAME> [--api-key <KEY>] [--api-key-stdin] [--force] [--no-verify]
```
- `<NAME>`: Account alias (case-insensitive).
- `--api-key <KEY>`: Key literal.
- `--api-key-stdin`: Read key from stdin without terminal echo.
- `--force`: Replace existing key under this account name.
- `--no-verify`: Skip verification test query during addition.

#### `exa accounts list`
```bash
exa accounts list [--check] [--json]
```
- `--check`: Contacts the Exa API to verify token status (`valid`, `rejected`, or `unreachable`).

#### `exa accounts test <NAME>`
```bash
exa accounts test <NAME> [--json]
```
Tests stored credentials for the account against the Exa API.

#### `exa accounts remove <NAME>`
```bash
exa accounts remove <NAME> [--yes]
```
Removes the account from local configuration and deletes the key from the OS keystore. Does not revoke the key upstream.

---

### `exa login`
Browser-assisted interactive login:
```bash
exa login [NAME] [--api-key <KEY>] [--api-key-stdin] [--no-browser] [--force] [--no-verify]
```
Default account name is `default`. Automatically opens `https://dashboard.exa.ai/api-keys` in a web browser unless `--no-browser` is specified.

---

### `exa agent-readme`
Outputs the embedded agent manual:
```bash
exa agent-readme [--json]
```
When invoked with `--json`, returns structured metadata containing rules, API version, and exit code mappings.