# CLI

> Run cited research from your terminal — browser sign-in, no key to paste


The `deepsieve` CLI is for humans at a terminal and for agents that live in one.
It signs in through your browser, so there is no key to copy, and nothing
sensitive lands in your shell history.

```bash
uv tool install deepsieve-cli
deepsieve login
```

(or `pipx install deepsieve-cli`. For a one-off without installing:
`uvx --from deepsieve-cli deepsieve login` — but the later `deepsieve …`
commands need it on your PATH.)

You'll see a short code and a browser window:

```text
  Your code:  BUPP-W4ZQ

  Open: https://deepsieve.ai/cli-login?code=BUPP-W4ZQ

  Waiting for approval…
```

Approve it and you're signed in. Behind the scenes this is the OAuth device
flow ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) — the same
shape as `gh auth login`. What it grants you is an ordinary scoped API key, so
it shows up in [Settings → API keys](/settings/api-keys) and you can revoke it
there whenever you like.

## The commands you'll use

```bash
deepsieve whoami                               # identity, workspace, scopes
deepsieve data catalog                         # your entities + columns
deepsieve data get companies --receipts        # rows with per-cell citations
deepsieve runs create --query "..." --dry-run  # free, ~15s, nothing persisted
deepsieve runs create --query "..." --wait     # real run: spends credits
deepsieve runs list
deepsieve runs get <id>
deepsieve runs cancel <id>
```

Add `--json` to any command for machine-readable output — that's the mode to use
when a script or an agent is reading it.

## Test before you spend

`--dry-run` behaves exactly like a real run (same statuses, same row shape,
`"test": true`) but finishes in about 15 seconds and costs nothing. Build your
pipeline against it first:

```bash
deepsieve runs create --query "anything" --dry-run --wait --json
```

A real run spends credits and takes 15–60 minutes, so the CLI asks you to
confirm — and in a non-interactive shell it refuses outright unless you pass
`--yes`. That's deliberate: a script shouldn't be able to spend your balance by
surprise.

## Several deployments at once

Profiles keep each deployment's origin and credential separate, so staging can
never quietly become production:

```bash
deepsieve login --profile staging --origin https://deepsieve.your-company.example
deepsieve --profile staging runs list
```

`DEEPSIEVE_PROFILE` sets the default for a shell.

## CI and containers

Skip `login`. Set `DEEPSIEVE_API_KEY` (and `DEEPSIEVE_BASE_URL` unless you're on
production) and the CLI uses it directly — environment variables always win over
a stored profile, so a pipeline can't accidentally pick up a developer's login.

```bash
DEEPSIEVE_API_KEY=ds_live_... deepsieve --json data get companies
```

Create that key at [Settings → API keys](/settings/api-keys) with the **Agent**
preset.

## Exit codes

Stable, so shell scripts can branch on them:

| Code | Meaning |
|---|---|
| `0` | success |
| `1` | failure |
| `2` | usage error |
| `3` | not authenticated |
| `4` | run still in progress |

## What it won't do

The CLI can't touch billing, members, API keys, or edit an active Blueprint. Its
credential is ceilinged at the **Agent** scope preset, so that isn't just a
missing subcommand — the server refuses too. Schema changes and spending
settings belong to a human in the app.

## Connect your agent while you're here

```bash
deepsieve setup mcp
```

prints the MCP registration for whichever deployment the current profile points
at. For the full agent setup — MCP, skills, and a rules file — use the
[one-prompt quickstart](/developers) instead.