thoughtleaders-cli 0.9.7__tar.gz → 0.9.9__tar.gz

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

thoughtleaders_cli-0.9.9/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+# Fast, hermetic checks on every push to main and every PR. These run the
+# mocked unit suite under tests/ — no live API, no credits, fully
+# deterministic. The live CLI tests live in cli-integration.yml.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit-tests:
+    name: Unit tests (mocked) · py${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Matches `requires-python = ">=3.12"`.
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Sync locked dependencies
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+      - name: Run unit tests
+        # tests/ mock the HTTP client (CliRunner + fake get_client), so there
+        # is no network, no API key, and no credit spend.
+        run: uv run --python ${{ matrix.python-version }} --with pytest pytest tests/ -v
+
+  windows-launcher:
+    name: Windows launcher (tl setup windows)
+    # `tl setup windows` writes a tl.cmd that runs the CLI through the signed
+    # python.exe, so the unsigned pipx stub can't be blocked by Smart App
+    # Control. This job proves the wrapper is written and actually launches the
+    # CLI. NOTE: GitHub runners don't have SAC in enforcement, so this verifies
+    # the mechanism, not the block itself — real SAC validation needs a SAC/WDAC
+    # machine. Hermetic: a uv project install is a dev install, so the CLI's
+    # auto-updater no-ops (no network).
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Sync locked dependencies
+        run: uv sync --frozen
+      - name: Install the launcher wrapper
+        run: uv run tl setup windows
+      - name: Wrapper exists and launches the CLI through python
+        shell: pwsh
+        run: |
+          $cmd = "$env:LOCALAPPDATA\Programs\tl-cli\tl.cmd"
+          if (-not (Test-Path $cmd)) { throw "wrapper not written at $cmd" }
+          Get-Content $cmd
+          & $cmd --version
+          if ($LASTEXITCODE -ne 0) { throw "wrapper failed to launch the CLI (exit $LASTEXITCODE)" }

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: thoughtleaders-cli
-Version: 0.9.7
+Version: 0.9.9
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli
@@ -92,6 +92,25 @@ uv tool install thoughtleaders-cli
 pip install thoughtleaders-cli
 ```
 
+#### Windows with Smart App Control / WDAC
+
+The pipx/uv install above creates an **unsigned** launcher stub that Windows
+Smart App Control (and enforced WDAC policies) block — `tl` fails to start with
+a Code Integrity error. Fix it with:
+
+```powershell
+tl setup windows
+```
+
+That drops a small `tl.cmd` on your `PATH` (ahead of the blocked stub) which
+launches the CLI through the already-signed `python.exe`, so it runs cleanly
+under SAC. If `tl` is *already* blocked and won't start, bootstrap it through
+the signed interpreter directly, then reopen your terminal:
+
+```powershell
+& "$env:USERPROFILE\pipx\venvs\thoughtleaders-cli\Scripts\python.exe" -m tl_cli setup windows
+```
+
 Then set up:
 ```bash
 tl auth login          # authenticate with ThoughtLeaders (OAuth2 browser flow, device code, or API key)

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/README.md

@@ -64,6 +64,25 @@ uv tool install thoughtleaders-cli
 pip install thoughtleaders-cli
 ```
 
+#### Windows with Smart App Control / WDAC
+
+The pipx/uv install above creates an **unsigned** launcher stub that Windows
+Smart App Control (and enforced WDAC policies) block — `tl` fails to start with
+a Code Integrity error. Fix it with:
+
+```powershell
+tl setup windows
+```
+
+That drops a small `tl.cmd` on your `PATH` (ahead of the blocked stub) which
+launches the CLI through the already-signed `python.exe`, so it runs cleanly
+under SAC. If `tl` is *already* blocked and won't start, bootstrap it through
+the signed interpreter directly, then reopen your terminal:
+
+```powershell
+& "$env:USERPROFILE\pipx\venvs\thoughtleaders-cli\Scripts\python.exe" -m tl_cli setup windows
+```
+
 Then set up:
 ```bash
 tl auth login          # authenticate with ThoughtLeaders (OAuth2 browser flow, device code, or API key)

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/hooks/scripts/post-usage.sh

@@ -11,7 +11,7 @@ fi
 
 # Check for 402 (insufficient credits)
 if [[ "$OUTPUT" =~ "402" ]] || [[ "$OUTPUT" =~ "Insufficient credits" ]]; then
-  echo "WARN: Credits exhausted. Deposit more at https://app.thoughtleaders.io/settings/billing" >&2
+  echo "WARN: Credits exhausted. Deposit more at https://app.thoughtleaders.io/billing" >&2
   exit 0
 fi
 

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.9.7"
+version = "0.9.9"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/skills/tl/SKILL.md

@@ -61,7 +61,7 @@ Retry after 5 seconds if the server returns a "connection denied" or a "server e
 
 Where possible reference sponsorships, brands, channel by numeric IDs.
 
-In raw SQL, match text case-insensitively with `UPPER(x)` on both sides — never `LOWER(x)`, which misses the indexes and times out. See `references/postgres-schema.md`.
+In raw SQL, match text case-insensitively with `UPPER(x)` on both sides — never `LOWER(x)`, which misses the indexes and times out. This includes channel names (`channel_name`, `common_name`), not just handles and URLs. See `references/postgres-schema.md`.
 
 ## Data Model & Terminology
 

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/skills/tl/references/postgres-schema.md

@@ -8,7 +8,7 @@ Accepted SQL:
 - **SELECT only**, single statement. No DDL/DML/transactions/SET/COPY/MERGE.
 - Functions accepted from an explicit list (aggregates, window, string, JSON, math, date-time, array). Catalog-resolving casts (`::regclass`, `::regprocedure`, …) are not accepted.
 - `LIMIT` and `OFFSET` are optional. Omit them and the server fills in `LIMIT 50 OFFSET 0`. Explicit `LIMIT` must be an integer literal ≤ 10,000. Explicit `OFFSET` ≥ 10,000 is rejected with HTTP 403 (`OFFSET_TOO_DEEP`); paginate with the response's `next_offset`/breadcrumbs instead of jumping deep.
-- **Case-insensitive equality: `UPPER(col) = UPPER('…')` / `UPPER(col) IN (UPPER('…'), …)` — never `LOWER(col)`.** The functional indexes on this database are built on `UPPER(…)` (e.g. channel `url`, `common_name`); a `LOWER(col)` predicate can't use them, seq-scans the 1.3M-row channel table, and dies on statement timeout (504). For substring search use `ILIKE '%…%'` on the bare column instead — that's served by trigram indexes where present (`channel_name`, `slug`).
+- **Case-insensitive equality: `UPPER(col) = UPPER('…')` / `UPPER(col) IN (UPPER('…'), …)` — never `LOWER(col)`.** The case-insensitive functional indexes on this database are built on `UPPER(…)` — on channel `channel_name`, `common_name` and `url`, among others. A `LOWER(col)` predicate can't use them: it seq-scans the 1.3M-row channel table (~20s+) and often dies on statement timeout (504). This holds for channel **names** exactly as it does for handles and URLs — see *Finding a single channel or brand ID* below for the bulk-lookup form. For substring search use `ILIKE '%…%'` on the **bare** column instead — that's served by trigram indexes where present (channel `channel_name`, `slug`; brand `name`, `website`). `LOWER(col) ILIKE '%…%'` is both redundant (`ILIKE` is already case-insensitive) and slow (the trigram index is on the bare column).
 
 ## Core Tables
 
@@ -262,16 +262,19 @@ thoughtleaders_adlink
 
 As a special case, the `tl channels find` and `tl brands find` commands accept a name of the channel / brand (be sure to properly quote them for the shell) and will return the respective ID. Use this instead of constructing SQL for this particular case. The commands will return a list of possible choices
 
-For bulk handle/name lookups in SQL (e.g. resolving a list of YouTube handles against `common_name`), compare case-insensitively with `UPPER(…)` on both sides — that's the form the functional indexes serve:
+For bulk handle/name lookups in SQL (e.g. resolving a list of YouTube handles against `common_name`, or a list of channel names against `channel_name`), compare case-insensitively with `UPPER(…)` on both sides — that's the form the functional indexes serve:
 
 ```sql
 SELECT id, channel_name, common_name
 FROM thoughtleaders_channel
 WHERE UPPER(common_name) IN (UPPER('@TheInfographicsShow'), UPPER('@DrewDirksen'))
+   OR UPPER(channel_name) IN (UPPER('The Infographics Show'), UPPER('Drew Dirksen'))
 LIMIT 100 OFFSET 0
 ```
 
-`LOWER(common_name)` (or `LOWER()` on any indexed column) cannot use those indexes — it seq-scans and times out.
+Wrap **both** sides in `UPPER(…)`. `UPPER(col) IN ('lowercase literal', …)` matches nothing, since the indexed side is upper-cased.
+
+`LOWER(channel_name)`, `LOWER(common_name)` — or `LOWER()` on any indexed column — cannot use those indexes. Every such predicate is a full sequential scan of 1.3M channel rows: ~20s when it survives, a 504 statement timeout when it doesn't. One `OR LOWER(col) IN (…)` branch is enough to force the scan even when every other branch in the `WHERE` is indexed, so do not mix the two forms.
 
 ### Common Join Paths
 

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/src/tl_cli/__init__.py

@@ -1,3 +1,3 @@
 """ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence."""
 
-__version__ = "0.9.7"
+__version__ = "0.9.9"

thoughtleaders_cli-0.9.9/src/tl_cli/__main__.py

@@ -0,0 +1,13 @@
+"""Module entry point for the CLI.
+
+Enables `python -m tl_cli` and serves as the single entry script for the
+PyInstaller-frozen standalone build (see packaging/tl.spec). Invoking the CLI
+through the signed `python.exe` / signed frozen exe is what keeps it runnable
+under Windows Smart App Control, which blocks the unsigned launcher stub that
+pipx/uv generate per install.
+"""
+
+from tl_cli.main import cli
+
+if __name__ == "__main__":
+    cli()

thoughtleaders_cli-0.9.9/src/tl_cli/client/errors.py

@@ -0,0 +1,122 @@
+"""User-friendly error handling for API responses."""
+
+import json
+import sys
+import traceback
+
+from rich.console import Console
+
+err = Console(stderr=True)
+
+
+class ApiError(Exception):
+    """Raised when the API returns a non-success status."""
+
+    def __init__(self, status_code: int, detail: str, raw: dict | None = None, url: str | None = None, response_text: str | None = None):
+        self.status_code = status_code
+        self.detail = detail
+        self.raw = raw
+        self.url = url
+        self.response_text = response_text
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+def _print_debug(error: ApiError) -> None:
+    """Print detailed debug info for an API error."""
+    from tl_cli.config import debug
+
+    if not debug:
+        return
+    err.print(f"\n[dim]--- debug ---[/dim]")
+    if error.url:
+        err.print(f"[dim]URL: {error.url}[/dim]")
+    err.print(f"[dim]HTTP {error.status_code}: {error.detail}[/dim]")
+    if error.response_text:
+        err.print(f"[dim]Response body:[/dim]")
+        err.print(f"[dim]{error.response_text}[/dim]")
+    err.print(f"[dim]Traceback:[/dim]")
+    err.print(f"[dim]{''.join(traceback.format_exception(error))}[/dim]")
+
+
+def _split_hint(error: ApiError) -> tuple[str, str | None]:
+    """Separate the server's `hint` from `detail`.
+
+    The server sends the remediation both concatenated into `detail` (for
+    older clients) and as a separate `hint` key — render it on its own line
+    so it can't get lost in the error. Used by every branch: a hint on a
+    billing refusal (402/403/429) is just as actionable as one on a 400.
+    """
+    detail = error.detail or ""
+    hint = (error.raw or {}).get("hint") if isinstance(error.raw, dict) else None
+    if isinstance(hint, str) and hint:
+        if detail.endswith(hint):
+            detail = detail[: -len(hint)].rstrip()
+        return detail, hint
+    return detail, None
+
+
+def _print_hint(hint: str | None) -> None:
+    if hint:
+        err.print(f"[bold yellow]Hint:[/bold yellow] [yellow]{hint}[/yellow]")
+
+
+def handle_api_error(error: ApiError) -> None:
+    """Print a user-friendly error message and exit with the right code."""
+    detail, hint = _split_hint(error)
+    if error.status_code == 401:
+        err.print("[red]Authentication required.[/red] Run: tl auth login")
+        _print_debug(error)
+        sys.exit(2)
+    elif error.status_code == 402:
+        # The server composes the whole story into `detail` — a prepaid org is
+        # told to deposit, a subscription org that it can also just wait for
+        # the next top-up — and only the server knows which org this is. The
+        # old fixed copy overwrote that with the same top-up pitch for
+        # everyone. The `tl credits buy` line stays: it is the CLI-native way
+        # to act on the refusal, which the server's sentence can't know about.
+        if detail:
+            err.print(f"[red]{detail}[/red]")
+        else:
+            err.print("[red]Insufficient credits.[/red]")
+            err.print("Or visit: https://app.thoughtleaders.io/billing")
+        _print_hint(hint)
+        err.print("Top up with: [bold]tl credits buy --amount-usd 10[/bold]")
+        _print_debug(error)
+        sys.exit(4)
+    elif error.status_code == 403:
+        # Verbatim, with no upsell line of our own: a billing 403's detail
+        # already names the paid plan (UPGRADE_MESSAGE and friends), and the
+        # rest of the 403s — "Superuser only", permission errors — are not
+        # plan problems, so "your plan may not include this" was misdirection
+        # exactly where the user needed the real reason.
+        err.print(f"[red]Access denied:[/red] {detail}")
+        _print_hint(hint)
+        _print_debug(error)
+        sys.exit(1)
+    elif error.status_code == 404:
+        err.print(f"[yellow]Not found:[/yellow] {detail}")
+        _print_hint(hint)
+        _print_debug(error)
+        sys.exit(1)
+    elif error.status_code == 429:
+        # Both quota gates refuse with 429 and compose the whole explanation
+        # into `detail` — which cap was hit, how much of it is used, and when it
+        # frees up. Collapsing that to a flat "rate limited" line drops the only
+        # thing that tells the user whether to wait, buy credits, or ask for a
+        # seat. An edge/WAF 429 carries no detail and keeps the generic wording.
+        if detail:
+            err.print(f"[yellow]{detail}[/yellow]")
+        else:
+            err.print("[yellow]Rate limited.[/yellow] Please wait and try again.")
+        _print_hint(hint)
+        _print_debug(error)
+        sys.exit(3)
+    elif error.status_code >= 500:
+        err.print(f"[red]Server error ({error.status_code}):[/red] {error.detail}")
+        _print_debug(error)
+        sys.exit(3)
+    else:
+        err.print(f"[red]Error ({error.status_code}):[/red] {detail}")
+        _print_hint(hint)
+        _print_debug(error)
+        sys.exit(1)

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/src/tl_cli/commands/balance.py

@@ -53,6 +53,17 @@ def balance(
         if allow_overage:
             console.print("[dim]Overage: enabled[/dim]")
 
+        # The server's own read on the caller's allowance — the session-quota
+        # percentage, or the seatless explanation. This is the same sentence
+        # the refusal path uses, so a seatless member learns why from
+        # `tl balance` instead of only from their first refused call (it used
+        # to be visible solely under --json).
+        usage = data.get("credit_usage") or {}
+        usage_message = usage.get("message")
+        if isinstance(usage_message, str) and usage_message:
+            style = "yellow" if usage.get("warn") else "dim"
+            console.print(f"[{style}]{usage_message}[/{style}]")
+
         # Top-up hint when running low. Threshold matches the hook warning
         # that nudges the user before they hit 0.
         try:
@@ -63,7 +74,7 @@ def balance(
             console.print(
                 "[yellow]Running low.[/yellow] Top up with: "
                 "[bold]tl credits buy --amount-usd 10[/bold] "
-                "(or https://app.thoughtleaders.io/billing/cli)"
+                "(or https://app.thoughtleaders.io/billing)"
             )
 
         recent = data.get("recent_usage", [])

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/src/tl_cli/commands/setup.py

@@ -756,3 +756,74 @@ def setup_codex(
         json_output=json_output,
         toon_output=toon_output,
     )
+
+
+def _prepend_user_path(new_dir: str) -> bool:
+    """Prepend ``new_dir`` to the persistent per-user PATH.
+
+    Writes HKCU\\Environment and broadcasts the change so new processes pick it
+    up without a sign-out. Returns True if PATH was changed, False if new_dir
+    was already present. Windows-only.
+    """
+    import ctypes
+    import winreg
+
+    with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment", 0, winreg.KEY_READ | winreg.KEY_WRITE) as key:
+        try:
+            current, _ = winreg.QueryValueEx(key, "Path")
+        except FileNotFoundError:
+            current = ""
+        parts = [p for p in current.split(os.pathsep) if p]
+        target = os.path.normcase(os.path.normpath(new_dir))
+        if any(os.path.normcase(os.path.normpath(p)) == target for p in parts):
+            return False
+        updated = os.pathsep.join([new_dir, *parts]) if parts else new_dir
+        winreg.SetValueEx(key, "Path", 0, winreg.REG_EXPAND_SZ, updated)
+
+    # Tell running shells the environment changed (best-effort).
+    ctypes.windll.user32.SendMessageTimeoutW(0xFFFF, 0x1A, 0, "Environment", 0x2, 5000, None)
+    return True
+
+
+@app.command("windows")
+def setup_windows(
+    force: bool = typer.Option(False, "--force", help="Overwrite an existing tl.cmd wrapper"),
+) -> None:
+    """Make `tl` runnable under Windows Smart App Control (Windows only).
+
+    pipx/uv expose `tl` through an *unsigned* launcher stub that Smart App
+    Control (and enforced WDAC policies) block. This writes a small `tl.cmd`
+    that runs the CLI through the already-signed `python.exe` instead, and
+    puts it ahead of the blocked stub on your PATH.
+
+    Run once. On a machine where `tl` is already blocked, bootstrap it with
+    the venv's signed python directly:
+
+        <pipx-venv>\\Scripts\\python.exe -m tl_cli setup windows
+
+    Examples:
+        tl setup windows
+    """
+    if sys.platform != "win32":
+        console.print("[yellow]`tl setup windows` only applies on Windows — nothing to do here.[/yellow]")
+        return
+
+    python_exe = Path(sys.executable)
+    wrapper_dir = Path(os.environ.get("LOCALAPPDATA", Path.home())) / "Programs" / "tl-cli"
+    wrapper = wrapper_dir / "tl.cmd"
+
+    if wrapper.exists() and not force:
+        console.print(f"[yellow]Wrapper already exists:[/yellow] {wrapper}\nRe-run with --force to regenerate it.")
+        return
+
+    wrapper_dir.mkdir(parents=True, exist_ok=True)
+    # Absolute path to the signed interpreter bypasses PATH so the launch can't
+    # resolve back to the blocked stub. %* forwards all arguments unchanged.
+    wrapper.write_text(f'@echo off\r\n"{python_exe}" -m tl_cli %*\r\n', encoding="ascii", newline="")
+
+    console.print(f"[green]✓[/green] Wrote signed-launcher wrapper: {wrapper}")
+    if _prepend_user_path(str(wrapper_dir)):
+        console.print(f"[green]✓[/green] Added to your user PATH (ahead of the blocked stub): {wrapper_dir}")
+    else:
+        console.print(f"[dim]Already on your user PATH: {wrapper_dir}[/dim]")
+    console.print("[dim]Open a new terminal, then run:[/dim] tl whoami")

{thoughtleaders_cli-0.9.7 → thoughtleaders_cli-0.9.9}/src/tl_cli/output/formatter.py

@@ -95,12 +95,14 @@ def output(
         # Banner still goes to stderr so it surfaces even when stdout is
         # piped through `jq` or redirected to a file.
         _print_quota_notice(data)
+        _print_upgrade_notice(data)
         _print_server_warnings(data)
         return
 
     if not results:
         err_console.print("[dim]No results found.[/dim]")
         _print_quota_notice(data)
+        _print_upgrade_notice(data)
         _print_server_warnings(data)
         _print_usage(usage)
         return
@@ -121,6 +123,7 @@ def output(
 
     _print_pagination_notice(data)
     _print_quota_notice(data)
+    _print_upgrade_notice(data)
     _print_server_warnings(data)
     _print_usage(usage)
     _print_breadcrumbs(breadcrumbs)
@@ -523,17 +526,17 @@ def _print_server_warnings(data: dict) -> None:
 
 
 def _print_quota_notice(data: dict) -> None:
-    """Print a banner when the server signals a billing-quota refusal or
-    truncation on a raw-DB call.
-
-    The server emits `_billing_quota_exhausted` on the response envelope
-    in two cases: (a) the query was refused outright before execution
-    because the org has already used its expensive-query allowance for
-    the window; (b) the query ran but the result list was truncated
-    because the remaining expensive-row allowance was smaller than the
-    natural row count. Either way the response carries an empty or
-    short ``results`` array and the caller needs to know *why* and
-    *when they can retry*.
+    """Print a banner when the server signals a billing-quota truncation
+    on a raw-DB call.
+
+    The query ran, but the result list was cut to the org's remaining
+    premium-row allowance for the window — so ``results`` is short of what
+    the query would naturally return, and the caller needs to know *why*
+    and *when the rest becomes reachable*.
+
+    An outright refusal never lands here: it is a 429 carrying the server's
+    detail, rendered by `client.errors.handle_api_error`. A short result set
+    and a refused query must not look alike.
     """
     if not data.get("_billing_quota_exhausted"):
         return
@@ -555,6 +558,28 @@ def _print_quota_notice(data: dict) -> None:
         )
 
 
+def _print_upgrade_notice(data: dict) -> None:
+    """Print a banner when the server withheld premium fields from a
+    successful response (``_upgrade_required``).
+
+    The rows are real, but transcript / brand-mention / demographic fields
+    were omitted for the caller's plan — without this line a free-tier user
+    reads the gaps as "no data exists". The sentence is the server's own
+    (UPGRADE_MESSAGE), the same one the web app's field locks show, so the
+    wording stays composed in exactly one place.
+    """
+    notice = data.get("_upgrade_required")
+    if not isinstance(notice, dict):
+        return
+    message = notice.get("message") or "Some fields are available on paid plans."
+    err_console.print(f"[bold yellow]⚠ {message}[/bold yellow]")
+    fields = notice.get("fields") or []
+    if fields:
+        err_console.print(
+            f"[yellow]  withheld field(s): {', '.join(str(f) for f in fields)}[/yellow]"
+        )
+
+
 def output_pricing_estimate(data: dict, fmt: str) -> None:
     """Render the `--pricing` dry-run estimate for `tl db pg|fb|es`.
 

thoughtleaders_cli-0.9.9/tests/test_quota_refusal_message.py

@@ -0,0 +1,68 @@
+"""Tests for what a 429 quota refusal actually tells the user.
+
+Both server-side quota gates refuse with 429 and put the entire remedy into
+`detail`: which cap was hit, how much of it is spent, and when it frees up. The
+user's next action differs per gate — wait out a rolling window, buy credits,
+or ask an org admin for a seat — so a generic "rate limited" line is not a
+smaller version of the message, it is the wrong message.
+"""
+
+import pytest
+
+from tl_cli.client.errors import ApiError, handle_api_error
+
+
+def _render(error: ApiError, capsys) -> str:
+    with pytest.raises(SystemExit) as exc:
+        handle_api_error(error)
+    assert exc.value.code == 3
+    return " ".join(capsys.readouterr().err.split())  # undo console wrapping
+
+
+class TestQuotaRefusalMessage:
+    def test_premium_data_quota_detail_reaches_the_user(self, capsys):
+        detail = (
+            "Premium data quota reached: your organization has used 100 of 100 "
+            "premium-data rows in the last 24h. Wait ~3.2h until the oldest call "
+            "rolls off the window (2026-08-17T14:02:11+00:00)."
+        )
+        out = _render(
+            ApiError(429, detail, raw={"detail": detail, "code": "quota_exhausted"}),
+            capsys,
+        )
+        assert "100 of 100 premium-data rows" in out
+        assert "Wait ~3.2h" in out
+
+    def test_per_user_credit_quota_detail_reaches_the_user(self, capsys):
+        detail = (
+            "Per-user CLI credit quota reached: 1236.32 of 1200.00 credits used this "
+            "session (5h window). Wait ~5.0h until your session resets "
+            "(2026-08-17T16:21:13+00:00); you can then spend up to 1200.00 credits "
+            "again. Or buy credits to continue without waiting: "
+            "https://app.thoughtleaders.io/billing"
+        )
+        out = _render(
+            ApiError(429, detail, raw={"detail": detail, "code": "quota_exhausted"}),
+            capsys,
+        )
+        assert "1236.32 of 1200.00 credits" in out
+        # The remedy is the point: without it the user cannot tell that buying
+        # credits skips the wait.
+        assert "buy credits" in out
+
+    def test_seatless_refusal_names_the_remedy(self, capsys):
+        detail = (
+            "No CLI seat is assigned to your user in this organization. Ask an "
+            "organization owner or admin to assign you a seat: "
+            "https://app.thoughtleaders.io/billing"
+        )
+        out = _render(
+            ApiError(429, detail, raw={"detail": detail, "code": "quota_exhausted"}),
+            capsys,
+        )
+        assert "assign you a seat" in out
+
+    def test_bare_429_keeps_the_generic_wording(self, capsys):
+        # An edge/WAF rate limit carries no detail; there is nothing to explain.
+        out = _render(ApiError(429, "", raw=None), capsys)
+        assert "Rate limited." in out