Metadata-Version: 2.4
Name: deepsieve-cli
Version: 0.1.0
Summary: DeepSieve CLI — run cited deep research from your terminal
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# deepsieve-cli

Run cited deep research from your terminal.

```bash
uv tool install deepsieve-cli   # or: pipx install deepsieve-cli
deepsieve login
```

`login` opens your browser, you approve a short code, and the CLI stores a
scoped API key. Nothing to copy, nothing pasted into your shell history. The
credential appears in **Settings → API keys** on your deployment and can be
revoked there at any time.

## Commands

```bash
deepsieve whoami                              # identity, workspace, scopes
deepsieve runs create --query "..." --dry-run # free simulated run (~15s)
deepsieve runs create --query "..." --wait    # real run: spends credits
deepsieve runs list
deepsieve runs get <id>                       # exit 4 while still running
deepsieve runs cancel <id>
deepsieve data catalog                        # entities + columns (never guess)
deepsieve data get companies --receipts       # rows with per-cell citations
deepsieve setup mcp                           # MCP registration for this origin
```

Add `--json` to anything for machine-readable output.

## Profiles: several deployments side by side

```bash
deepsieve login --profile staging --origin https://staging.deepsieve.ai
deepsieve --profile staging runs list
```

Each profile is its own `(origin, credential)` pair, so staging and production
never overwrite one another. `DEEPSIEVE_PROFILE` sets the default.

## CI and containers

Skip `login` entirely — set `DEEPSIEVE_API_KEY` (and `DEEPSIEVE_BASE_URL` if not
production). Environment variables take precedence over any stored profile.

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

## What it deliberately cannot do

No billing, no organization or member management, no API-key management, and it
cannot edit an active Blueprint. Those are decisions for a human in the app —
and the restriction is enforced server-side by the credential's scopes, not just
by the absence of a subcommand.

Starting a real (billable) run asks for confirmation, and refuses outright in a
non-interactive shell unless you pass `--yes`.

## Exit codes

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

Full docs: <https://deepsieve.ai/developers/cli>
