@bigknoxy/exa-cli 0.1.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,250 @@
+# @bigknoxy/exa-cli
+
+[![npm version](https://img.shields.io/npm/v/@bigknoxy/exa-cli.svg)](https://www.npmjs.com/package/@bigknoxy/exa-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@bigknoxy/exa-cli.svg)](https://nodejs.org)
+
+A CLI wrapper for the [Exa MCP server](https://github.com/exa-labs/exa-mcp-server). Use Exa's powerful search, crawl, and research capabilities from the command line - optimized for LLM tool usage.
+
+## Why exa-cli?
+
+- **Free tier support** - Uses Exa's free MCP tier (no API key required)
+- **LLM-optimized** - CLI tools are more efficient for LLMs than MCP protocol
+- **All Exa tools** - Web search, code search, crawling, company research, people search, and deep research
+
+## Installation
+
+### Quick Install (Recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/bigknoxy/exa-cli/main/install.sh | sh
+```
+
+### npm
+
+```bash
+npm install -g @bigknoxy/exa-cli
+```
+
+### Run directly with npx
+
+```bash
+npx @bigknoxy/exa-cli search "your query"
+```
+
+## Uninstall
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/bigknoxy/exa-cli/main/uninstall.sh | sh
+```
+
+Or with npm:
+
+```bash
+npm uninstall -g @bigknoxy/exa-cli
+```
+
+> **Note**: The uninstall script will leave your config file (`~/.exarc`) in place. Remove it manually with `rm ~/.exarc` if desired.
+
+## Commands
+
+### `exa search <query>`
+
+Search the web for any topic.
+
+```bash
+exa search "latest AI news 2026" --num 10
+exa search "typescript best practices" --type fast --format json
+```
+
+**Options:**
+- `--num` - Number of results (default: 8)
+- `--type` - Search type: `auto` or `fast` (default: auto)
+- `--livecrawl` - Live crawl mode: `fallback` or `preferred` (default: fallback)
+- `--format` - Output format: `text`, `json`, or `markdown` (default: text)
+- `--api-key` - Override API key
+
+### `exa code <query>`
+
+Search for code examples and documentation.
+
+```bash
+exa code "React useState hook TypeScript" --tokens 3000
+exa code "express middleware authentication" --format markdown
+```
+
+**Options:**
+- `--tokens` - Token count 1000-50000 (default: 5000)
+- `--format` - Output format (default: text)
+- `--api-key` - Override API key
+
+### `exa crawl <url>`
+
+Extract content from a specific URL.
+
+```bash
+exa crawl https://docs.exa.ai --max-chars 5000
+exa crawl https://example.com/article --format json
+```
+
+**Options:**
+- `--max-chars` - Maximum characters to extract (default: 3000)
+- `--format` - Output format (default: text)
+- `--api-key` - Override API key
+
+### `exa company <name>`
+
+Research a company.
+
+```bash
+exa company Anthropic --num 5
+exa company "OpenAI" --format json
+```
+
+**Options:**
+- `--num` - Number of results (default: 3)
+- `--format` - Output format (default: text)
+- `--api-key` - Override API key
+
+### `exa people <query>`
+
+Search for people and professional profiles.
+
+```bash
+exa people "VP Engineering AI startups" --num 10
+exa people "machine learning researcher" --format json
+```
+
+**Options:**
+- `--num` - Number of results (default: 5)
+- `--format` - Output format (default: text)
+- `--api-key` - Override API key
+
+### `exa search-advanced <query>`
+
+Advanced search with full filter control.
+
+```bash
+exa search-advanced "AI agents 2026" \
+  --category news \
+  --include-domains techcrunch.com,wired.com \
+  --start-date 2026-01-01 \
+  --highlights
+```
+
+**Options:**
+- `--num` - Number of results, max 100 (default: 10)
+- `--type` - Search type: `auto`, `fast`, or `neural`
+- `--category` - Category filter: `company`, `research paper`, `news`, `tweet`, `personal site`, `people`, `financial report`
+- `--include-domains` - Comma-separated domains to include
+- `--exclude-domains` - Comma-separated domains to exclude
+- `--start-date` - Start published date (YYYY-MM-DD)
+- `--end-date` - End published date (YYYY-MM-DD)
+- `--highlights` - Enable highlights
+- `--summary` - Enable summaries
+- `--livecrawl` - Mode: `never`, `fallback`, `preferred`, `always`
+- `--format` - Output format (default: text)
+- `--api-key` - Override API key
+
+### `exa research start <instructions>`
+
+Start an AI research agent for complex questions.
+
+```bash
+exa research start "Compare flagship GPUs from NVIDIA, AMD, and Intel in 2026"
+exa research start "Analyze the electric vehicle market trends" --model exa-research-pro
+```
+
+**Options:**
+- `--model` - Research model: `exa-research-fast`, `exa-research`, `exa-research-pro` (default: exa-research-fast)
+- `--format` - Output format (default: text)
+- `--api-key` - Override API key
+
+### `exa research check <id>`
+
+Check the status of a research task.
+
+```bash
+exa research check abc123...
+```
+
+### `exa config`
+
+Manage configuration stored in `~/.exarc`.
+
+```bash
+exa config list              # Show all config
+exa config set apiKey YOUR_KEY   # Set API key
+exa config set output json   # Set default output format
+exa config get apiKey        # Get a config value
+exa config clear             # Reset to defaults
+```
+
+### `exa completion <shell>`
+
+Generate shell completion scripts.
+
+```bash
+# Bash
+exa completion bash > /etc/bash_completion.d/exa
+
+# Zsh
+exa completion zsh > ~/.zsh/completions/_exa
+
+# Fish
+exa completion fish > ~/.config/fish/completions/exa.fish
+```
+
+## Configuration
+
+Configuration is stored in `~/.exarc`:
+
+```json
+{
+  "apiKey": "your-api-key",
+  "output": "text",
+  "defaultNum": 8
+}
+```
+
+### API Key
+
+The CLI works with the free MCP tier by default (no API key required). To get higher rate limits:
+
+1. Get an API key from https://dashboard.exa.ai/api-keys
+2. Set it via config: `exa config set apiKey YOUR_KEY`
+3. Or use `--api-key` flag per command
+4. Or set `EXA_API_KEY` environment variable
+
+## Output Formats
+
+- `text` (default) - Human-readable with colors
+- `json` - Raw JSON output for scripting
+- `markdown` - Markdown formatted with links
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/bigknoxy/exa-cli.git
+cd exa-cli
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+
+# Development mode
+npm run dev search "test query"
+```
+
+## Requirements
+
+- Node.js 18+
+- npm or bun
+
+## License
+
+MIT

package/dist/commands/code.d.ts

@@ -0,0 +1,23 @@
+declare const _default: import("citty").CommandDef<{
+    query: {
+        type: "positional";
+        required: true;
+        description: string;
+    };
+    tokens: {
+        type: "string";
+        default: string;
+        description: string;
+    };
+    format: {
+        type: "string";
+        default: string;
+        description: string;
+    };
+    'api-key': {
+        type: "string";
+        description: string;
+    };
+}>;
+export default _default;
+//# sourceMappingURL=code.d.ts.map

package/dist/commands/code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code.d.ts","sourceRoot":"","sources":["../../src/commands/code.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;AAQA,wBAmDE"}

package/dist/commands/code.js

@@ -0,0 +1,55 @@
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+import { getMcpClient } from '../lib/mcp-client.js';
+import { formatOutput } from '../lib/output.js';
+const VALID_FORMATS = ['text', 'json', 'markdown'];
+export default defineCommand({
+    meta: {
+        name: 'code',
+        description: 'Search for code examples and documentation',
+    },
+    args: {
+        query: {
+            type: 'positional',
+            required: true,
+            description: 'Code search query (include language/framework)',
+        },
+        tokens: {
+            type: 'string',
+            default: '5000',
+            description: 'Token count (1000-50000)',
+        },
+        format: {
+            type: 'string',
+            default: 'text',
+            description: `Output format (${VALID_FORMATS.join(', ')})`,
+        },
+        'api-key': {
+            type: 'string',
+            description: 'Exa API key',
+        },
+    },
+    async run({ args }) {
+        const { query, tokens, format, 'api-key': apiKey } = args;
+        const tokensNum = Math.min(Math.max(parseInt(String(tokens), 10) || 5000, 1000), 50000);
+        const outputFormat = VALID_FORMATS.includes(format) ? format : 'text';
+        const mcpClient = getMcpClient();
+        try {
+            await mcpClient.connect(apiKey);
+            const result = await mcpClient.callTool('get_code_context_exa', {
+                query,
+                tokensNum,
+            });
+            const formatted = formatOutput(result, outputFormat);
+            console.log(formatted);
+        }
+        catch (error) {
+            consola.error('Failed to search code:', error instanceof Error ? error.message : 'Unknown error');
+            process.exit(1);
+        }
+        finally {
+            await mcpClient.close();
+        }
+    },
+});
+//# sourceMappingURL=code.js.map

package/dist/commands/code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code.js","sourceRoot":"","sources":["../../src/commands/code.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAG/C,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAU,CAAA;AAE3D,eAAe,aAAa,CAAC;IAC3B,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,4CAA4C;KAC1D;IACD,IAAI,EAAE;QACJ,KAAK,EAAE;YACL,IAAI,EAAE,YAAY;YAClB,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,gDAAgD;SAC9D;QACD,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,MAAM;YACf,WAAW,EAAE,0BAA0B;SACxC;QACD,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,MAAM;YACf,WAAW,EAAE,kBAAkB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;SAC3D;QACD,SAAS,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,aAAa;SAC3B;KACF;IACD,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE;QAChB,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;QAEzD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,CAAA;QACvF,MAAM,YAAY,GAAG,aAAa,CAAC,QAAQ,CAAC,MAAsC,CAAC,CAAC,CAAC,CAAC,MAAsB,CAAC,CAAC,CAAC,MAAM,CAAA;QAErH,MAAM,SAAS,GAAG,YAAY,EAAE,CAAA;QAEhC,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,OAAO,CAAC,MAA4B,CAAC,CAAA;YAErD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,sBAAsB,EAAE;gBAC9D,KAAK;gBACL,SAAS;aACV,CAAC,CAAA;YAEF,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;YACpD,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAA;YACjG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;gBAAS,CAAC;YACT,MAAM,SAAS,CAAC,KAAK,EAAE,CAAA;QACzB,CAAC;IACH,CAAC;CACF,CAAC,CAAA"}

package/dist/commands/company.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Company research command - Wraps the MCP company_research_exa tool
+ */
+declare const _default: import("citty").CommandDef<{
+    name: {
+        type: "positional";
+        required: true;
+        description: string;
+    };
+    num: {
+        type: "string";
+        default: string;
+        description: string;
+    };
+    format: {
+        type: "string";
+        default: string;
+        description: string;
+    };
+    'api-key': {
+        type: "string";
+        description: string;
+    };
+}>;
+export default _default;
+//# sourceMappingURL=company.d.ts.map

package/dist/commands/company.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"company.d.ts","sourceRoot":"","sources":["../../src/commands/company.ts"],"names":[],"mappings":"AAAA;;GAEG;;;;;;;;;;;;;;;;;;;;;;AAUH,wBAmDE"}

package/dist/commands/company.js

@@ -0,0 +1,58 @@
+/**
+ * Company research command - Wraps the MCP company_research_exa tool
+ */
+import { defineCommand } from 'citty';
+import { consola } from 'consola';
+import { getMcpClient } from '../lib/mcp-client.js';
+import { formatOutput } from '../lib/output.js';
+const VALID_FORMATS = ['text', 'json', 'markdown'];
+export default defineCommand({
+    meta: {
+        name: 'company',
+        description: 'Research a company',
+    },
+    args: {
+        name: {
+            type: 'positional',
+            required: true,
+            description: 'Company name to research',
+        },
+        num: {
+            type: 'string',
+            default: '3',
+            description: 'Number of results',
+        },
+        format: {
+            type: 'string',
+            default: 'text',
+            description: `Output format (${VALID_FORMATS.join(', ')})`,
+        },
+        'api-key': {
+            type: 'string',
+            description: 'Exa API key',
+        },
+    },
+    async run({ args }) {
+        const { name, num, format, 'api-key': apiKey } = args;
+        const numResults = parseInt(String(num), 10) || 3;
+        const outputFormat = VALID_FORMATS.includes(format) ? format : 'text';
+        const client = getMcpClient();
+        try {
+            await client.connect(apiKey);
+            const result = await client.callTool('company_research_exa', {
+                companyName: name,
+                numResults,
+            });
+            const output = formatOutput(result, outputFormat);
+            console.log(output);
+        }
+        catch (error) {
+            consola.error('Company research failed:', error instanceof Error ? error.message : 'Unknown error');
+            process.exit(1);
+        }
+        finally {
+            await client.close();
+        }
+    },
+});
+//# sourceMappingURL=company.js.map

package/dist/commands/company.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"company.js","sourceRoot":"","sources":["../../src/commands/company.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAG/C,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAU,CAAA;AAE3D,eAAe,aAAa,CAAC;IAC3B,IAAI,EAAE;QACJ,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,oBAAoB;KAClC;IACD,IAAI,EAAE;QACJ,IAAI,EAAE;YACJ,IAAI,EAAE,YAAY;YAClB,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,0BAA0B;SACxC;QACD,GAAG,EAAE;YACH,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,GAAG;YACZ,WAAW,EAAE,mBAAmB;SACjC;QACD,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,MAAM;YACf,WAAW,EAAE,kBAAkB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;SAC3D;QACD,SAAS,EAAE;YACT,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,aAAa;SAC3B;KACF;IACD,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE;QAChB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;QAErD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAA;QACjD,MAAM,YAAY,GAAG,aAAa,CAAC,QAAQ,CAAC,MAAsC,CAAC,CAAC,CAAC,CAAC,MAAsB,CAAC,CAAC,CAAC,MAAM,CAAA;QAErH,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;QAE7B,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,CAAC,MAA4B,CAAC,CAAA;YAElD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,sBAAsB,EAAE;gBAC3D,WAAW,EAAE,IAAI;gBACjB,UAAU;aACX,CAAC,CAAA;YAEF,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;YACjD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAA;YACnG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACtB,CAAC;IACH,CAAC;CACF,CAAC,CAAA"}

package/dist/commands/completion.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Completion command - Generate shell completion scripts
+ */
+declare const _default: import("citty").CommandDef<{
+    shell: {
+        type: "positional";
+        required: true;
+        description: string;
+        value: (val: string) => string;
+    };
+}>;
+export default _default;
+//# sourceMappingURL=completion.d.ts.map

package/dist/commands/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAAA;;GAEG;;;;;;qBAiZgB,MAAM;;;AAVzB,wBAwCE"}