deepsieve-cli 0.1.0__py3-none-any.whl

deepsieve_cli/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .main import main
+
+sys.exit(main())

deepsieve_cli/client.py

@@ -0,0 +1,149 @@
+"""HTTP client for `/v1`, plus the device-authorization login flow.
+
+Deliberately a thin httpx wrapper rather than a dependency on the generated
+SDK: the CLI needs the unauthenticated device endpoints before any credential
+exists, and keeping the dependency surface at httpx keeps `uvx deepsieve`
+startup fast. The same choice the stdio MCP package made.
+
+Errors are surfaced as the typed `/v1` envelope so the CLI can print the
+message the API actually gave — a 403 must never render as "something failed".
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+USER_AGENT = "deepsieve-cli"
+
+
+class ApiError(Exception):
+    def __init__(self, code: str, message: str, *, request_id: str | None = None) -> None:
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        tail = f" (request id {self.request_id})" if self.request_id else ""
+        return f"{self.message}{tail}"
+
+
+@dataclass
+class DeviceAuthorization:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+class Client:
+    def __init__(self, origin: str, api_key: str | None = None, timeout: float = 60.0) -> None:
+        self.origin = origin.rstrip("/")
+        self.api_key = api_key
+        self._timeout = timeout
+
+    def _headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        h = {"User-Agent": USER_AGENT, **(extra or {})}
+        if self.api_key:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        raw: bool = False,
+    ) -> Any:
+        url = f"{self.origin}{path}"
+        try:
+            with httpx.Client(timeout=self._timeout, follow_redirects=True) as c:
+                r = c.request(
+                    method, url, params=params, json=json_body, headers=self._headers(headers)
+                )
+        except httpx.RequestError as exc:
+            raise ApiError("network_error", f"Could not reach {self.origin}: {exc}") from exc
+
+        if raw and r.is_success:
+            return r.text
+        try:
+            body = r.json()
+        except ValueError:
+            if r.is_success:
+                return {"raw": r.text}
+            raise ApiError("http_error", f"HTTP {r.status_code} from {path}") from None
+        if not r.is_success:
+            err = (body or {}).get("error") or {}
+            raise ApiError(
+                err.get("code", f"http_{r.status_code}"),
+                err.get("message", f"HTTP {r.status_code} from {path}"),
+                request_id=err.get("request_id"),
+            )
+        return body
+
+    # ── device authorization ────────────────────────────────────────────────
+
+    def start_device_authorization(
+        self, client_name: str, preset: str = "cli"
+    ) -> DeviceAuthorization:
+        # Ask for the CLI preset, not the broad `agent` one. The consent screen
+        # lists what it asks for, and asking a security-attentive developer to
+        # approve "manage webhook endpoints" for a tool that has no webhook
+        # command is how you lose their trust at the first screen.
+        body = self.request(
+            "POST",
+            "/v1/auth/device/code",
+            json_body={"client_name": client_name, "preset": preset},
+        )
+        return DeviceAuthorization(
+            device_code=body["device_code"],
+            user_code=body["user_code"],
+            verification_uri=body["verification_uri"],
+            verification_uri_complete=body.get("verification_uri_complete")
+            or body["verification_uri"],
+            expires_in=int(body.get("expires_in", 600)),
+            interval=int(body.get("interval", 5)),
+        )
+
+    def poll_for_credential(
+        self, auth: DeviceAuthorization, *, on_tick=None, sleep=time.sleep
+    ) -> dict[str, Any]:
+        """Poll until approved, denied, or expired.
+
+        Honours the server's `interval`, and backs off on `slow_down` as
+        RFC 8628 requires — a CLI that ignores that is how a device flow turns
+        into a self-inflicted denial of service.
+        """
+        interval = auth.interval
+        deadline = time.monotonic() + auth.expires_in
+        while time.monotonic() < deadline:
+            sleep(interval)
+            if on_tick:
+                on_tick()
+            try:
+                return self.request(
+                    "POST", "/v1/auth/device/token", json_body={"device_code": auth.device_code}
+                )
+            except ApiError as exc:
+                if exc.code == "authorization_pending":
+                    continue
+                if exc.code == "slow_down":
+                    interval += 5
+                    continue
+                # A shared limiter bucket or a transient blip must not abort a
+                # sign-in the human is in the middle of approving: back off and
+                # keep waiting until the authorization itself expires.
+                if exc.code in ("rate_limited", "network_error") or exc.code.startswith("http_5"):
+                    interval = min(interval + 5, 30)
+                    continue
+                raise
+        raise ApiError("expired_token", "Timed out waiting for approval. Run login again.")

deepsieve_cli/config.py

@@ -0,0 +1,116 @@
+"""Profiles and credential storage.
+
+A profile is `(origin, api_key)` under a name. That is what makes it safe to
+work against staging and production side by side: they are separate profiles,
+never a global "current login" a developer has to remember the state of.
+
+Credentials live in a 0600 file under the user's config directory, never in
+shell history and never in the repo. `DEEPSIEVE_API_KEY` in the environment
+always wins, so CI needs no login and no file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_ORIGIN = "https://deepsieve.ai"
+ENV_KEY = "DEEPSIEVE_API_KEY"
+ENV_ORIGIN = "DEEPSIEVE_BASE_URL"
+ENV_PROFILE = "DEEPSIEVE_PROFILE"
+
+
+def config_path() -> Path:
+    """`$XDG_CONFIG_HOME/deepsieve/config.json`, or the OS equivalent."""
+    override = os.environ.get("DEEPSIEVE_CONFIG")
+    if override:
+        return Path(override)
+    base = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(base) if base else Path.home() / ".config"
+    return root / "deepsieve" / "config.json"
+
+
+@dataclass
+class Profile:
+    name: str
+    origin: str
+    api_key: str | None = None
+    key_name: str | None = None
+    scopes: list[str] | None = None
+
+    @property
+    def is_env_credential(self) -> bool:
+        return bool(os.environ.get(ENV_KEY)) and self.api_key == os.environ.get(ENV_KEY)
+
+
+def _read() -> dict:
+    path = config_path()
+    if not path.exists():
+        return {"profiles": {}}
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {"profiles": {}}
+    data.setdefault("profiles", {})
+    return data
+
+
+def _write(data: dict) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # chmod BEFORE the secret is written, so it is never briefly world-readable.
+    tmp = path.with_suffix(".tmp")
+    tmp.touch(mode=0o600, exist_ok=True)
+    os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)
+    tmp.write_text(json.dumps(data, indent=2) + "\n")
+    tmp.replace(path)
+    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+
+
+def profile_name(explicit: str | None = None) -> str:
+    return explicit or os.environ.get(ENV_PROFILE) or "default"
+
+
+def load_profile(name: str | None = None) -> Profile:
+    """Resolve a profile, with environment variables taking precedence.
+
+    Env-first is what makes the same binary work in CI without a login step —
+    and it means a compromised config file cannot silently override an
+    explicitly-provided CI credential.
+    """
+    resolved = profile_name(name)
+    stored = _read()["profiles"].get(resolved, {})
+    return Profile(
+        name=resolved,
+        origin=(os.environ.get(ENV_ORIGIN) or stored.get("origin") or DEFAULT_ORIGIN).rstrip("/"),
+        api_key=os.environ.get(ENV_KEY) or stored.get("api_key"),
+        key_name=stored.get("key_name"),
+        scopes=stored.get("scopes"),
+    )
+
+
+def save_profile(profile: Profile) -> None:
+    data = _read()
+    data["profiles"][profile.name] = {
+        "origin": profile.origin,
+        "api_key": profile.api_key,
+        "key_name": profile.key_name,
+        "scopes": profile.scopes,
+    }
+    _write(data)
+
+
+def forget_profile(name: str) -> bool:
+    data = _read()
+    if name not in data["profiles"]:
+        return False
+    del data["profiles"][name]
+    _write(data)
+    return True
+
+
+def list_profiles() -> dict[str, dict]:
+    return _read()["profiles"]

