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 key asks only for what the CLI's commands use, so it cannot create a Blueprint. If an agent will use this credential to create Blueprints, sign in with deepsieve login --preset agent; the approval screen lists the extra scopes before you grant them.

The commands you'll use

bash

deepsieve whoami                               # identity, organization, active Blueprint, scopes
deepsieve data catalog                         # your entities + columns
deepsieve data get companies --receipts        # rows with per-cell citations
deepsieve data history companies headquarters_city  # every change to a column, newest first
deepsieve data history companies headquarters_city --record <id>  # one record's cell: what replaced what
deepsieve data history --cell <cell> --rechecks    # one cell by id, plus re-check findings not applied
deepsieve runs create --query "..." --dry-run  # free, ~15s, nothing persisted
deepsieve runs create --blueprint <id> --query "..." --wait  # real run: spends credits
deepsieve runs create --blueprint <id> --seeds "..." --allowed-source "*.gov"  # only cite these
deepsieve runs create --blueprint <id> --query "..." --expected-total 1000  # refuse (charge nothing) if it now costs more than the estimate
deepsieve runs list
deepsieve runs get <id>
deepsieve runs cancel <id>
deepsieve runs monitoring <id> --off            # stop paying for a duplicate; asks first
deepsieve runs monitoring <id> --on --commit-lock  # back on after the free 30 days commits 30 days; an agent asks its human first
deepsieve runs retry <id>                        # retry a failed run; a retry that charges shows its total and asks
deepsieve runs retry <id> --expected-total 1200  # confirm that total (cents); an agent asks its human first
deepsieve runs retry <id> --expected-total 1200 --expected-funding plan_credits  # and bind what pays, as quoted
deepsieve runs retry <id> --expected-total 3000 --expected-funding mixed --expected-prepaid 1000  # a mixed quote binds its split too (deepsieve-cli 0.9.0)
deepsieve runs reruns <id>                       # a report's re-research waiting for approval, its total and quote_id
deepsieve runs reruns <id> --approve --expected-total 900 --quote-id <qid>  # approve it (spends); an agent asks its human first
deepsieve runs reruns <id> --auto-approve-on --cap 50  # approve future re-research automatically, up to $50 a month; asks first
deepsieve runs reruns <id> --auto-approve-off    # stop approving automatically
deepsieve chat thread <run-id>                 # changes, with status + warnings
deepsieve chat confirm <action-id>             # apply a change waiting for confirmation
deepsieve chat dismiss <action-id>             # decline it; nothing is written
deepsieve chat revert <action-id>              # undo an applied change
deepsieve changes list --live                  # merges, renames, successor links, removed links
deepsieve changes undo <id>                    # asks first; --yes in scripts
deepsieve links remove <entity> <record-id> <linked-entity> <target-id>  # remove a wrong link; research won't add it back; asks first
deepsieve subscription cancel                  # at the end of the period; nothing new is charged; asks first
deepsieve subscription resume                  # undo it while the period runs; asks first
deepsieve holds list --pending                 # cells you set, with newer research
deepsieve holds apply <cell> --finding <id>    # take it (the cell stays protected)
deepsieve holds keep <cell> --finding <id>     # keep your value; research won't ask again from the same pages
deepsieve holds release <cell>                 # let research update it again
deepsieve merge preview companies --survivor <id> --loser <id>   # writes nothing
deepsieve merge apply companies --survivor <id> --loser <id> --choice KEY=loser --preview-digest <digest>  # the preview's digest
deepsieve knowledge list                       # what your team told DeepSieve about the field
deepsieve knowledge add --kind source_caution --statement "Lags a quarter." --host crunchbase.com
deepsieve knowledge add --kind value_meaning --statement "Funding is the total raised." --entity labs --column funding --min 1000 --max 5e9 --unit USD
deepsieve knowledge edit <id> --statement "..." --revision 2  # a newer edit is refused, not overwritten
deepsieve knowledge retire <id>                # stop using it in later runs; restore brings it back
deepsieve knowledge delete <id>                # asks first; retire keeps it
deepsieve knowledge list --draft <session-id>   # a draft's notes; every knowledge write takes --draft too
deepsieve runs knowledge <run-id>              # what your knowledge did in a run: carried, cited by QA, decided
deepsieve knowledge usage --runs 20            # what your notes decided in recent runs, or why no run looked

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

