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) — 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 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 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 instead.