DeepSearch CLI

Command-line client for the DeepSearch Developer API. Built on @reloadapp/deepsearch-client, so it shares the same types, scopes, wallet metering, and sandbox behavior as the REST API.

deepsearch search "Ada Lovelace" --sandbox

Install

The package lives in this monorepo and depends on the checked-in TypeScript SDK.

# build the SDK it depends on, then the CLI
npm --prefix sdks/typescript install && npm --prefix sdks/typescript run build
npm --prefix sdks/cli install && npm --prefix sdks/cli run build

# run it
node sdks/cli/dist/index.js search "Ada Lovelace" --sandbox

# or link it globally as `deepsearch`
npm --prefix sdks/cli link
deepsearch --help

Requires Node.js ≥ 20.9.

Authentication

The CLI resolves your API key in this order (highest priority first):

1. --api-key dsk_...
2. DEEPSEARCH_API_KEY environment variable
3. ~/.deepsearch/config.json (written by deepsearch login)

Create a key at https://deepsearch.app/developers, then store it once:

deepsearch login                 # prompts for the key (hidden) and base URL
deepsearch login --api-key dsk_... --base-url https://deepsearch.app

The config file is written with 0600 permissions. deepsearch config get masks the key.

The base URL resolves the same way (--base-url › DEEPSEARCH_BASE_URL › config › https://deepsearch.app).

Commands

| Command | Description | | --- | --- | | search <query> | Find people by name, phone, email, or username | | dossier <name> | Build or replay a public-footprint dossier | | chat <name> <message...> | Ask a follow-up question about a person | | jobs create <op> | Queue an async job (search, dossier, or chat) | | jobs list | List recent async jobs | | jobs get <id> | Fetch one job by id | | jobs events <id> | Replay a job's stored SSE event stream | | status | Show developer API availability (no key required) | | login | Save an API key and base URL to config | | config <get\|set\|path> | Inspect or edit stored config |

Common options

| Flag | Effect | | --- | --- | | --json | Print the raw JSON envelope instead of formatted output | | --sandbox | Use deterministic, unmetered Ada Lovelace fixtures | | --stream | Stream live SSE events (search, dossier, chat) | | --api-key <key> | Override the API key for one call | | --base-url <url> | Override the API base URL | | -h, --help / -v, --version | Help / version |

Examples

# Name search, formatted
deepsearch search "Ada Lovelace" --sandbox

# Username search scoped to platforms, raw JSON
deepsearch search ada --type username --platforms linkedin,github --json

# Dossier, streaming progress as it scans
deepsearch dossier "Ada Lovelace" --stream

# Ask a question
deepsearch chat "Ada Lovelace" "Summarize the public sources" --sandbox

# Async job from a payload file, with idempotency
deepsearch jobs create dossier --input @job.json --idempotency-key demo-1
deepsearch jobs get job_123 --json

# Pipe a payload in
echo '{"query":"Grace Hopper","type":"name","format":"json"}' \
  | deepsearch jobs create search --input -

# One-off key without storing anything
DEEPSEARCH_API_KEY=dsk_... deepsearch search "Grace Hopper"

Output & exit codes

• Default output is human-formatted; usage/metering is printed to stderr so --json-free output stays pipe-friendly. Add --json for the full typed envelope on stdout.
• Exit codes: 0 success, 1 runtime/API error (a DeepSearchError prints status, code, and request id), 2 usage error (bad flags or missing arguments).

Use --sandbox while integrating: it requires a valid scoped key but returns deterministic fixtures and never spends wallet credits.