runs retry, runs reruns, runs monitoring, links remove and merge apply's --preview-digest / --without-preview need deepsieve-cli 0.6.0 or later. data history needs a deepsieve-cli release after 0.8.0. merge apply applies exactly the merge merge preview showed: pass its digest, or --without-preview to merge without one on purpose.

Domain knowledge is what your team knows about the field: where the reliable data is, which sources mislead, what a value means and its plausible range, what to leave out. Later runs carry each entry wherever it applies; it changes no stored value. --entity, --column and --host say what an entry is about (none: the whole Blueprint). When an entry contradicts or repeats one you already have, nothing is saved: the command names the entries and exits 2, and you run it again with --on-conflict supersede or --on-conflict keep_both. runs knowledge keeps the counts apart as the report does: entries a run carried, cells QA cited one in its verdict (a model's claim), and cells your knowledge decided (by code). A run whose record was not kept says not recorded, never zero. knowledge usage gives each entry one line across recent runs, in the Domain knowledge tab's words: what it decided, that it was checked and changed nothing, that nothing in its scope came up, or that it was not checked and why. Writing needs the member role; a sign-in from before this release can read knowledge but not write it until you run deepsieve login again. --draft <session-id> on knowledge list, add, edit, retire, restore and delete acts on a Blueprint still being created: its notes go live when it is approved. Writing them needs blueprint:create rather than knowledge:write, which the default sign-in does not carry: sign in with deepsieve login --preset agent. knowledge, knowledge usage, --draft and runs knowledge need deepsieve-cli 0.10.0 or later. A cell's own knowledge (knowledge_decided, knowledge_cited) is in data get --receipts.

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 must name its Blueprint with --blueprint <id> (deepsieve whoami shows your active Blueprint's id); without it the CLI stops before sending anything. 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.

Restrict where evidence may come from

--allowed-source names the sites a run is allowed to cite. It is repeatable, and it is a rule the run enforces rather than a preference it is asked to honour: a cell supported only by pages outside the list is left blank, and those URLs come back on the run as a lead you can follow by hand.

bash

deepsieve runs create --blueprint <id> --seeds "Acme, Globex" \
  --allowed-source "*.gov" \
  --allowed-source "https://sec.gov/cgi-bin/*" \
  --allowed-source blueprint:primary

A bare host allows its subdomains, *.gov allows any host under that suffix, a URL prefix is matched exactly on host, and blueprint:primary expands to the primary sources your Blueprint declares. The hosts of any URL seeds are always allowed. The server resolves and validates the list, so a pattern it refuses (a bare *.com, more than fifty entries) fails before anything is spent; the run's allowed_sources field echoes the list it actually enforced. Needs deepsieve-cli 0.3.0 or later.

Exact phrases and kinds of document

A --query that quotes a phrase or says "PDFs only" makes the run also search for that wording or that kind of document. These are extra searches, never filters, and they never change the price. --phrase and --file-type (both repeatable) together replace EVERY phrase and file type read from the query, so pass all the ones you want kept; --no-search-hints drops them all:

bash

deepsieve runs create --blueprint <id> --query "Acme filings, PDFs only" --no-search-hints
deepsieve runs create --blueprint <id> --query "Acme filings" --file-type pdf --file-type xlsx

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, including `deepsieve merge apply` meeting a tie it was not told how to settle (`ties_unresolved`), or rows under different parents that can never be merged (`merge_across_parents`), and a knowledge write that conflicts with an entry (`knowledge_conflict`) or edits an old revision (`knowledge_revision_conflict`)
`3`	not authenticated, or a sign-in that cannot write knowledge yet (run `deepsieve login` again)
`4`	run still in progress
`5`	`deepsieve runs create --query` (the one command whose query a model parses) was refused because the organization's model allowance is used for this period (`model_allowance_exhausted`); wait for the reset rather than retrying

What it won't do

The CLI can't touch billing, members, API keys, or edit an active Blueprint's schema. 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. Domain knowledge is not schema: it changes only what later runs are told, so deepsieve knowledge writes it.

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.