# 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.

```bash
npx xdive login
npx xdive scrape https://docs.stripe.com/payments
```

## Sign in

`xdive login` uses [device sign-in](https://xdive.dev/docs/authentication.md#device-sign-in-for-clis-and-agents): 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 example `content may be incomplete`) and the "continue with `--offset N`" hint for long pages go to stderr, so `xdive scrape URL > page.md` saves just the page.
- **Long pages.** `xdive scrape URL --max-chars 8000` returns 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.

---

Source: https://xdive.dev/docs/cli · All docs for agents: https://xdive.dev/llms.txt