deepsieve_cli/main.py

@@ -0,0 +1,531 @@
+"""`deepsieve` — the DeepSieve CLI.
+
+Scope is deliberate. This is the operator's tool: sign in, start and watch
+research, read the cited dataset, wire an agent up. It does NOT manage billing,
+organizations, API keys, or edit an active Blueprint — those are decisions a
+human should make in the app, and a terminal (or an agent driving one) is the
+wrong place to make them irreversibly. The credential it holds is ceilinged at
+the `agent` preset, so the restraint is enforced server-side too, not just by
+the absence of a subcommand.
+
+Output: human-readable tables on a TTY, `--json` for pipes and agents. Exit
+codes are stable — 0 success, 1 failure, 2 usage, 3 auth, 4 still-running.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+import uuid
+import webbrowser
+from typing import Any
+
+from . import config
+from .client import ApiError, Client
+
+EXIT_OK, EXIT_FAIL, EXIT_USAGE, EXIT_AUTH, EXIT_PENDING = 0, 1, 2, 3, 4
+
+CLIENT_NAME = "DeepSieve CLI"
+
+
+# ── output helpers ───────────────────────────────────────────────────────────
+
+
+def _tty() -> bool:
+    return sys.stdout.isatty()
+
+
+def out(data: Any, as_json: bool, human: str | None = None) -> None:
+    if as_json or human is None:
+        print(json.dumps(data, indent=2, default=str))
+    else:
+        print(human)
+
+
+def err(message: str) -> None:
+    print(f"error: {message}", file=sys.stderr)
+
+
+def _table(rows: list[list[str]], headers: list[str]) -> str:
+    widths = [len(h) for h in headers]
+    for r in rows:
+        for i, cell in enumerate(r):
+            widths[i] = max(widths[i], len(cell))
+    line = "  ".join(h.upper().ljust(widths[i]) for i, h in enumerate(headers))
+    body = ["  ".join(c.ljust(widths[i]) for i, c in enumerate(r)) for r in rows]
+    return "\n".join([line, *body])
+
+
+def _client(args) -> tuple[Client, config.Profile]:
+    prof = config.load_profile(getattr(args, "profile", None))
+    return Client(prof.origin, prof.api_key), prof
+
+
+def _require_auth(args) -> tuple[Client, config.Profile]:
+    client, prof = _client(args)
+    if not prof.api_key:
+        err(
+            f"not signed in for profile '{prof.name}'. Run: deepsieve login"
+            + (f" --profile {prof.name}" if prof.name != "default" else "")
+        )
+        raise SystemExit(EXIT_AUTH)
+    return client, prof
+
+
+# ── commands ─────────────────────────────────────────────────────────────────
+
+
+def cmd_login(args) -> int:
+    origin = (args.origin or os.environ.get(config.ENV_ORIGIN) or "").rstrip("/")
+    name = config.profile_name(args.profile)
+    if not origin:
+        existing = config.load_profile(name)
+        origin = existing.origin
+    client = Client(origin)
+
+    if args.api_key:
+        # Headless path. Verify before storing, so a typo fails now rather than
+        # on the next command with a confusing 401.
+        client.api_key = args.api_key
+        try:
+            me = client.request("GET", "/v1/me")
+        except ApiError as exc:
+            err(f"that key did not work against {origin}: {exc}")
+            return EXIT_AUTH
+        config.save_profile(
+            config.Profile(
+                name=name,
+                origin=origin,
+                api_key=args.api_key,
+                key_name="(provided)",
+                scopes=me.get("scopes"),
+            )
+        )
+        out({"signed_in": True, "profile": name, "origin": origin}, args.json,
+            f"Signed in to {origin} as profile '{name}'.")
+        return EXIT_OK
+
+    try:
+        auth = client.start_device_authorization(CLIENT_NAME)
+    except ApiError as exc:
+        err(str(exc))
+        return EXIT_FAIL
+
+    print(f"\n  Your code:  {auth.user_code}\n")
+    print(f"  Open: {auth.verification_uri_complete}\n")
+    if not args.no_browser:
+        try:
+            webbrowser.open(auth.verification_uri_complete)
+        except Exception:  # noqa: BLE001 — a headless box has no browser; the URL is printed
+            pass
+    print("  Waiting for approval…", end="", flush=True)
+
+    try:
+        cred = client.poll_for_credential(auth, on_tick=lambda: print(".", end="", flush=True))
+    except ApiError as exc:
+        print()
+        err(str(exc))
+        return EXIT_AUTH
+    print()
+
+    config.save_profile(
+        config.Profile(
+            name=name,
+            origin=origin,
+            api_key=cred["api_key"],
+            key_name=cred.get("key_name"),
+            scopes=cred.get("scopes"),
+        )
+    )
+    print(f"\n  Signed in to {origin} as profile '{name}'.")
+    print(f"  Credential: {cred.get('key_name')} — revoke any time at {origin}/settings/api-keys\n")
+    return EXIT_OK
+
+
+def cmd_logout(args) -> int:
+    name = config.profile_name(args.profile)
+    removed = config.forget_profile(name)
+    msg = (
+        f"Signed out of profile '{name}'. The API key still exists — revoke it at "
+        "/settings/api-keys if it should stop working."
+        if removed
+        else f"No stored credential for profile '{name}'."
+    )
+    out({"signed_out": removed, "profile": name}, args.json, msg)
+    return EXIT_OK
+
+
+def cmd_whoami(args) -> int:
+    client, prof = _require_auth(args)
+    try:
+        me = client.request("GET", "/v1/me")
+    except ApiError as exc:
+        err(str(exc))
+        return EXIT_AUTH
+    if args.json:
+        out(me, True)
+        return EXIT_OK
+    print(f"profile    {prof.name}")
+    print(f"origin     {prof.origin}")
+    print(f"org        {me.get('org_id')}")
+    print(f"workspace  {me.get('workspace_schema')}")
+    print(f"role       {me.get('role')}")
+    print(f"scopes     {', '.join(me.get('scopes') or []) or '(full)'}")
+    return EXIT_OK
+
+
+def cmd_profiles(args) -> int:
+    profiles = config.list_profiles()
+    active = config.profile_name(args.profile)
+    if args.json:
+        out({k: {"origin": v.get("origin"), "active": k == active} for k, v in profiles.items()}, True)
+        return EXIT_OK
+    if not profiles:
+        print("No profiles yet. Run: deepsieve login")
+        return EXIT_OK
+    rows = [
+        [("* " if k == active else "  ") + k, v.get("origin", ""), v.get("key_name") or ""]
+        for k, v in sorted(profiles.items())
+    ]
+    print(_table(rows, ["profile", "origin", "credential"]))
+    return EXIT_OK
+
+
+def cmd_runs_list(args) -> int:
+    client, _ = _require_auth(args)
+    params: dict[str, Any] = {"limit": args.limit}
+    if args.status:
+        params["status"] = args.status
+    try:
+        body = client.request("GET", "/v1/research/runs", params=params)
+    except ApiError as exc:
+        err(str(exc))
+        return EXIT_FAIL
+    if args.json:
+        out(body, True)
+        return EXIT_OK
+    rows = [
+        [r.get("id", "")[:8], r.get("status", ""), str(r.get("created_at", ""))[:19],
+         (r.get("title") or r.get("query") or "")[:48]]
+        for r in body.get("data", [])
+    ]
+    print(_table(rows, ["id", "status", "created", "title"]) if rows else "No runs yet.")
+    return EXIT_OK
+
+
+def cmd_runs_get(args) -> int:
+    client, _ = _require_auth(args)
+    try:
+        body = client.request("GET", f"/v1/research/runs/{args.run_id}")
+    except ApiError as exc:
+        err(str(exc))
+        return EXIT_FAIL
+    if args.json:
+        out(body, True)
+    else:
+        print(f"id       {body.get('id')}")
+        print(f"status   {body.get('status')}  (done={body.get('done')})")
+        if body.get("error"):
+            print(f"error    {body['error'].get('message')}")
+    if not body.get("done"):
+        return EXIT_PENDING
+    return EXIT_OK if body.get("status") == "completed" else EXIT_FAIL
+
+
+def cmd_runs_create(args) -> int:
+    client, prof = _require_auth(args)
+    if bool(args.query) == bool(args.seeds):
+        err("pass exactly one of --query or --seeds")
+        return EXIT_USAGE
+
+    body: dict[str, Any] = {"depth": args.depth, "dry_run": args.dry_run, "monitored": args.monitored}
+    if args.query:
+        body["query"] = args.query
+    if args.seeds:
+        body["seeds"] = [s.strip() for s in args.seeds.split(",") if s.strip()]
+
+    # A real run spends money. Confirm interactively unless told not to — and
+    # never silently in a pipe, where nobody is watching.
+    if not args.dry_run and not args.yes:
+        if not _tty():
+            err("refusing to start a billable run non-interactively; pass --yes (or --dry-run)")
+            return EXIT_USAGE
+        print(f"This starts a REAL research run on {prof.origin} — it spends credits "
+              f"and takes 15-60 minutes.")
+        if input("Continue? [y/N] ").strip().lower() not in ("y", "yes"):
+            print("Cancelled.")
+            return EXIT_OK
+
+    try:
+        created = client.request(
+            "POST",
+            "/v1/research/runs",
+            json_body=body,
+            headers={"Idempotency-Key": args.idempotency_key or uuid.uuid4().hex},
+        )
+    except ApiError as exc:
+        err(str(exc))
+        return EXIT_FAIL
+
+    if args.json and not args.wait:
+        out(created, True)
+        return EXIT_OK
+    run_id = created.get("id")
+    print(f"started run {run_id} ({'dry run' if args.dry_run else 'billable'})")
+    if not args.wait:
+        print(f"poll with: deepsieve runs get {run_id}")
+        return EXIT_OK
+    return _wait(client, run_id, args)
+
+
+def cmd_runs_wait(args) -> int:
+    client, _ = _require_auth(args)
+    return _wait(client, args.run_id, args)
+
+
+def _wait(client: Client, run_id: str, args) -> int:
+    """Poll to completion, honouring Retry-After semantics via a fixed floor."""
+    deadline = time.monotonic() + args.timeout
+    while time.monotonic() < deadline:
+        try:
+            body = client.request("GET", f"/v1/research/runs/{run_id}")
+        except ApiError as exc:
+            err(str(exc))
+            return EXIT_FAIL
+        if body.get("done"):
+            if args.json:
+                out(body, True)
+            else:
+                print(f"run {run_id} finished: {body.get('status')}")
+                if body.get("error"):
+                    print(f"  {body['error'].get('message')}")
+            return EXIT_OK if body.get("status") == "completed" else EXIT_FAIL
+        if not args.json and _tty():
+            print(f"  status: {body.get('status')}…", end="\r", flush=True)
+        time.sleep(args.interval)
+    err(f"still running after {args.timeout}s; poll with: deepsieve runs get {run_id}")
+    return EXIT_PENDING
+
+
+def cmd_runs_cancel(args) -> int:
+    client, _ = _require_auth(args)
+    try:
+        body = client.request("POST", f"/v1/research/runs/{args.run_id}/cancel")
+    except ApiError as exc:
+        err(str(exc))
+        return EXIT_FAIL
+    out(body, args.json, f"cancellation requested for {args.run_id}")
+    return EXIT_OK
+
+
+def cmd_data_catalog(args) -> int:
+    client, _ = _require_auth(args)
+    try:
+        body = client.request("GET", "/v1/data")
+    except ApiError as exc:
+        err(str(exc))
+        return EXIT_FAIL
+    if args.json:
+        out(body, True)
+        return EXIT_OK
+    for ent in body.get("entities", []):
+        cols = ", ".join(c.get("key", "") for c in ent.get("columns", []))
+        print(f"{ent.get('key')}  ({ent.get('label', '')})\n    {cols}\n")
+    return EXIT_OK
+
+
+def cmd_data_get(args) -> int:
+    client, _ = _require_auth(args)
+    params: dict[str, Any] = {"limit": args.limit, "receipts": args.receipts}
+    if args.cursor:
+        params["cursor"] = args.cursor
+    if args.updated_since:
+        params["updated_since"] = args.updated_since
+    try:
+        body = client.request("GET", f"/v1/data/{args.entity}", params=params)
+    except ApiError as exc:
+        err(str(exc))
+        return EXIT_FAIL
+    out(body, True)  # rows are structured either way; --json only stills the notes
+    if body.get("truncated") and not args.json:
+        print(
+            "\nnote: this response is a PREVIEW, not the full dataset "
+            f"(preview_row_cap={body.get('preview_row_cap')}).",
+            file=sys.stderr,
+        )
+    return EXIT_OK
+
+
+def _remote_server_name(prof) -> str:
+    """The MCP server name this deployment tells agents to register.
+
+    Read from the deployment's own published setup payload, which is
+    unauthenticated and carries the canonical registration line. That matters:
+    the obvious source (`/api/system/status`) requires a session, so it 401s in
+    exactly the situation this command exists for — wiring up an agent before
+    anyone has signed in.
+
+    The fallback is the brand default, never a slice of the hostname: emitting
+    "staging" for staging.example.com drops the brand and collides with every
+    other deployment whose first label happens to match.
+    """
+    try:
+        body = Client(prof.origin).request("GET", "/setup.md", raw=True)
+        m = re.search(r"claude mcp add --transport http (\S+) ", body or "")
+        if m:
+            return m.group(1)
+    except Exception:  # noqa: BLE001 — naming must never block printing config
+        pass
+    return "deepsieve"
+
+
+def cmd_setup_mcp(args) -> int:
+    """Print (or install) the MCP registration for this profile's origin."""
+    _, prof = _client(args)
+    url = f"{prof.origin}/mcp"
+    # Ask the deployment what it calls itself rather than assuming "deepsieve":
+    # hardcoding it here would print a staging registration that overwrites the
+    # production entry — the exact collision the env-aware naming fixed.
+    name = args.name or _remote_server_name(prof)
+    if args.json:
+        out({"mcpServers": {name: {"url": url}}}, True)
+        return EXIT_OK
+    print(f"Register the {name} MCP server (browser login, no key needed):\n")
+    print(f"  claude mcp add --transport http {name} {url}\n")
+    print("Or add to your agent's MCP config:\n")
+    print(json.dumps({"mcpServers": {name: {"url": url}}}, indent=2))
+    print(f"\nFull setup, including skills and rules: {prof.origin}/setup.md")
+    return EXIT_OK
+
+
+# ── parser ───────────────────────────────────────────────────────────────────
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # The global flags live on a shared PARENT parser as well as the root, so
+    # both `deepsieve --json runs list` and `deepsieve runs list --json` work.
+    # argparse subparsers do not inherit root options, and the docs promise
+    # "add --json to any command" — the trailing form is the one people type.
+    # SUPPRESS is load-bearing: without it the subparser re-applies its own
+    # default and CLOBBERS a value given before the subcommand, so
+    # `deepsieve --json data get x` would silently print human output.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--profile",
+        default=argparse.SUPPRESS,
+        help="named profile (default: $DEEPSIEVE_PROFILE or 'default')",
+    )
+    common.add_argument(
+        "--json",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="machine-readable output",
+    )
+
+    p = argparse.ArgumentParser(
+        prog="deepsieve",
+        description="Run cited deep research from your terminal.",
+        epilog="Docs: https://deepsieve.ai/developers/cli",
+        parents=[common],
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    lg = sub.add_parser("login", help="sign in via your browser (device flow)", parents=[common])
+    lg.add_argument("--origin", help="deployment URL (e.g. https://staging.deepsieve.ai)")
+    lg.add_argument("--api-key", help="headless: use a key instead of the browser flow")
+    lg.add_argument("--no-browser", action="store_true", help="print the URL, don't open it")
+    lg.set_defaults(func=cmd_login)
+
+    lo = sub.add_parser("logout", help="forget this profile's stored credential", parents=[common])
+    lo.set_defaults(func=cmd_logout)
+
+    wa = sub.add_parser("whoami", help="show the resolved identity, workspace and scopes", parents=[common])
+    wa.set_defaults(func=cmd_whoami)
+
+    pr = sub.add_parser("profiles", help="list configured profiles", parents=[common])
+    pr.set_defaults(func=cmd_profiles)
+
+    runs = sub.add_parser("runs", help="research runs", parents=[common]).add_subparsers(dest="sub", required=True)
+
+    rl = runs.add_parser("list", help="recent runs", parents=[common])
+    rl.add_argument("--status")
+    rl.add_argument("--limit", type=int, default=20)
+    rl.set_defaults(func=cmd_runs_list)
+
+    rg = runs.add_parser("get", help="one run's status", parents=[common])
+    rg.add_argument("run_id")
+    rg.set_defaults(func=cmd_runs_get)
+
+    rc = runs.add_parser("create", help="start a run", parents=[common])
+    rc.add_argument("--query")
+    rc.add_argument("--seeds", help="comma-separated names or URLs")
+    rc.add_argument("--depth", default="standard", choices=["standard", "max"])
+    rc.add_argument("--dry-run", action="store_true", help="free simulated run (~15s)")
+    rc.add_argument("--no-monitor", dest="monitored", action="store_false",
+                    help="one-off; don't bill ongoing freshness")
+    rc.add_argument("--wait", action="store_true", help="poll until it finishes")
+    rc.add_argument("--interval", type=int, default=15)
+    rc.add_argument("--timeout", type=int, default=3600)
+    rc.add_argument("--idempotency-key")
+    rc.add_argument("-y", "--yes", action="store_true", help="skip the billable-run confirmation")
+    rc.set_defaults(func=cmd_runs_create)
+
+    rw = runs.add_parser("wait", help="poll an existing run to completion", parents=[common])
+    rw.add_argument("run_id")
+    rw.add_argument("--interval", type=int, default=15)
+    rw.add_argument("--timeout", type=int, default=3600)
+    rw.set_defaults(func=cmd_runs_wait)
+
+    rx = runs.add_parser("cancel", help="cancel an in-flight run", parents=[common])
+    rx.add_argument("run_id")
+    rx.set_defaults(func=cmd_runs_cancel)
+
+    data = sub.add_parser("data", help="your cited dataset", parents=[common]).add_subparsers(dest="sub", required=True)
+
+    dc = data.add_parser("catalog", help="entities and columns (never guess these)", parents=[common])
+    dc.set_defaults(func=cmd_data_catalog)
+
+    dg = data.add_parser("get", help="rows for one entity", parents=[common])
+    dg.add_argument("entity")
+    dg.add_argument("--limit", type=int, default=25)
+    dg.add_argument("--cursor")
+    dg.add_argument("--updated-since")
+    dg.add_argument("--receipts", action="store_true", help="include per-cell citations")
+    dg.set_defaults(func=cmd_data_get)
+
+    setup = sub.add_parser("setup", help="connect other tools", parents=[common]).add_subparsers(
+        dest="sub", required=True
+    )
+    sm = setup.add_parser("mcp", help="MCP server registration for this origin", parents=[common])
+    sm.add_argument("--name", help="server name to register")
+    sm.set_defaults(func=cmd_setup_mcp)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    # SUPPRESS means the attrs only exist when passed; normalise once here so
+    # every command can read them unconditionally.
+    for attr, default in (("json", False), ("profile", None)):
+        if not hasattr(args, attr):
+            setattr(args, attr, default)
+    try:
+        return args.func(args)
+    except SystemExit as exc:  # _require_auth and friends
+        return int(exc.code) if exc.code is not None else EXIT_FAIL
+    except KeyboardInterrupt:
+        print()
+        return EXIT_FAIL
+    except ApiError as exc:
+        err(str(exc))
+        return EXIT_FAIL
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

deepsieve_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+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>

deepsieve_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+deepsieve_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deepsieve_cli/__main__.py,sha256=I0WVsFDX16-IxsgTiX1tUcx9ypuiTkokIaLK2fU5RpI,53
+deepsieve_cli/client.py,sha256=jcQAZvMm_mLkC8iIBkSSP_94zY5ry8bVdXQwOw6NkYo,5679
+deepsieve_cli/config.py,sha256=YygQfIs0u03BXuU-NQvL0GaDhkmRd2_uvOpis4i74xw,3453
+deepsieve_cli/main.py,sha256=8hL5eFWM420imOIRE7NAulMRCakxHgMauDhdr3fTRVI,19937
+deepsieve_cli-0.1.0.dist-info/METADATA,sha256=JYciuIPwIqA1aPYHOqDwbRukx6ajq5B7tfdBIR0STd0,2515
+deepsieve_cli-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+deepsieve_cli-0.1.0.dist-info/entry_points.txt,sha256=yJCcmxJr4LGXwLTa8j4QfSM_rNx_0fvE0cttFyi9OhM,54
+deepsieve_cli-0.1.0.dist-info/RECORD,,

deepsieve_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

deepsieve_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+deepsieve = deepsieve_cli.main:main