selltostate-cli 0.1.0__py3-none-any.whl

selltostate_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: selltostate-cli
+Version: 0.1.0
+Summary: selltostate: official CLI for the Sell to State government-contracts data API (REST/MCP parity).
+License-Expression: MIT
+Project-URL: Homepage, https://www.selltostate.com/cli/
+Project-URL: Source, https://github.com/getbeton/selltostate-cli
+Keywords: selltostate,government,tenders,procurement,cli
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# `selltostate-cli` — `selltostate`
+
+Official command-line client for the **Sell to State** government-contracts data API
+(`app.selltostate.com`). Python port of the npm package
+[`@selltostate/cli`](https://www.npmjs.com/package/@selltostate/cli): the same commands,
+flags, output and exit codes. Standard library only, Python 3.9+.
+
+```bash
+pipx install selltostate-cli      # or: pip install selltostate-cli / uv tool install selltostate-cli
+selltostate auth login            # prompts for the key, checks it with /whoami, saves it
+selltostate search "IT consulting" --country singapore --year-min 2026 --format json
+```
+
+Get a key at `https://app.selltostate.com/dashboard` (Settings -> API keys).
+
+## Auth and configuration
+
+The CLI sends a dashboard API key as the `x-api-key` header. Resolution order:
+
+1. `--api-key` / `--api-url` flags
+2. `STS_API_KEY` / `STS_API_URL` environment variables
+3. `~/.config/selltostate/config.json` (written by `auth login`, mode `0600`; honours `XDG_CONFIG_HOME`)
+4. Default API URL `https://app.selltostate.com`
+
+The npm and the Python CLI share this config file.
+
+## Commands
+
+| Command | Endpoint |
+| --- | --- |
+| `whoami` | `GET /api/v1/whoami` |
+| `search <q> [filters]` | `GET /api/v1/search` |
+| `awards [filters]` | `GET /api/v1/awards` |
+| `get buyer\|supplier\|tender\|sector <id>` | `GET /api/v1/{buyers\|suppliers\|tenders\|sectors}/<id>` (tender: `award_id`) |
+| `sectors`, `suppliers [--limit]`, `buyers [--limit]` | `GET /api/v1/{sectors\|suppliers\|buyers}` |
+| `lists ls\|create\|show\|add\|rm\|rename\|delete` | `/api/v1/lists*` |
+| `saved-searches ls\|save\|show\|rename\|delete` | `/api/v1/saved-searches*` |
+| `export [filters] [-o file]` | `GET /api/v1/awards.csv` |
+| `price` | `GET /api/v1/price` (no auth) |
+| `pay [--token --customer]` | `POST /api/v1/pay` |
+
+`--format table|json|csv` (default `table`; `--json` = `--format json`). Run
+`selltostate <command> --help` for the flags of one command.
+
+## Exit codes
+
+`0` success · `1` error · `2` unauthorized (401) · `3` payment required (402) · `4` rate limited (429) · `64` usage error
+
+## Development
+
+This package lives in the `data-atlas` monorepo next to `packages/cli`. Keep both in lockstep.
+
+```bash
+python -m unittest discover -s tests   # no network; compares --help with packages/cli/dist when it is built
+uv build                               # dist/selltostate_cli-<version>-py3-none-any.whl
+```

selltostate_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+selltostate_cli.py,sha256=X2O5VxQx2WbvnvC3g6fUVUpwYpcNCCB5i3Y2ED923kM,41344
+selltostate_cli-0.1.0.dist-info/METADATA,sha256=3nUwAPMVkTmcQCeXQD_BF8RRd3j4IMxxNEi3znfPd0Y,2994
+selltostate_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+selltostate_cli-0.1.0.dist-info/entry_points.txt,sha256=BOJDddCUFfm1Sq8A0Qgcfj9ZXFXYps95qqqEwyy873I,53
+selltostate_cli-0.1.0.dist-info/top_level.txt,sha256=8DjHuPhMtnBhTay8BnDtfHBICUxZmcvC9PXZbafJsFw,16
+selltostate_cli-0.1.0.dist-info/RECORD,,

selltostate_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

selltostate_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+selltostate = selltostate_cli:main

selltostate_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+selltostate_cli

selltostate_cli.py

@@ -0,0 +1,1088 @@
+"""selltostate: official CLI for the Sell to State government-contracts data API.
+
+Python port of packages/cli (npm @selltostate/cli). Same commands, flags, output
+and exit codes; stdlib only. Every data command maps 1:1 to a REST /api/v1
+endpoint and sends the dashboard key as x-api-key. A 402 prints the agent-native
+payment_link; a 401 points at `auth login`. Keep in lockstep with packages/cli.
+"""
+
+from __future__ import annotations
+
+import getpass
+import json
+import math
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+VERSION = "0.1.0"
+BIN = "selltostate"
+DEFAULT_API_URL = "https://app.selltostate.com"
+
+# Exit codes (same as the npm CLI).
+EXIT_ERROR, EXIT_UNAUTHORIZED, EXIT_PAYMENT, EXIT_RATE_LIMIT, EXIT_USAGE = 1, 2, 3, 4, 64
+
+
+class Exit(Exception):
+    """Raised to end the command with an exit code (main() turns it into sys.exit)."""
+
+    def __init__(self, code: int):
+        super().__init__(code)
+        self.code = code
+
+
+# ── Output ───────────────────────────────────────────────────────────────────
+def out(data) -> None:
+    s = data if isinstance(data, str) else dumps(data)
+    sys.stdout.write(s if s.endswith("\n") else s + "\n")
+
+
+def err(message: str) -> None:
+    sys.stderr.write(f"{BIN}: {message}\n")
+
+
+def dumps(data) -> str:
+    """JSON.stringify(data, null, 2)."""
+    return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+# ── Config (flag -> env -> ~/.config/selltostate/config.json -> default) ─────
+def config_dir() -> str:
+    xdg = (os.environ.get("XDG_CONFIG_HOME") or "").strip()
+    return os.path.join(xdg or os.path.join(os.path.expanduser("~"), ".config"), "selltostate")
+
+
+def config_path() -> str:
+    return os.path.join(config_dir(), "config.json")
+
+
+def read_stored_config() -> dict:
+    try:
+        with open(config_path(), encoding="utf-8") as f:
+            parsed = json.load(f)
+        return parsed if isinstance(parsed, dict) else {}
+    except (OSError, ValueError):
+        # A missing or corrupt config file must never crash the CLI.
+        return {}
+
+
+def write_stored_config(patch: dict) -> dict:
+    """Merge patch into the config file. It holds the API key: file 0600, dir 0700."""
+    d = config_dir()
+    os.makedirs(d, exist_ok=True)
+    try:
+        os.chmod(d, 0o700)
+    except OSError:
+        pass
+    merged = {**read_stored_config(), **patch}
+    merged = {k: v for k, v in merged.items() if v}
+    path = config_path()
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(json.dumps(merged, indent=2) + "\n")
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+    return merged
+
+
+def resolve_config(api_key: str | None = None, api_url: str | None = None) -> dict:
+    stored = read_stored_config()
+    key, key_src = None, "none"
+    for value, src in ((api_key, "flag"), (os.environ.get("STS_API_KEY"), "env"), (stored.get("apiKey"), "file")):
+        if value:
+            key, key_src = value, src
+            break
+    url, url_src = DEFAULT_API_URL, "default"
+    for value, src in ((api_url, "flag"), (os.environ.get("STS_API_URL"), "env"), (stored.get("apiUrl"), "file")):
+        if value:
+            url, url_src = value, src
+            break
+    return {
+        "apiUrl": url.strip().rstrip("/"),
+        "apiKey": (key or "").strip() or None,
+        "source": {"apiKey": key_src, "apiUrl": url_src},
+    }
+
+
+# ── REST client ──────────────────────────────────────────────────────────────
+class ApiError(Exception):
+    """A non-2xx response, with the parsed body when JSON."""
+
+    def __init__(self, status: int, message: str, body=None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+def _query_value(v) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, float) and v.is_integer():
+        return str(int(v))
+    return str(v)
+
+
+def build_query(query: dict | None) -> str:
+    pairs = []
+    for key, value in (query or {}).items():
+        for v in value if isinstance(value, list) else [value]:
+            if v is None or v == "":
+                continue
+            pairs.append((key, _query_value(v)))
+    return "?" + urllib.parse.urlencode(pairs) if pairs else ""
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):  # noqa: D401 - urllib hook
+        return None
+
+
+def _default_open(req: urllib.request.Request, follow: bool):
+    opener = urllib.request.build_opener() if follow else urllib.request.build_opener(_NoRedirect)
+    return opener.open(req, timeout=60)
+
+
+def _quote(segment: str) -> str:
+    """encodeURIComponent."""
+    return urllib.parse.quote(str(segment), safe="!'()*-._~")
+
+
+class ApiClient:
+    """One method per documented machine endpoint. `opener(req, follow)` is injectable for tests."""
+
+    def __init__(self, api_url: str, api_key: str | None, user_agent: str = "selltostate-cli", opener=None):
+        self.api_url = (api_url or DEFAULT_API_URL).rstrip("/")
+        self.api_key = api_key
+        self.user_agent = user_agent
+        self.opener = opener or _default_open
+
+    def request(self, method: str, path: str, query=None, body=None, raw_text=False, no_follow=False):
+        url = f"{self.api_url}{path}{build_query(query)}"
+        headers = {"accept": "application/json", "user-agent": self.user_agent}
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        data = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            data = json.dumps(body).encode()
+        req = urllib.request.Request(url, data=data, method=method, headers=headers)
+
+        try:
+            res = self.opener(req, not no_follow)
+            try:
+                status, res_headers, payload = res.status, res.headers, res.read()
+            finally:
+                getattr(res, "close", lambda: None)()
+        except urllib.error.HTTPError as e:
+            with e:
+                status, res_headers, payload = e.code, e.headers, e.read()
+        except (urllib.error.URLError, OSError) as e:
+            raise RuntimeError(f"network error talking to {url}: {getattr(e, 'reason', e)}") from e
+
+        # The awards.csv route redirects to /checkout (no subscription) or /auth
+        # (bad key). Map it to the same 402/401 contract the JSON endpoints use,
+        # so the CSV file never gets an HTML login page.
+        if no_follow and 300 <= status < 400:
+            location = res_headers.get("location") or ""
+            code = 401 if re.search(r"/auth\b", location) else 402
+            message = (
+                "export requires a valid API key (redirected to /auth)"
+                if code == 401
+                else "export requires an active subscription (redirected to /checkout)"
+            )
+            raise ApiError(code, message, {"error": "unauthorized" if code == 401 else "payment_required", "redirect": location})
+
+        text = payload.decode("utf-8", errors="replace")
+        is_json = "application/json" in (res_headers.get("content-type") or "")
+
+        if not 200 <= status < 300:
+            parsed = text
+            if is_json:
+                try:
+                    parsed = json.loads(text)
+                except ValueError:
+                    pass
+            message = parsed.get("error") if isinstance(parsed, dict) and parsed.get("error") else f"{method} {path} -> {status}"
+            raise ApiError(status, str(message), parsed)
+
+        if raw_text:
+            return text
+        if status == 204:
+            return None
+        return json.loads(text) if is_json and text else text
+
+    # Identity, pricing, payment
+    def whoami(self):
+        return self.request("GET", "/api/v1/whoami")
+
+    def price(self):
+        return self.request("GET", "/api/v1/price")
+
+    def pay(self, body=None):
+        return self.request("POST", "/api/v1/pay", body=body or {})
+
+    # Search and awards
+    def search(self, query):
+        return self.request("GET", "/api/v1/search", query=query)
+
+    def awards(self, query):
+        return self.request("GET", "/api/v1/awards", query=query)
+
+    def awards_csv(self, query):
+        return self.request("GET", "/api/v1/awards.csv", query=query, raw_text=True, no_follow=True)
+
+    # Reference lists
+    def sectors(self):
+        return self.request("GET", "/api/v1/sectors")
+
+    def suppliers(self, query=None):
+        return self.request("GET", "/api/v1/suppliers", query=query)
+
+    def buyers(self, query=None):
+        return self.request("GET", "/api/v1/buyers", query=query)
+
+    # Entity detail
+    def get_buyer(self, slug, query=None):
+        return self.request("GET", f"/api/v1/buyers/{_quote(slug)}", query=query)
+
+    def get_supplier(self, slug, query=None):
+        return self.request("GET", f"/api/v1/suppliers/{_quote(slug)}", query=query)
+
+    def get_tender(self, tender_id):
+        return self.request("GET", f"/api/v1/tenders/{_quote(tender_id)}")
+
+    def get_sector(self, slug, query=None):
+        return self.request("GET", f"/api/v1/sectors/{_quote(slug)}", query=query)
+
+    # Lists (owner-scoped, x-api-key only)
+    def list_lists(self):
+        return self.request("GET", "/api/v1/lists")
+
+    def get_list(self, list_id, query=None):
+        return self.request("GET", f"/api/v1/lists/{_quote(list_id)}", query=query)
+
+    def create_list(self, name):
+        return self.request("POST", "/api/v1/lists", body={"name": name})
+
+    def rename_list(self, list_id, name):
+        return self.request("PATCH", f"/api/v1/lists/{_quote(list_id)}", body={"name": name})
+
+    def delete_list(self, list_id):
+        return self.request("DELETE", f"/api/v1/lists/{_quote(list_id)}")
+
+    def add_list_item(self, list_id, item):
+        return self.request("POST", f"/api/v1/lists/{_quote(list_id)}/items", body=item)
+
+    def remove_list_item(self, list_id, tender_no):
+        return self.request("DELETE", f"/api/v1/lists/{_quote(list_id)}/items", body={"tender_no": tender_no})
+
+    # Saved searches
+    def list_saved_searches(self):
+        return self.request("GET", "/api/v1/saved-searches")
+
+    def get_saved_search(self, search_id):
+        return self.request("GET", f"/api/v1/saved-searches/{_quote(search_id)}")
+
+    def create_saved_search(self, body):
+        return self.request("POST", "/api/v1/saved-searches", body=body)
+
+    def rename_saved_search(self, search_id, name):
+        return self.request("PATCH", f"/api/v1/saved-searches/{_quote(search_id)}", body={"name": name})
+
+    def delete_saved_search(self, search_id):
+        return self.request("DELETE", f"/api/v1/saved-searches/{_quote(search_id)}")
+
+
+# ── Format (table | json | csv) ──────────────────────────────────────────────
+def parse_format(raw: str | None, json_flag: bool) -> str:
+    if json_flag:
+        return "json"
+    if raw is None:
+        return "table"
+    v = raw.strip().lower()
+    if v in ("json", "table", "csv"):
+        return v
+    raise ValueError(f'invalid --format "{raw}" (expected: table | json | csv)')
+
+
+def col(key, label=None, render=None):
+    return (key, label or key, render)
+
+
+def _js_string(v) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, float) and v.is_integer():
+        return str(int(v))
+    return str(v)
+
+
+def _cell(row: dict, column) -> str:
+    key, _, render = column
+    raw = row.get(key)
+    if render:
+        return render(raw)
+    if raw is None:
+        return ""
+    if isinstance(raw, (dict, list)):
+        return json.dumps(raw, separators=(",", ":"), ensure_ascii=False)
+    return _js_string(raw)
+
+
+def num(value) -> str:
+    """toLocaleString("en-US"): thousands separators, up to 3 decimals."""
+    if value is None or value == "":
+        return ""
+    try:
+        n = float(value)
+    except (TypeError, ValueError):
+        return str(value)
+    if not math.isfinite(n):
+        return str(value)
+    if n.is_integer():
+        return f"{int(n):,}"
+    return f"{n:,.3f}".rstrip("0").rstrip(".")
+
+
+def truncate(value, max_len: int) -> str:
+    s = "" if value is None else _js_string(value)
+    return s[: max_len - 1] + "…" if len(s) > max_len else s
+
+
+def render_table(rows: list, columns: list) -> str:
+    if not rows:
+        return "(no rows)"
+    headers = [c[1] for c in columns]
+    matrix = [[_cell(r, c) for c in columns] for r in rows]
+    widths = [max([len(headers[i])] + [len(m[i]) for m in matrix]) for i in range(len(columns))]
+    lines = [" | ".join(h.ljust(widths[i]) for i, h in enumerate(headers)), "-+-".join("-" * w for w in widths)]
+    lines += [" | ".join(c.ljust(widths[i]) for i, c in enumerate(m)) for m in matrix]
+    return "\n".join(lines)
+
+
+def _csv_escape(value: str) -> str:
+    return '"' + value.replace('"', '""') + '"' if re.search(r'[",\r\n]', value) else value
+
+
+def render_csv(rows: list, columns: list) -> str:
+    header = ",".join(_csv_escape(c[1]) for c in columns)
+    body = "\n".join(",".join(_csv_escape(_cell(r, c)) for c in columns) for r in rows)
+    return f"{header}\n{body}\n" if rows else f"{header}\n"
+
+
+def render_tabular(fmt: str, rows: list, columns: list, raw) -> str:
+    if fmt == "json":
+        return dumps(raw)
+    if fmt == "csv":
+        return render_csv(rows, columns)
+    return render_table(rows, columns)
+
+
+# ── Args ─────────────────────────────────────────────────────────────────────
+BOOLEAN_FLAGS = {"help", "version", "json", "yes", "quiet"}
+SHORT_VALUE_FLAGS = {"o": "output"}
+
+
+def parse_args(argv: list) -> tuple:
+    """Positionals + flags: `--flag value`, `--flag=value`, boolean `--flag`, `-o value`, `-h`, `--`."""
+    positionals, flags = [], {}
+    i = 0
+    while i < len(argv):
+        tok = argv[i]
+        nxt = argv[i + 1] if i + 1 < len(argv) else None
+        if tok == "--":
+            positionals += argv[i + 1 :]
+            break
+        if tok.startswith("--"):
+            if "=" in tok:
+                name, value = tok[2:].split("=", 1)
+                flags[name] = value
+            elif tok[2:] in BOOLEAN_FLAGS or nxt is None or nxt.startswith("-"):
+                flags[tok[2:]] = True
+            else:
+                flags[tok[2:]] = nxt
+                i += 1
+        elif tok.startswith("-") and len(tok) > 1:
+            short = tok[1:]
+            if short == "h":
+                flags["help"] = True
+            elif short == "v":
+                flags["version"] = True
+            elif short in SHORT_VALUE_FLAGS:
+                if nxt is not None and not nxt.startswith("-"):
+                    flags[SHORT_VALUE_FLAGS[short]] = nxt
+                    i += 1
+                else:
+                    flags[SHORT_VALUE_FLAGS[short]] = True
+            else:
+                flags[short] = True
+        else:
+            positionals.append(tok)
+        i += 1
+    return positionals, flags
+
+
+def flag_str(flags: dict, *names):
+    for n in names:
+        if isinstance(flags.get(n), str):
+            return flags[n]
+    return None
+
+
+def flag_bool(flags: dict, *names) -> bool:
+    return any(flags.get(n) is True or flags.get(n) == "true" for n in names)
+
+
+def flag_num(flags: dict, *names):
+    s = flag_str(flags, *names)
+    if s is None:
+        return None
+    try:
+        n = float(s.strip() or "0")
+    except ValueError:
+        return None
+    return n if math.isfinite(n) else None
+
+
+def flag_list(flags: dict, *names) -> list:
+    v = flag_str(flags, *names)
+    return [s.strip() for s in v.split(",") if s.strip()] if v else []
+
+
+# ── Shared command plumbing ──────────────────────────────────────────────────
+def client_for(cfg: dict) -> ApiClient:
+    return ApiClient(cfg["apiUrl"], cfg["apiKey"], user_agent=f"{BIN}/{VERSION}")
+
+
+def require_credential(cfg: dict) -> None:
+    if not cfg["apiKey"]:
+        err(f"no API key configured. Run `{BIN} auth login`, set STS_API_KEY, or pass --api-key.")
+        raise Exit(EXIT_UNAUTHORIZED)
+
+
+def explain_api_error(e: Exception):
+    """Map an ApiError to a hint + exit code. Always raises Exit."""
+    if isinstance(e, ApiError):
+        if e.status == 401:
+            err(f"unauthorized — run `{BIN} auth login` to set a valid API key.")
+            raise Exit(EXIT_UNAUTHORIZED)
+        if e.status == 402:
+            body = e.body if isinstance(e.body, dict) else {}
+            err("payment required — no active subscription.")
+            if body.get("price"):
+                err(f"price: {body['price']}" + (f" {body['currency']}" if body.get("currency") else ""))
+            if body.get("payment_link"):
+                err(f"pay (human): {body['payment_link']}")
+            endpoint = (body.get("machine_payment") or {}).get("endpoint")
+            if endpoint:
+                err(f"pay (agent): POST {endpoint}")
+            err(f"or run `{BIN} pay` to activate.")
+            raise Exit(EXIT_PAYMENT)
+        if e.status == 429:
+            err("rate limited (429) — slow down and retry.")
+            raise Exit(EXIT_RATE_LIMIT)
+        err(f"API error {e.status}: {e}")
+        raise Exit(EXIT_ERROR)
+    err(str(e))
+    raise Exit(EXIT_ERROR)
+
+
+def call(fn, *args):
+    try:
+        return fn(*args)
+    except (ApiError, RuntimeError) as e:
+        explain_api_error(e)
+
+
+def fmt_of(flags: dict, default: str | None = None) -> str:
+    return parse_format(flag_str(flags, "format") or default, flag_bool(flags, "json"))
+
+
+def usage_error(group: str, form: str):
+    err(f"usage: {BIN} {group} {form}")
+    raise Exit(EXIT_USAGE)
+
+
+def pick(obj: dict, keys: list) -> str:
+    for k in keys:
+        v = obj.get(k)
+        if v is not None and v != "":
+            return json.dumps(v, separators=(",", ":")) if isinstance(v, (dict, list)) else _js_string(v)
+    return ""
+
+
+PARTNER_COLUMNS = [
+    col("name", "name", lambda v: truncate(v, 40)),
+    col("slug"),
+    col("total", "total", num),
+    col("count", "count", num),
+]
+
+AWARD_COLUMNS = [
+    col("tender_no"),
+    col("supplier", "supplier", lambda v: truncate(v, 30)),
+    col("agency", "agency", lambda v: truncate(v, 30)),
+    col("category", "category", lambda v: truncate(v, 20)),
+    col("awarded_amt", "awarded_amt", num),
+    col("published_at"),
+    col("awarded_at"),
+]
+
+LISTS_COLUMNS = [
+    col("id"),
+    col("name", "name", lambda v: truncate(v, 40)),
+    col("itemCount", "tenders", num),
+    col("buyerCount", "buyers", num),
+    col("supplierCount", "suppliers", num),
+]
+
+
+# ── Commands ─────────────────────────────────────────────────────────────────
+WHOAMI_USAGE = """selltostate whoami — show the authenticated subject, plan, scopes and export cap
+
+Usage: selltostate whoami [--format table|json|csv]
+
+Calls GET /api/v1/whoami. A valid-but-unentitled key returns active:false
+(pay to unlock) rather than an error; a missing/invalid key is a 401."""
+
+
+def cmd_whoami(pos, flags, cfg):
+    require_credential(cfg)
+    fmt = fmt_of(flags)
+    me = call(client_for(cfg).whoami)
+    if not (flag_bool(flags, "json") or flag_str(flags, "format") is not None):
+        state = "active" if me.get("active") else f"inactive — run `{BIN} pay` to unlock"
+        out(
+            "\n".join(
+                [
+                    f"subject:    {me.get('subject')}",
+                    f"type:       {me.get('type')}",
+                    f"plan:       {me.get('plan') or '—'}",
+                    f"status:     {state}",
+                    f"scopes:     {', '.join(me.get('scopes') or []) or '—'}",
+                    f"export cap: {_js_string(me.get('export_cap'))}",
+                ]
+            )
+        )
+        return
+    row = {
+        "subject": me.get("subject"),
+        "type": me.get("type"),
+        "active": me.get("active"),
+        "plan": me.get("plan") or "",
+        "scopes": " ".join(me.get("scopes") or []),
+        "export_cap": me.get("export_cap"),
+    }
+    out(render_tabular(fmt, [row], [col(k) for k in row], me))
+
+
+SEARCH_USAGE = """selltostate search <query> [options] — faceted search across tenders/awards
+
+Usage: selltostate search <query> [options]
+
+Options:
+  --scope <name>        Collection: tenders (default) | awards | …
+  --sector <s>          Sector slug (comma-separated for multiple)
+  --country <c>         Country filter
+  --type <t>            Procurement type
+  --status <s>          Status filter
+  --year-min <n>        Lower bound on year
+  --year-max <n>        Upper bound on year
+  --amount-min <n>      Lower bound on amount
+  --amount-max <n>      Upper bound on amount
+  --page <n>            Page number (default 1)
+  --per-page <n>        Results per page (1–50, default 25)
+  --format <fmt>        table (default) | json | csv
+
+Calls GET /api/v1/search."""
+
+
+def cmd_search(pos, flags, cfg):
+    require_credential(cfg)
+    fmt = fmt_of(flags)
+    query = {
+        "q": pos[0] if pos else flag_str(flags, "q") or "",
+        "scope": flag_str(flags, "scope"),
+        "sector": flag_list(flags, "sector"),
+        "country": flag_str(flags, "country"),
+        "type": flag_str(flags, "type"),
+        "status": flag_str(flags, "status"),
+        "year_min": flag_num(flags, "year-min"),
+        "year_max": flag_num(flags, "year-max"),
+        "amount_min": flag_num(flags, "amount-min"),
+        "amount_max": flag_num(flags, "amount-max"),
+        "page": flag_num(flags, "page"),
+        "per_page": flag_num(flags, "per-page"),
+    }
+    res = call(client_for(cfg).search, query)
+    if fmt == "json":
+        return out(dumps(res))
+    body = res if isinstance(res, dict) else {}
+    hits = body.get("hits") if isinstance(body.get("hits"), list) else []
+    rows = [
+        {
+            "id": pick(h, ["tender_no", "id", "award_id", "slug"]),
+            "title": truncate(pick(h, ["title", "name", "description"]), 60),
+            "buyer": pick(h, ["buyer", "agency", "buyer_name"]),
+            "supplier": pick(h, ["supplier", "supplier_name"]),
+            "amount": num(pick(h, ["amount", "awarded_amt", "value"])),
+            "year": pick(h, ["year"]),
+        }
+        for h in hits
+    ]
+    out(render_tabular(fmt, rows, [col(k) for k in ("id", "title", "buyer", "supplier", "amount", "year")], res))
+    if fmt != "csv":
+        found = body.get("found", len(hits))
+        out(f"\nfound {_js_string(found)}, page {_js_string(body.get('page') or 1)} × {_js_string(body.get('per_page') or len(hits))}")
+
+
+AWARDS_USAGE = """selltostate awards [options] — list awarded tenders (the explorer dataset)
+
+Usage: selltostate awards [options]
+
+Options:
+  --q <text>            Free-text filter
+  --agency <name>       Buyer / agency filter
+  --supplier <name>     Supplier filter
+  --category <name>     Category filter
+  --country <slug>      Country slug (default singapore)
+  --year <n>            Award year
+  --amount-min <n>      Minimum awarded amount
+  --amount-max <n>      Maximum awarded amount
+  --page <n>            Page number (default 1)
+  --per-page <n>        Rows per page (server-capped by your plan)
+  --format <fmt>        table (default) | json | csv
+
+Calls GET /api/v1/awards. For a bulk CSV export use `selltostate export`."""
+
+
+def awards_query(flags: dict) -> dict:
+    return {
+        "q": flag_str(flags, "q"),
+        "agency": flag_str(flags, "agency"),
+        "supplier": flag_str(flags, "supplier"),
+        "category": flag_str(flags, "category"),
+        "country": flag_str(flags, "country"),
+        "year": flag_num(flags, "year"),
+        "amount_min": flag_num(flags, "amount-min"),
+        "amount_max": flag_num(flags, "amount-max"),
+        "page": flag_num(flags, "page"),
+        "page_size": flag_num(flags, "per-page"),
+    }
+
+
+def cmd_awards(pos, flags, cfg):
+    require_credential(cfg)
+    fmt = fmt_of(flags)
+    res = call(client_for(cfg).awards, awards_query(flags))
+    if fmt == "json":
+        return out(dumps(res))
+    body = res if isinstance(res, dict) else {}
+    rows = body.get("rows") if isinstance(body.get("rows"), list) else []
+    out(render_tabular(fmt, rows, AWARD_COLUMNS, res))
+    if fmt != "csv":
+        total = body.get("total", len(rows))
+        cap = body.get("export_cap")
+        out(f"\n{len(rows)} rows (page {_js_string(body.get('page') or 1)}, {_js_string(total)} total, export cap {'—' if cap is None else _js_string(cap)})")
+
+
+GET_USAGE = """selltostate get <kind> <slug-or-id> [options] — fetch one entity in detail
+
+Usage: selltostate get buyer|supplier|tender|sector <slug-or-id> [options]
+
+Options:
+  --page <n>            Partner-table page (buyer/supplier/sector)
+  --kind <buyers|suppliers>  Sector partner table to return (sector only)
+  --format <fmt>        json (default) | table | csv  (table/csv = partner table)
+
+Calls GET /api/v1/{buyers|suppliers|tenders|sectors}/<id>. A missing entity is a 404."""
+
+
+def cmd_get(pos, flags, cfg):
+    require_credential(cfg)
+    kind = pos[0] if pos else None
+    if kind not in ("buyer", "supplier", "tender", "sector"):
+        err(f"unknown entity kind: {kind or '(none)'}. Expected: buyer | supplier | tender | sector")
+        raise Exit(EXIT_USAGE)
+    if len(pos) < 2:
+        err(f"missing <slug-or-id>. Usage: selltostate get {kind} <slug-or-id>")
+        raise Exit(EXIT_USAGE)
+    ident = pos[1]
+    fmt = fmt_of(flags, "json")
+    page = flag_num(flags, "page")
+    client = client_for(cfg)
+    if kind == "buyer":
+        res, partner_key = call(client.get_buyer, ident, {"sup_page": page} if page else None), "suppliers"
+    elif kind == "supplier":
+        res, partner_key = call(client.get_supplier, ident, {"buyer_page": page} if page else None), "buyers"
+    elif kind == "sector":
+        sector_kind = "suppliers" if flag_str(flags, "kind") == "suppliers" else "buyers"
+        res, partner_key = call(client.get_sector, ident, {"kind": sector_kind, "page": page}), "partners"
+    else:
+        res, partner_key = call(client.get_tender, ident), ""
+    if fmt == "json":
+        return out(dumps(res))
+    if not partner_key:
+        err("note: tender detail has no flat partner table; emitting JSON.")
+        return out(dumps(res))
+    block = res.get(partner_key) if isinstance(res, dict) else None
+    rows = block.get("rows") if isinstance(block, dict) and isinstance(block.get("rows"), list) else []
+    out(render_tabular(fmt, rows, PARTNER_COLUMNS, res))
+
+
+LISTS_USAGE = """selltostate lists <subcommand> — manage saved lists
+
+Subcommands:
+  ls                         List every list you own (tender, buyer and supplier counts)
+  create <name>              Create a new list
+  show <id>                  Show a list + its items (--page, --per-page)
+  add <id> <tender_no>       Add an award (or --award-id <id>) to a list
+  rm <id> <tender_no>        Remove an item from a list
+  rename <id> <name>         Rename a list
+  delete <id>                Delete a list
+
+Options: --format table|json|csv
+
+Calls /api/v1/lists*. Requires a dashboard API key (x-api-key)."""
+
+
+def format_lists(res, fmt: str) -> str:
+    if fmt == "json":
+        return dumps(res)
+    lists = (res.get("lists") or []) if isinstance(res, dict) else []
+    return render_tabular(fmt, lists, LISTS_COLUMNS, res)
+
+
+def cmd_lists(pos, flags, cfg):
+    require_credential(cfg)
+    sub, rest = (pos[0] if pos else "ls"), pos[1:]
+    fmt = fmt_of(flags)
+    client = client_for(cfg)
+    if sub == "ls":
+        return out(format_lists(call(client.list_lists), fmt))
+    if sub == "create":
+        name = " ".join(rest).strip()
+        if not name:
+            usage_error("lists", "create <name>")
+        return out(dumps(call(client.create_list, name)))
+    if sub == "show":
+        if not rest:
+            usage_error("lists", "show <id>")
+        res = call(client.get_list, rest[0], {"page": flag_num(flags, "page"), "page_size": flag_num(flags, "per-page")})
+        if fmt == "json":
+            return out(dumps(res))
+        body = res if isinstance(res, dict) else {}
+        items = body.get("items") if isinstance(body.get("items"), list) else []
+        columns = [
+            col("tender_no"),
+            col("supplier", "supplier", lambda v: truncate(v, 30)),
+            col("agency", "agency", lambda v: truncate(v, 30)),
+            col("awarded_amt", "awarded_amt", num),
+        ]
+        table = render_tabular(fmt, items, columns, res)
+        if fmt == "csv":
+            return out(table)
+        out(f"# {(body.get('list') or {}).get('name') or '(list)'}")
+        out(table)
+        return out(f"\n{len(items)} items (page {_js_string(body.get('page') or 1)}, {_js_string(body.get('total', len(items)))} total)")
+    if sub == "add":
+        if not rest:
+            usage_error("lists", "add <id> <tender_no|--award-id ID>")
+        award_id = flag_str(flags, "award-id")
+        tender_no = rest[1] if len(rest) > 1 else None
+        if not tender_no and not award_id:
+            usage_error("lists", "add <id> <tender_no> (or --award-id ID)")
+        item = {"tender_no": tender_no} if tender_no else {"award_id": award_id}
+        return out(dumps(call(client.add_list_item, rest[0], item)))
+    if sub == "rm":
+        if len(rest) < 2:
+            usage_error("lists", "rm <id> <tender_no>")
+        return out(dumps(call(client.remove_list_item, rest[0], rest[1])))
+    if sub == "rename":
+        name = " ".join(rest[1:]).strip()
+        if not rest or not name:
+            usage_error("lists", "rename <id> <name>")
+        return out(dumps(call(client.rename_list, rest[0], name)))
+    if sub == "delete":
+        if not rest:
+            usage_error("lists", "delete <id>")
+        return out(dumps(call(client.delete_list, rest[0])))
+    err(f"unknown lists subcommand: {sub}. Try: ls | create | show | add | rm | rename | delete")
+    raise Exit(EXIT_USAGE)
+
+
+SAVED_SEARCHES_USAGE = """selltostate saved-searches <subcommand> — manage saved searches
+
+Subcommands:
+  ls                         List every saved search you can see
+  save <name> [--query JSON] [--kind atlas]   Save a search
+  show <id>                  Show one saved search
+  rename <id> <name>         Rename a saved search
+  delete <id>                Delete a saved search
+
+Options: --format table|json|csv
+
+Calls /api/v1/saved-searches*. Requires a dashboard API key (x-api-key)."""
+
+
+def cmd_saved_searches(pos, flags, cfg):
+    require_credential(cfg)
+    sub, rest = (pos[0] if pos else "ls"), pos[1:]
+    fmt = fmt_of(flags)
+    client = client_for(cfg)
+    if sub == "ls":
+        res = call(client.list_saved_searches)
+        if fmt == "json":
+            return out(dumps(res))
+        searches = (res.get("searches") or []) if isinstance(res, dict) else []
+        return out(render_tabular(fmt, searches, [col("id"), col("name", "name", lambda v: truncate(v, 50))], res))
+    if sub == "save":
+        name = " ".join(rest).strip()
+        if not name:
+            usage_error("saved-searches", "save <name> [--query JSON] [--kind atlas]")
+        query_raw = flag_str(flags, "query")
+        query = {}
+        if query_raw:
+            try:
+                query = json.loads(query_raw)
+            except ValueError:
+                err(f"--query must be valid JSON (got: {query_raw})")
+                raise Exit(EXIT_USAGE)
+        body = {"name": name, "query": query}
+        if flag_str(flags, "kind"):
+            body["kind"] = flag_str(flags, "kind")
+        return out(dumps(call(client.create_saved_search, body)))
+    if sub == "show":
+        if not rest:
+            usage_error("saved-searches", "show <id>")
+        return out(dumps(call(client.get_saved_search, rest[0])))
+    if sub == "rename":
+        name = " ".join(rest[1:]).strip()
+        if not rest or not name:
+            usage_error("saved-searches", "rename <id> <name>")
+        return out(dumps(call(client.rename_saved_search, rest[0], name)))
+    if sub == "delete":
+        if not rest:
+            usage_error("saved-searches", "delete <id>")
+        return out(dumps(call(client.delete_saved_search, rest[0])))
+    err(f"unknown saved-searches subcommand: {sub}. Try: ls | save | show | rename | delete")
+    raise Exit(EXIT_USAGE)
+
+
+EXPORT_USAGE = """selltostate export [filters] [-o file.csv] — export awards as CSV
+
+Usage: selltostate export [options] [-o|--output FILE]
+
+Filters (same as `awards`):
+  --q <text>            Free-text filter
+  --agency <name>       Buyer / agency filter
+  --supplier <name>     Supplier filter
+  --category <name>     Category filter
+  --country <slug>      Country slug (default singapore)
+  --year <n>            Award year
+  --amount-min <n>      Minimum awarded amount
+  --amount-max <n>      Maximum awarded amount
+
+Output:
+  -o, --output <file>   Write CSV to <file> (default: stdout)
+
+Calls GET /api/v1/awards.csv. Row count is capped by your plan (paid 5000 / trial 20)."""
+
+
+def cmd_export(pos, flags, cfg):
+    require_credential(cfg)
+    output = flag_str(flags, "output", "o")
+    csv_text = call(client_for(cfg).awards_csv, awards_query(flags))
+    if not output:
+        sys.stdout.write(csv_text)
+        return
+    try:
+        with open(output, "w", encoding="utf-8", newline="") as f:
+            f.write(csv_text)
+    except OSError as e:
+        err(f"could not write {output}: {e}")
+        raise Exit(EXIT_ERROR)
+    trimmed = csv_text.rstrip("\n")
+    err(f"wrote {max(0, len(trimmed.split(chr(10))) - 1) if trimmed else 0} rows to {output}")
+
+
+def _reference(method: str, columns=None):
+    def handler(pos, flags, cfg):
+        require_credential(cfg)
+        fmt = fmt_of(flags)
+        limit = flag_num(flags, "limit")
+        fn = getattr(client_for(cfg), method)
+        res = call(fn) if method == "sectors" else call(fn, {"limit": limit} if limit else None)
+        if fmt == "json":
+            return out(dumps(res))
+        rows = (res.get("rows") or []) if isinstance(res, dict) else []
+        out(render_tabular(fmt, rows, columns or PARTNER_COLUMNS, res))
+
+    return handler
+
+
+def cmd_price(pos, flags, cfg):
+    # price is public: no credential check.
+    out(dumps(call(client_for(cfg).price)))
+
+
+def cmd_pay(pos, flags, cfg):
+    require_credential(cfg)
+    body = {}
+    token = flag_str(flags, "token", "payment-method-token")
+    if token:
+        body["payment_method_token"] = token
+    if flag_str(flags, "customer"):
+        body["customer"] = flag_str(flags, "customer")
+    out(dumps(call(client_for(cfg).pay, body)))
+
+
+# ── auth ─────────────────────────────────────────────────────────────────────
+AUTH_USAGE = """selltostate auth <subcommand> — manage credentials
+
+Subcommands:
+  login [--api-key KEY] [--api-url URL]   Save a key to {path}
+  status                                  Show the resolved credential + source
+  logout                                  Remove the stored API key"""
+
+
+def cmd_auth(pos, flags, cfg):
+    sub = pos[0] if pos else None
+    if sub == "login":
+        api_key = flag_str(flags, "api-key")
+        api_url = flag_str(flags, "api-url")
+        if not api_key:
+            out(f"Get a dashboard API key at {cfg['apiUrl']}/dashboard (Settings → API keys).")
+            api_key = getpass.getpass("API key: ").strip()
+        if not api_key:
+            err("no API key entered.")
+            raise Exit(EXIT_UNAUTHORIZED)
+        stored = write_stored_config({"apiKey": api_key, "apiUrl": api_url if api_url and api_url != DEFAULT_API_URL else None})
+        out(f"Saved API key to {config_path()}")
+        try:
+            me = client_for(resolve_config(stored["apiKey"], api_url)).whoami()
+        except ApiError as e:
+            if e.status == 401:
+                err("warning: the key was saved but /whoami rejected it (401). Double-check the key.")
+            else:
+                err(f"warning: saved the key but could not verify it: {e}")
+            return
+        except RuntimeError as e:
+            err(f"warning: saved the key but could not verify it: {e}")
+            return
+        if me.get("active"):
+            out(f"Authenticated as {me.get('subject')} (plan: {me.get('plan') or '—'}, active).")
+        else:
+            out(f"Authenticated as {me.get('subject')} (inactive — run `{BIN} pay` to unlock data).")
+        return
+    if sub == "status":
+        key = cfg["apiKey"]
+        out(
+            {
+                "api_url": cfg["apiUrl"],
+                "api_url_source": cfg["source"]["apiUrl"],
+                "api_key": f"{key[:4]}…{key[-4:]}" if key else "(none)",
+                "api_key_source": cfg["source"]["apiKey"],
+                "config_file": config_path(),
+            }
+        )
+        return
+    if sub == "logout":
+        write_stored_config({"apiKey": None})
+        out(f"Removed the stored API key from {config_path()}.")
+        return
+    err(f"unknown auth subcommand: {sub or '(none)'}. Try: login | status | logout")
+    raise Exit(EXIT_USAGE)
+
+
+# ── Registry + entry point ───────────────────────────────────────────────────
+COMMANDS = {
+    "auth": ("Manage credentials (login | status | logout)", cmd_auth, AUTH_USAGE),
+    "whoami": ("Show the authenticated subject, plan, scopes and export cap", cmd_whoami, WHOAMI_USAGE),
+    "search": ("Faceted search across tenders/awards (GET /api/v1/search)", cmd_search, SEARCH_USAGE),
+    "awards": ("List awarded tenders (GET /api/v1/awards)", cmd_awards, AWARDS_USAGE),
+    "get": ("Fetch one buyer|supplier|tender|sector in detail (R1)", cmd_get, GET_USAGE),
+    "sectors": ("List the curated sector taxonomy (GET /api/v1/sectors)", _reference("sectors", [col("slug"), col("name")]), None),
+    "suppliers": ("Top suppliers by awarded total (GET /api/v1/suppliers)", _reference("suppliers"), None),
+    "buyers": ("Top buyers by spend (GET /api/v1/buyers)", _reference("buyers"), None),
+    "lists": ("Manage saved lists (ls|create|show|add|rm|rename|delete)", cmd_lists, LISTS_USAGE),
+    "saved-searches": ("Manage saved searches (ls|save|show|rename|delete)", cmd_saved_searches, SAVED_SEARCHES_USAGE),
+    "export": ("Export awards as CSV to stdout or -o file (GET /api/v1/awards.csv)", cmd_export, EXPORT_USAGE),
+    "price": ("Show the live subscription price (GET /api/v1/price)", cmd_price, None),
+    "pay": ("Activate a subscription autonomously (POST /api/v1/pay)", cmd_pay, None),
+}
+
+
+def help_text() -> str:
+    width = max(len(k) for k in COMMANDS)
+    lines = [
+        f"{BIN} v{VERSION} — CLI for the Sell to State government-contracts data API",
+        "",
+        f"Usage: {BIN} <command> [subcommand] [options]",
+        "",
+        "Commands:",
+    ]
+    lines += [f"  {name.ljust(width)}  {summary}" for name, (summary, _, _) in COMMANDS.items()]
+    lines += [
+        "",
+        "Global options:",
+        "  --api-key <key>   API key (else $STS_API_KEY, else stored config)",
+        f"  --api-url <url>   API base URL (default $STS_API_URL or {DEFAULT_API_URL})",
+        "  --format <fmt>    Output format: table | json | csv (where supported)",
+        "  --json            Shorthand for --format json",
+        f"  -h, --help        Show help (per-command: `{BIN} <command> --help`)",
+        "  -v, --version     Show version",
+        "",
+        "Auth:",
+        f"  {BIN} auth login          Save an API key to {config_path()}",
+        f"  {BIN} auth status         Show the resolved credential + its source",
+        "",
+        "Environment: STS_API_KEY, STS_API_URL",
+    ]
+    return "\n".join(lines)
+
+
+def run(argv: list) -> int:
+    pos, flags = parse_args(argv)
+    if flags.get("version"):
+        out(VERSION)
+        return 0
+    if not pos:
+        out(help_text())
+        return 0
+    entry = COMMANDS.get(pos[0])
+    if not entry:
+        err(f"unknown command: {pos[0]}")
+        out(help_text())
+        return EXIT_USAGE
+    _, handler, usage = entry
+    if flags.get("help"):
+        out(usage.replace("{path}", config_path()) if usage else help_text())
+        return 0
+    cfg = resolve_config(flag_str(flags, "api-key"), flag_str(flags, "api-url"))
+    try:
+        handler(pos[1:], flags, cfg)
+    except Exit as e:
+        return e.code
+    except (ValueError, RuntimeError) as e:
+        err(str(e))
+        return EXIT_ERROR
+    return 0
+
+
+def main() -> None:
+    try:
+        sys.exit(run(sys.argv[1:]))
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except BrokenPipeError:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()