Command line
xdive is the API from a shell. It is part of the xdive npm package, so it runs with npx and needs nothing installed beyond Node.js 18. It is built for coding agents such as Codex and Claude Code as much as for people: data goes to stdout, every message to stderr, and the exit code says what happened.
npx xdive login
npx xdive scrape https://docs.stripe.com/paymentsSign in
xdive login uses device sign-in: it prints a link and a code, you approve once in the browser, and the CLI saves a new API key with the scrape, crawl and search scopes to ~/.config/xdive/config.json (readable only by you). The key is listed under API Keys, where you can revoke it. xdive logout deletes the saved key from this machine.
In CI or an agent sandbox, set XDIVE_API_KEY instead; it takes precedence over the saved key. XDIVE_BASE_URL or --base-url points the CLI at a self-hosted server.
Commands
| Command | Does |
|---|---|
xdive scrape <url> | A page as Markdown. --max-chars and --offset read a long page in parts, --wait-for <ms> lets a slow page render, --format markdown,links,html asks for other formats (printed as JSON). |
xdive search <query> | Search results: title, URL and snippet. --limit sets how many. |
xdive research <question> | A cited answer with its sources. --deep researches longer. |
xdive map <url> | A site's URLs, one per line. --search keeps those about a topic. |
xdive crawl <url> | Several pages of a site as Markdown, waiting for the crawl to finish. --max-pages (default 10) and --max-depth (default 2). |
xdive extract <url...> --prompt "…" | Structured data from up to 10 pages, as JSON. |
xdive whoami | The organization and key in use. |
Add --json to any command for the API's JSON response.
For agents
- Output. stdout carries only the data: Markdown by default, JSON with
--json. Warnings (for examplecontent may be incomplete) and the "continue with--offset N" hint for long pages go to stderr, soxdive scrape URL > page.mdsaves just the page. - Long pages.
xdive scrape URL --max-chars 8000returns the first part; stderr then names the next offset. The parts come from one cached fetch. - Exit codes.
| Code | Meaning | What to do |
|---|---|---|
0 | Success | |
1 | Other error (the message is on stderr) | Read the message; do not loop. |
2 | Wrong usage | Fix the command; xdive --help lists the options. |
3 | Not signed in, or the key was refused | Run xdive login or set XDIVE_API_KEY. |
4 | Quota or key budget used up | Tell the user; retrying will not help. |
5 | Rate limited | Wait the number of seconds on stderr, then retry. |
The CLI already retries rate limits and network failures a few times with an Idempotency-Key, so a retry never runs or bills the work twice.