thoughtleaders-cli 0.6.24__tar.gz → 0.6.26__tar.gz

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.24
+Version: 0.6.26
 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

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/pyproject.toml

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

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/skills/tl/SKILL.md

@@ -92,7 +92,7 @@ Other key concepts:
   - **`purchase_date`** — when the sponsorship was purchased (i.e. when the deal was made); These make up bookings.
   - **`send_date`** — the date the video is/was expected to be published (scheduled)
   - **`publish_date`** — the date the video was actually published; These make up live ads.
-- **Credits** — every data query costs credits; use `tl describe` to see rates
+- **Credits** — every data query costs credits; use `tl describe` to see rates. Top up with `tl credits buy --amount-usd N` (free; opens a browser checkout). New accounts get a starter balance on first `tl auth login`; the rate is shown by `tl credits pricing`.
 
 Users see data scoped by their organization and plan:
 - **Media buyers** see sponsorships where their org is the brand. They see `price` but never `cost`.
@@ -345,7 +345,10 @@ tl schema pg <table>                   # PostgreSQL schema for a SINGLE table (f
 tl schema fb                           # Live Firebolt tables and column types for `tl db fb` (free) — both tables
 tl schema fb <table>                   # Firebolt schema for a SINGLE table (free) — `article_metrics` or `channel_metrics`
 tl schema es                           # Elasticsearch document shape for `tl db es` (free)
-tl balance --json                      # Credit balance (free)
+tl balance --json                      # Credit balance + recent usage (free)
+tl credits pricing                     # Current usd-per-credit rate (free, no auth)
+tl credits buy --amount-usd 10         # Start a top-up; opens browser checkout (free)
+tl credits history                     # Recent top-ups for the caller's org (free)
 tl whoami                              # Current user, org, brands (free)
 tl auth status                         # Auth check (free)
 tl changelog                           # Release notes — current version, or current..latest if behind (free)

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/skills/tl/references/postgres-schema.md

@@ -207,6 +207,17 @@ A channel can have multiple adspots (different sellers: talent manager, direct,
 | `description` | text | LLM-generated description of the channel. Sometimes useful as a regex-target for thematic filtering when the integer category is too coarse (e.g. filtering "Technology" cat 15 down to actual tech reviewers via keywords like `tech|gadget|review|software`). |
 | `evergreenness` | float | Cached evergreen score |
 
+#### Hallucination shapes to avoid
+
+When composing `SELECT ... FROM thoughtleaders_channel ...`, do not improvise column names from semantic intuition — consult the column table above. Failed guesses return *"column '\<name\>' does not exist"* and cost a round-trip. Recurring shapes:
+
+- ❌ **Suffix/qualifier variants of date columns** (e.g. an `_max` / `latest_` / `_date` form when the canonical column has neither). Date columns above use bare names.
+- ❌ **Platform-name-prefixed ID forms** (e.g. a platform-name prefix when the canonical column uses a neutral `external_` prefix). See the column table for the actual ID column.
+- ❌ **Bare-noun forms without the table-prefix** (e.g. `name` instead of `channel_name`). This table prefixes its display fields with `channel_` to avoid SQL keyword collisions and ambiguity in joins.
+- ❌ **User-facing-term forms used as SQL column names** (the user-facing word is sometimes different from the SQL column name; consult [business-glossary](business-glossary.md) for the canonical mapping when the two diverge).
+
+When the canonical column you need isn't obvious from the table above, consult the column table first. Do **not** rely on a 400 to correct you, and do **not** fall back to `information_schema.columns` as the recovery path — that's a regression marker too.
+
 #### `content_category` Constants
 
 Source of truth: `thoughtleaders.taxonomies.ContentCategory` (Django `IntEnum` in the main `thoughtleaders` repo).

thoughtleaders_cli-0.6.26/skills/tl-import/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: tl-import
+description: Bulk-add or exclude a list of channels, brands, uploads (videos), or sponsorships against a ThoughtLeaders report (campaign). Superuser-only. Use when a request asks to import / add / exclude a batch of identifiers against a specific report ID — phrasings like "import these channels into report 1234", "add brands to campaign 5678", "exclude these channels from report Z", "bulk-add these videos to report X".
+---
+
+# tl-import
+
+Wraps the `tl bulk-import` command — submits a list of identifiers against a report, polls until done, and renders a per-row result table.
+
+## When to use
+
+Trigger on requests like:
+
+- "Import @mkbhd, @veritasium into report 1234"
+- "Add these brands to campaign 5678"
+- "Bulk-add this list of channels to report 999"
+- "Exclude these channels from report Z"
+- "Add these videos to report X"
+
+Single-identifier requests still work (the command accepts one). The reason to keep this skill separate from other report-edit flows: it's the only path that auto-creates channels from YouTube URLs / handles, and brands from website domains.
+
+## Inputs to gather
+
+Before running, confirm:
+
+1. **Report ID** (`--campaign` / `-c`) — required. If the user pastes a TL URL (e.g. `https://app.thoughtleaders.io/#/thoughtleaders?campaign=23859&...`), the integer after `campaign=` is the ID.
+2. **Entity type** — one of `channels` / `brands` / `articles` / `sponsorships`. Infer from context, but translate user-facing vocabulary:
+   - YouTube URLs / handles / `UC…` IDs → `channels`
+   - Domains / brand slugs → `brands`
+   - "videos" / "uploads" / video URLs / video IDs → `articles` *(the CLI calls them uploads in `tl uploads list`, but `bulk-import` expects `articles` — same concept, legacy naming)*
+   - "adlinks" / "deals" / "sponsorships" / numeric AdLink IDs → `sponsorships`
+3. **Identifiers** — the list. Accepted shapes per entity:
+   - **channels**: numeric DB IDs, YouTube channel IDs (`UC…`), `@handles`, full YouTube URLs (`/@…`, `/channel/UC…`, `/user/…`)
+   - **brands**: numeric IDs, slugs, websites / domains (`example.com`)
+   - **articles** (uploads): video IDs or video URLs
+   - **sponsorships** (adlinks): numeric AdLink IDs only
+4. **Include vs exclude** — default is include (add to the report). Pass `--exclude` only if the user explicitly wants to remove from the report.
+
+## How to invoke
+
+The command reads identifiers from a file (`--ids-file`) or stdin:
+
+```bash
+# small list — stdin
+echo '@mkbhd
+@veritasium
+@lemmino' | tl bulk-import channels --campaign 1234
+
+# larger list — file
+tl bulk-import channels --campaign 1234 --ids-file ./channels.txt
+
+# exclusion
+tl bulk-import brands --campaign 5678 -f ./brands.txt --exclude
+```
+
+Short flags: `-c` for `--campaign`, `-f` for `--ids-file`.
+
+## Output: the `inputs` envelope
+
+`tl bulk-import` returns a JSON envelope. Use the **`inputs`** array as the source of truth for what to render — it has one row per submitted identifier, in input order, with everything you need to classify and display.
+
+```json
+{
+  "task_id": "...",
+  "mode": "include",
+  "inputs": [
+    {"input": "@mkbhd",            "resolved_id": 4587,    "reason": "Success",    "newly_created": false},
+    {"input": "@veritasium",       "resolved_id": 1209,    "reason": "Duplicate",  "newly_created": false},
+    {"input": "@OfficialSaharTV",  "resolved_id": 1328906, "reason": "Success",    "newly_created": true},
+    {"input": "https://bad-url",   "resolved_id": null,    "reason": "Not found",  "newly_created": false}
+  ],
+  "success_ids": [4587, 1328906],
+  "newly_created_ids": [1328906],
+  "failed_ids": [...],
+  ...
+}
+```
+
+Each `inputs` row's `input` field echoes the raw identifier the user submitted (unchanged). `resolved_id` is the entity ID it matched/created, or `null` for failures. `reason` and `newly_created` drive the row's display label below.
+
+**`mode` echoes back the operation mode** (`"include"` or `"exclude"`). You need this for labelling because the semantics flip:
+
+- include + Success = identifier was just added to the report
+- exclude + Success = identifier was just removed from the report
+- include + Duplicate = identifier was already in the report (no-op)
+- exclude + Duplicate = identifier was already excluded (no-op)
+
+Don't use `success_ids` / `failed_ids` for display — they lose input mapping and miss the include/exclude direction. `inputs` is the canonical surface.
+
+## Classify each row
+
+| `reason` | `newly_created` | `mode` | Icon | Label |
+|---|---|---|---|---|
+| `Success` | `true` | `include` | 🆕 | Created in TL |
+| `Success` | `true` | `exclude` | ⚠️ | Created in TL — unexpected for exclude, verify report state |
+| `Success` | `false` | `include` | ✅ | Added |
+| `Success` | `false` | `exclude` | ✂️ | Excluded |
+| `Duplicate` | any | `include` | ↺ | Already in report |
+| `Duplicate` | any | `exclude` | ↺ | Already excluded |
+| `Not found` | any | any | ❌ | Not found |
+| `Cannot parse` | any | any | ❌ | Bad format |
+| `Multiple matches found` | any | any | ❌ | Ambiguous (multiple matches) |
+| `Limit exceeded` | any | any | ❌ | Auto-create cap hit |
+| starts with `Error:` | any | any | ❌ | Error (show reason verbatim) |
+| anything else | any | any | ❌ | Failed (show reason verbatim) |
+
+For 🆕 rows: mention that enrichment (subscriber stats, AI description, demographics for channels; metadata for brands) is queued and will populate over the next few minutes — these entities just entered the database.
+
+For ⚠️ rows: if an exclude import returns `newly_created: true`, treat it as unexpected. Tell the user the channel was created but does not appear to have been excluded — ask them to verify the report and re-submit the exclude against the returned `resolved_id` if needed.
+
+## Display
+
+Per-row markdown table. **Headline first** with the gain count, then the table.
+
+For include mode:
+
+```markdown
+**Bulk-import to report 23859 — done.** Report gained **2** rows; **1** was already there; **1** failed.
+
+| # | Status | Input | ID | Reason |
+|---|---|---|---|---|
+| 1 | ✅ Added | `@mkbhd` | 4587 | Success |
+| 2 | ↺ Already in report | `@veritasium` | 1209 | Duplicate |
+| 3 | 🆕 Created in TL | `@OfficialSaharTV` | 1328906 | Success — enrichment queued |
+| 4 | ❌ Not found | `https://bad-url` | — | Not found |
+```
+
+For exclude mode, headline uses "lost" wording:
+
+```markdown
+**Bulk-import (exclude) to report 23859 — done.** Report lost **N** rows; **M** were already excluded.
+```
+
+Display rules:
+
+- **Use the user's raw `input` value** in the Input column (it's `inputs[i].input` — the raw submitted string, unchanged).
+- **Omit any column that's uniformly empty** — for sponsorships, the "Input" and "ID" columns are usually identical (both numeric); the Reason column carries the signal.
+- **Small imports (≤30 rows):** render the full table.
+- **Large imports (>30 rows):** lead with a summary table of bucket counts; render the per-row table only for **non-bulk-success rows** — i.e. omit the dominant happy-path bucket, which is ✅ Added in include mode and ✂️ Excluded in exclude mode. The rows the user cares about (already-present, newly-created, failed, unexpected) all stay. Offer to dump the omitted rows on request.
+
+  Summary table (include mode example):
+
+  ```markdown
+  | Bucket | Count |
+  |---|---|
+  | ✅ Added | 142 |
+  | ↺ Already in report | 7 |
+  | 🆕 Created in TL | 3 |
+  | ❌ Failed | 2 |
+  | **Total submitted** | **154** |
+  ```
+
+  Summary table (exclude mode example):
+
+  ```markdown
+  | Bucket | Count |
+  |---|---|
+  | ✂️ Excluded | 142 |
+  | ↺ Already excluded | 7 |
+  | ❌ Failed | 2 |
+  | **Total submitted** | **151** |
+  ```
+
+- **Never look up entity names** with extra `tl channels show <id>` / `tl brands show <id>` calls just to populate a "Name" column — those are metered. The user's input column is enough for them to identify each row. If the user explicitly asks "what are these channels called?", then look them up.
+
+## Errors at the command level (before the per-row results)
+
+These are envelope-level failures, distinct from per-row `reason` values:
+
+- **403** → caller isn't a superuser. Stop and tell the user; this command is gated.
+- **400** → bad input shape (missing field, unknown entity, all-empty identifiers). Show the `detail` verbatim.
+- **402** → out of credits. Tell the user to top up.
+- **Connection failed** → transient network issue. Retry once; if it persists, surface to the user.
+
+## What this skill does NOT do
+
+- Doesn't create reports — that's `tl-report-builder`.
+- Doesn't change report metadata (title, description, columns, filters).
+- Doesn't validate identifiers ahead of time — submit and let the per-row `reason` tell the user which ones failed. Pre-checking with `tl channels show` / etc. is wasteful (metered) and adds latency.
+- Doesn't sweep duplicates from the user's input list — submit them as-is. The response will mark the second occurrence as `Duplicate`, which is more informative than silently deduping.

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/skills/tl-report-builder/SKILL.md

@@ -1608,6 +1608,8 @@ Render as Markdown links in the table cell — *not* the bare ID, *not* the YouT
 
 If the slug is missing or empty for a row, fall back to the ID-based path the platform exposes (e.g. `https://app.thoughtleaders.io/youtube/id-<channel_id>`); never fall back to the YouTube URL — that takes the user *away* from TL. The Phase 2 sample query must include the slug column alongside the rendered fields, otherwise the table can't link properly.
 
+**Sample-row enrichment column names — read from the canonical schema, do NOT improvise.** When the rendered table needs columns beyond what the initial ES sample returned (typically a slug for the hyperlink and a "last published" date), look up the column names in [`tl/references/postgres-schema.md` → `thoughtleaders_channel`](../tl/references/postgres-schema.md#thoughtleaders_channel-youtube-channels) before composing the PG query. Agents have improvised semantically-plausible column names from intuition (date-shape variants, platform-name-prefixed ID forms, bare-noun forms without table prefix, user-facing-term forms), hit a 400 with *"column '\<name\>' does not exist"*, then run an `information_schema.columns` fishing query to recover — a wasted round-trip that the canonical column catalogue eliminates. **If you find yourself about to write a `SELECT ... FROM thoughtleaders_channel WHERE ...` query and you're not sure of a column name, consult the schema reference first** — do not guess and rely on the 400 to correct you, and do not fall back to `information_schema.columns` as the recovery path. See the schema reference's "Hallucination shapes to avoid" subsection for the recurring guess patterns.
+
 21. **No side-channel deliverables.** The skill produces exactly two output shapes: (a) a saved TL Campaign + a campaign URL (save mode), or (b) an in-chat preview with the sample-rows table + takeaways + save tail (preview mode). It does NOT write CSVs, Markdown reports, or any other "data dump" file to disk as a deliverable. A real run for FRÉ Skincare wrote a CSV to `<temp>\fre-skincare-shortlist.csv` and pointed the user at it as the "full list" — that's a fabricated alternative deliverable that bypasses the TL report-creation flow. If the user wants more than the preview shows, the answer is "save it as a campaign and run it" — not "I'll dump CSV". The only filesystem write the skill is allowed to make is the `<system-temp>/tl-report-builder-<slug>.json` transport file used in step 1 of the save mechanics, and even that is a transport (deleted whenever) — never a deliverable.
 22. **Phases 1–4 always run; the skill never short-circuits to a chat-only data answer.** When the skill is invoked, the output is **always** a Campaign (save mode) or a Phase-4 preview (preview mode). Bypassing Phase 1–4 to produce a verification table, an analyst summary, a list cross-check, or any other "I'll just answer this directly in chat" deliverable is a regression bug. Real example to internalise: a prompt of *"Brands sponsoring Linus Tech Tips in the past 6 months: dbrand, Private Internet Access, Squarespace, Vessi, Secretlab, UGREEN, Odoo, Dell, Razer, Saily"* should route through Phase 1 → Type 2 brands report scoped to channel 1788 + last 180 days → Phases 2/3/4 → preview with the user's seed brands as a starting filter and the takeaways calling out *"your seed list is accurate but incomplete — TL data shows 60 distinct sponsors over 131 videos; top missing are War Thunder (7), Boot.dev (6), DeleteMe (6)…"*. Instead, a recent run produced exactly that analytical content **as a free-floating markdown table in chat** — no FilterSet emitted, no columns picked, no widgets, no save option. The analytical insight is welcome as a takeaway; it is **not** a substitute for the report. If you find yourself replying with a markdown table directly, ask: am I about to ship a Phase-4 preview, or am I bypassing the phases? The answer must always be the former.
 23. **No ad-hoc data-engineering pipelines.** The skill does NOT write Python consolidation scripts, multi-stage CSV merge tools, dedupe scripts, false-positive filters as standalone files, or any other custom data pipeline as part of producing the deliverable. The data plane is fixed: `tl db pg` (PG), `tl db es` (ES), `tl db fb` (Firebolt). Phase 2 issues queries against these directly to compose a FilterSet and validate it; that's the entire data-side surface. A real aviation/non-MSN run produced this anti-pattern: the agent issued five separate PG queries each writing a CSV (`/tmp/aviation_by_name.csv`, `/tmp/aviation_desc.csv`, `/tmp/aviation_desc2.csv`, `/tmp/aviation_desc3.csv`, `/tmp/aviation_pilot_desc.csv`), wrote a `consolidate_aviation.py` script to merge + dedupe + filter false positives, hit a Windows-vs-Linux `/tmp/` path mismatch, debugged it with `cygpath`, eventually rewrote the script to use `%LOCALAPPDATA%\Temp`, then produced `aviation_consolidated.csv` as the "full list". **None of this is the skill's job.** The right shape: one ES query with `terms` / `bool.should` filters covering the niche keywords + the `creator_countries` filter + `msn_channels_only: false` + `is_active: true` → get count + sample → emit the FilterSet → preview. If the skill's narration is starting to read like a data engineer's bash session ("Run consolidation script", "Try /tmp path resolution", "Resolve /tmp via cygpath", "Find where /tmp files actually are"), stop — the skill has gone off the rails. Restart from Phase 1 with a single composed query.

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/src/tl_cli/auth/commands.py

@@ -4,6 +4,7 @@ import typer
 from rich.console import Console
 from rich.prompt import Prompt
 
+from tl_cli.auth.finalize import finalize_signup
 from tl_cli.auth.login import login_browser, login_device_code
 from tl_cli.auth.token_store import clear_tokens, load_tokens
 
@@ -13,7 +14,12 @@ console = Console(stderr=True)
 
 @app.command("login", help="Log in to ThoughtLeaders.")
 def login_cmd() -> None:
-    """Log in to ThoughtLeaders."""
+    """Log in to ThoughtLeaders.
+
+    After Auth0 returns, the CLI calls the server's finalize endpoint.
+    First-time users are prompted for a persona (Media Buyer or Creator)
+    and the account + starter credits are created on the server side.
+    """
     console.print("[bold]How would you like to authenticate?[/bold]")
     console.print("  [cyan]1[/cyan] — Browser on this machine (default)")
     console.print("  [cyan]2[/cyan] — Device code (use a browser on another device)")
@@ -25,6 +31,8 @@ def login_cmd() -> None:
     else:
         login_browser()
 
+    finalize_signup()
+
 
 @app.command("logout")
 def logout_cmd() -> None:

thoughtleaders_cli-0.6.26/src/tl_cli/auth/finalize.py

@@ -0,0 +1,88 @@
+"""Server-side signup finalize, called once per login.
+
+After Auth0 returns a valid token the CLI asks the server whether an
+account exists for the email. If yes, this is a no-op. If no, the CLI
+prompts for a persona (Media Buyer or Creator) and POSTs it back; the
+server creates the User, Organization, Profile and CreditAccount.
+
+Errors here never abort login — the user can always retry the prompt
+on the next call. We do print a clear message so it's obvious whether
+the account is fully set up.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+
+from tl_cli.client.errors import ApiError
+from tl_cli.client.http import get_client
+
+console = Console(stderr=True)
+
+PERSONA_LABEL_TO_KEY = {
+    "Media Buyer": "media_buyer",
+    "Creator": "creator",
+}
+
+
+def finalize_signup() -> None:
+    """POST /auth/finalize, prompting for persona if the server asks for one."""
+    client = get_client()
+    try:
+        # First call: no body. Server tells us whether persona is required.
+        try:
+            result = client.post("/auth/finalize", {})
+        except ApiError as exc:
+            if exc.status_code == 400 and isinstance(exc.raw, dict) and exc.raw.get("code") == "persona_required":
+                result = _prompt_and_finalize(client, exc.raw.get("allowed_personas") or [])
+            elif exc.status_code == 404:
+                # Server predates this endpoint — silently skip; legacy
+                # accounts already exist and don't need provisioning.
+                return
+            else:
+                console.print(f"[yellow]Could not finalize signup: {exc.detail}[/yellow]")
+                return
+
+        if result.get("created"):
+            org = result.get("organization", {})
+            console.print(
+                f"[green]Account created for {org.get('name', 'your organization')}.[/green] "
+                "Run [bold]tl balance[/bold] to see your starter credits."
+            )
+    finally:
+        client.close()
+
+
+def _prompt_and_finalize(client, allowed: list[str]) -> dict:
+    """Prompt the user for a persona, then retry /auth/finalize."""
+    console.print()
+    console.print("[bold]Welcome to ThoughtLeaders![/bold] We need one more detail to set up your account.")
+    console.print("  [cyan]1[/cyan] — Media Buyer (brands and agencies buying sponsorships)")
+    console.print("  [cyan]2[/cyan] — Creator (channels selling sponsorships)")
+
+    persona_key: str | None = None
+    while persona_key is None:
+        choice = Prompt.ask("I am a", choices=["1", "2"], default="1", console=console)
+        candidate = "media_buyer" if choice == "1" else "creator"
+        if allowed and candidate not in allowed:
+            console.print(f"[yellow]Server rejects persona '{candidate}'. Allowed: {', '.join(allowed)}.[/yellow]")
+            continue
+        persona_key = candidate
+
+    org_name = Prompt.ask(
+        "Organization name (optional, leave blank to use your email)",
+        default="",
+        console=console,
+    ).strip()
+
+    body = {"persona": persona_key}
+    if org_name:
+        body["organization_name"] = org_name
+
+    try:
+        return client.post("/auth/finalize", body)
+    except ApiError as exc:
+        console.print(f"[red]Signup failed:[/red] {exc.detail}")
+        raise typer.Exit(1)

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/src/tl_cli/client/errors.py

@@ -46,7 +46,8 @@ def handle_api_error(error: ApiError) -> None:
         sys.exit(2)
     elif error.status_code == 402:
         err.print("[red]Insufficient credits.[/red]")
-        err.print("Deposit more at: https://app.thoughtleaders.io/settings/billing")
+        err.print("Top up with: [bold]tl credits buy --amount-usd 10[/bold]")
+        err.print("Or visit: https://app.thoughtleaders.io/billing/cli")
         _print_debug(error)
         sys.exit(4)
     elif error.status_code == 403:

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/src/tl_cli/commands/balance.py

@@ -46,6 +46,19 @@ def balance(
         if allow_overage:
             console.print("[dim]Overage: enabled[/dim]")
 
+        # Top-up hint when running low. Threshold matches the hook warning
+        # that nudges the user before they hit 0.
+        try:
+            balance_decimal = float(balance_val)
+        except (TypeError, ValueError):
+            balance_decimal = None
+        if balance_decimal is not None and balance_decimal < 500:
+            console.print(
+                "[yellow]Running low.[/yellow] Top up with: "
+                "[bold]tl credits buy --amount-usd 10[/bold] "
+                "(or https://app.thoughtleaders.io/billing/cli)"
+            )
+
         recent = data.get("recent_usage", [])
         if recent:
             table = Table(title="Recent Usage")

thoughtleaders_cli-0.6.26/src/tl_cli/commands/bulk_import.py

@@ -0,0 +1,120 @@
+"""tl bulk-import - bulk-add or exclude entities from a report.
+
+Superuser-only on the server side. Submits a list of identifiers
+(channels / brands / articles / sponsorships) against a target report
+and polls until the import completes.
+"""
+
+import json
+import sys
+import time
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+
+err = Console(stderr=True)
+
+POLL_INTERVAL_SEC = 2
+POLL_TIMEOUT_SEC = 600
+VALID_ENTITIES = ("channels", "brands", "articles", "sponsorships")
+
+
+def _read_ids(ids_file: str | None) -> list[str]:
+    if ids_file:
+        text = Path(ids_file).read_text()
+    elif not sys.stdin.isatty():
+        text = sys.stdin.read()
+    else:
+        err.print("[red]Provide --ids-file or pipe identifiers via stdin.[/red]")
+        raise typer.Exit(2)
+    ids = [line.strip() for line in text.splitlines() if line.strip()]
+    if not ids:
+        err.print("[red]No identifiers found.[/red]")
+        raise typer.Exit(2)
+    return ids
+
+
+def _poll_until_done(client, task_id: str) -> dict:
+    deadline = time.time() + POLL_TIMEOUT_SEC
+    with err.status(f"[bold blue]Importing... (task {task_id})[/bold blue]"):
+        while time.time() < deadline:
+            time.sleep(POLL_INTERVAL_SEC)
+            data = client.get(f"/bulk-import/poll/{task_id}")
+            if data.get("finished"):
+                if data.get("error"):
+                    err.print(f"[red]Import failed: {data.get('error')}[/red]")
+                    raise typer.Exit(1)
+                return data.get("end_result") or {}
+    err.print(f"[red]Polling timed out after {POLL_TIMEOUT_SEC}s. Task still running: {task_id}[/red]")
+    raise typer.Exit(3)
+
+
+def bulk_import_command(
+    entity: str = typer.Argument(..., help=f"Entity type: one of {', '.join(VALID_ENTITIES)}"),
+    campaign: int = typer.Option(..., "--campaign", "-c", help="Target report ID"),
+    ids_file: str | None = typer.Option(None, "--ids-file", "-f", help="Path to file with one identifier per line. Omit to read from stdin."),
+    exclude: bool = typer.Option(False, "--exclude", help="Mark these identifiers as excluded from the report instead of included"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output (default)"),
+) -> None:
+    """Bulk-import entities into a report.
+
+    Accepts a list of identifiers per entity:
+      channels      -> numeric IDs, YouTube channel IDs (UC...), @handles, full URLs
+      brands        -> numeric IDs, slugs, websites/domains
+      articles      -> video IDs or URLs
+      sponsorships  -> AdLink IDs (numeric)
+
+    Submits the list and polls until the import completes. Channels/brands
+    that aren't already on file get auto-created from YouTube / their
+    website. Enrichment (metadata, AI description, demographics) is queued
+    and lands a few minutes after the import returns.
+
+    Examples:
+        tl bulk-import channels --campaign 23859 --ids-file ./channels.txt
+        echo "@mkbhd" | tl bulk-import channels -c 23859
+        tl bulk-import brands -c 23859 -f ./brands.txt --exclude
+
+    Requires superuser permission - non-superusers get a 403.
+    """
+    if entity not in VALID_ENTITIES:
+        err.print(f"[red]entity must be one of: {', '.join(VALID_ENTITIES)}[/red]")
+        raise typer.Exit(2)
+
+    ids = _read_ids(ids_file)
+
+    body = {
+        "campaign_id": campaign,
+        "entity": entity,
+        "entity_ids": ids,
+        "include": not exclude,
+    }
+
+    err.print(f"[dim]Submitting {len(ids)} {entity} to report {campaign} (include={not exclude})...[/dim]")
+
+    client = get_client()
+    try:
+        submit = client.post("/bulk-import", json_body=body)
+    except ApiError as e:
+        handle_api_error(e)
+        raise typer.Exit(1)
+
+    task_id = submit.get("task_id")
+    if not task_id:
+        err.print(f"[red]No task_id in submit response: {submit}[/red]")
+        raise typer.Exit(1)
+
+    try:
+        result = _poll_until_done(client, task_id)
+    finally:
+        client.close()
+
+    output = {"task_id": task_id, **result}
+    if json_output or not sys.stdout.isatty():
+        json.dump(output, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    else:
+        Console().print_json(json.dumps(output))

thoughtleaders_cli-0.6.26/src/tl_cli/commands/credits.py

@@ -0,0 +1,184 @@
+"""tl credits — buy credits and view top-up history.
+
+`tl credits buy --amount-usd N` calls the server to start a top-up,
+opens the resulting web checkout URL in the user's browser, and polls
+the balance until it changes (or the user gives up).
+
+`tl credits history` lists recent top-ups for the caller's org.
+
+`tl credits pricing` shows the current usd-per-credit rate. Use this to
+sanity-check what `--amount-usd N` will buy before paying.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import webbrowser
+from decimal import Decimal, InvalidOperation
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.output.formatter import detect_format
+
+app = typer.Typer(help="Buy credits and view top-up history (free)")
+console = Console()
+err = Console(stderr=True)
+
+
+@app.command("pricing")
+def pricing_cmd(
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """Show the credit-to-USD rate, minimum purchase, and starter balance.
+
+    Free — no authentication required.
+    """
+    client = get_client()
+    try:
+        data = client.get("/pricing")
+    except ApiError as e:
+        handle_api_error(e)
+        return
+    finally:
+        client.close()
+
+    if json_output:
+        print(json.dumps(data, indent=2, default=str))
+        return
+
+    console.print(f"\n[bold]Rate:[/bold] ${data['usd_per_credit']} per credit ({data.get('currency', 'USD')})")
+    console.print(f"[bold]Minimum top-up:[/bold] ${data['min_purchase_usd']}")
+    console.print(f"[bold]Starter balance:[/bold] {data['starter_balance']} credits")
+
+
+@app.command("buy")
+def buy_cmd(
+    amount_usd: str = typer.Option(..., "--amount-usd", help="Amount to top up, in USD."),
+    no_browser: bool = typer.Option(False, "--no-browser", help="Don't open a browser, just print the checkout URL."),
+    poll: bool = typer.Option(True, "--poll/--no-poll", help="Poll balance after opening the checkout page."),
+) -> None:
+    """Start a credit top-up.
+
+    Calls the server to create a pending purchase, opens the web checkout
+    URL, and (by default) polls `tl balance` until the credits land or you
+    Ctrl-C out.
+    """
+    try:
+        Decimal(amount_usd)
+    except (InvalidOperation, ValueError):
+        err.print(f"[red]Invalid amount:[/red] {amount_usd}")
+        raise typer.Exit(1)
+
+    client = get_client()
+    try:
+        try:
+            initial = client.get("/balance")
+            initial_balance = Decimal(str(initial.get("balance", 0)))
+        except ApiError:
+            # Pricing fetch may work even if balance fails; still attempt the purchase.
+            initial_balance = None
+
+        try:
+            result = client.post("/top-up", {"usd_amount": amount_usd})
+        except ApiError as e:
+            handle_api_error(e)
+            return
+    finally:
+        client.close()
+
+    checkout_url = result.get("checkout_url")
+    credits = result.get("credits")
+    console.print(
+        f"\n[bold]Started top-up:[/bold] ${result['usd_amount']} → {credits} credits"
+    )
+    console.print(f"Checkout: {checkout_url}")
+
+    if checkout_url and not no_browser:
+        try:
+            webbrowser.open(checkout_url)
+        except Exception:
+            pass
+
+    if not poll or initial_balance is None:
+        console.print("[dim]Run `tl balance` to confirm once payment completes.[/dim]")
+        return
+
+    _poll_for_credit(initial_balance, expected_increment=Decimal(str(credits)))
+
+
+def _poll_for_credit(initial_balance: Decimal, expected_increment: Decimal) -> None:
+    """Poll the balance endpoint until it goes up. Bounded so the CLI
+    eventually returns to the prompt instead of hanging forever.
+    """
+    console.print("[dim]Waiting for payment confirmation (up to 10 minutes; Ctrl-C to stop)…[/dim]")
+    deadline = time.time() + 600
+    last_balance = initial_balance
+    try:
+        while time.time() < deadline:
+            time.sleep(5)
+            client = get_client()
+            try:
+                data = client.get("/balance")
+            except ApiError:
+                client.close()
+                continue
+            client.close()
+            new_balance = Decimal(str(data.get("balance", 0)))
+            if new_balance >= initial_balance + expected_increment:
+                console.print(f"[green]Payment confirmed.[/green] New balance: [cyan]{new_balance}[/cyan] credits")
+                return
+            if new_balance != last_balance:
+                console.print(f"[dim]Balance updated: {new_balance} credits[/dim]")
+                last_balance = new_balance
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Stopped polling.[/yellow] Run `tl balance` later to check.")
+        return
+    console.print("[yellow]Timed out waiting for payment.[/yellow] Run `tl balance` later to check.")
+
+
+@app.command("history")
+def history_cmd(
+    limit: int = typer.Option(25, "--limit", help="Max rows to show"),
+    offset: int = typer.Option(0, "--offset", help="Offset for pagination"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+) -> None:
+    """Show recent credit top-ups for your organization (free)."""
+    fmt = detect_format(json_output, False, False, False)
+    client = get_client()
+    try:
+        data = client.get("/credit-purchases", params={"limit": limit, "offset": offset})
+    except ApiError as e:
+        handle_api_error(e)
+        return
+    finally:
+        client.close()
+
+    if fmt == "json":
+        print(json.dumps(data, indent=2, default=str))
+        return
+
+    rows = data.get("results", [])
+    if not rows:
+        console.print("[dim]No credit purchases yet. Run `tl credits buy --amount-usd N`.[/dim]")
+        return
+
+    table = Table(title=f"Credit purchases ({data.get('total', len(rows))} total)")
+    table.add_column("Date")
+    table.add_column("USD", justify="right")
+    table.add_column("Credits", justify="right")
+    table.add_column("Status")
+    table.add_column("Invoice")
+    for row in rows:
+        table.add_row(
+            row.get("created_at", "")[:19].replace("T", " "),
+            row.get("usd_amount", ""),
+            row.get("credits", ""),
+            row.get("status", ""),
+            row.get("green_invoice_document_id") or "—",
+        )
+    console.print(table)

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/src/tl_cli/commands/whoami.py

@@ -26,10 +26,13 @@ def _render_whoami(data: dict) -> None:
 
     # --- User ---
     name = f"{user.get('first_name', '')} {user.get('last_name', '')}".strip()
+    email = user.get("email", "")
     title = Text()
-    title.append(name or user.get("email", ""), style="bold cyan")
-    if name:
-        title.append(f"  {user.get('email', '')}", style="dim")
+    if name and email:
+        title.append(f'"{name}"', style="bold cyan")
+        title.append(f" <{email}>", style="dim")
+    else:
+        title.append(f"<{email}>" if email else name, style="bold cyan")
 
     flags = profile.get("flags", [])
     persona = profile.get("persona")
@@ -61,6 +64,10 @@ def _render_whoami(data: dict) -> None:
     if org.get("is_managed_services"):
         org_lines.append("Managed services", style="magenta")
         org_lines.append("\n")
+    if "credits_balance" in org:
+        org_lines.append("Credits: ", style="dim")
+        org_lines.append(f"{org['credits_balance']:g}", style="cyan")
+        org_lines.append("\n")
     start = org.get("contract_start_date")
     end = org.get("contract_end_date")
     if start or end:
@@ -118,9 +125,12 @@ def _render_whoami_md(data: dict) -> None:
     brands = data.get("brands", [])
 
     name = f"{user.get('first_name', '')} {user.get('last_name', '')}".strip()
-    print(f"# {name or user.get('email', '')}\n")
-    if name:
-        print(f"- **Email:** {user.get('email', '')}")
+    email = user.get("email", "")
+    if name and email:
+        header = f'"{name}" <{email}>'
+    else:
+        header = f"<{email}>" if email else name
+    print(f"# {header}\n")
     persona = profile.get("persona")
     if persona:
         print(f"- **Persona:** {persona}")
@@ -136,6 +146,8 @@ def _render_whoami_md(data: dict) -> None:
         print(f"- **Plan:** {plan}")
     if org.get("is_managed_services"):
         print("- **Managed services:** yes")
+    if "credits_balance" in org:
+        print(f"- **Credits:** {org['credits_balance']:g}")
     start = org.get("contract_start_date")
     end = org.get("contract_end_date")
     if start or end:

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/src/tl_cli/main.py

@@ -16,6 +16,8 @@ from tl_cli.commands.ask import app as ask_app
 from tl_cli.commands.balance import app as balance_app
 from tl_cli.commands.changelog import changelog_command
 from tl_cli.commands.brands import app as brands_app
+from tl_cli.commands.bulk_import import bulk_import_command
+from tl_cli.commands.credits import app as credits_app
 from tl_cli.commands.channels import app as channels_app
 from tl_cli.commands.db import app as db_app
 from tl_cli.commands.deals import app as deals_app
@@ -93,12 +95,17 @@ app.add_typer(brands_app, name="brands")
 app.add_typer(recommender_app, name="recommender")
 app.add_typer(snapshots_app, name="snapshots")
 app.add_typer(reports_app, name="reports")
+# Direct command (not a sub-Typer) so `tl bulk-import <entity> --campaign <id>`
+# parses ENTITY as the positional and --campaign as a command option, instead
+# of Typer treating `--campaign` as a group-level flag that has to come first.
+app.command(name="bulk-import")(bulk_import_command)
 app.add_typer(db_app, name="db")
 
 # Discoverability
 app.add_typer(describe_app, name="describe")
 app.add_typer(schema_app, name="schema")
 app.add_typer(balance_app, name="balance")
+app.add_typer(credits_app, name="credits")
 app.add_typer(doctor_app, name="doctor")
 app.add_typer(whoami_app, name="whoami")
 

{thoughtleaders_cli-0.6.24 → thoughtleaders_cli-0.6.26}/src/tl_cli/self_update.py

@@ -115,12 +115,52 @@ def _run_upgrade(method: str, latest: str) -> None:
         f"[tl-cli] upgrading {__version__} → {latest} via {method}…",
         file=sys.stderr,
     )
+    # Capture output so a noisy traceback from a broken upgrader (seen on
+    # Windows pipx shims that lose track of their own module) doesn't get
+    # dumped into the user's shell — we surface it deliberately on failure
+    # alongside an actionable next-step message.
     try:
-        result = subprocess.run(cmd, check=False, timeout=60)
-    except (OSError, subprocess.TimeoutExpired):
+        result = subprocess.run(cmd, check=False, timeout=60, capture_output=True, text=True)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        print(
+            f"[tl-cli] could not run {method}: {exc}\n"
+            f"[tl-cli] upgrade manually with:\n  {' '.join(cmd)}",
+            file=sys.stderr,
+        )
         return
     if result.returncode == 0:
         _resync_integrations()
+        return
+    _report_upgrade_failure(method, cmd, result)
+
+
+def _report_upgrade_failure(method: str, cmd: list[str], result: subprocess.CompletedProcess) -> None:
+    """Print a user-friendly failure message after a non-zero upgrader exit.
+
+    On Windows in particular, `pipx.exe` can be a broken shim that errors
+    with `ModuleNotFoundError: No module named 'pipx'`. We detect that and
+    give a targeted hint instead of just echoing the traceback.
+    """
+    combined_err = (result.stderr or '') + (result.stdout or '')
+    print(
+        f"[tl-cli] automatic upgrade failed (exit {result.returncode}).",
+        file=sys.stderr,
+    )
+    if "No module named 'pipx'" in combined_err:
+        print(
+            "[tl-cli] Your pipx install appears broken (its launcher can't find the pipx module).\n"
+            "[tl-cli] Reinstall pipx from your system Python, then rerun the upgrade.\n"
+            "[tl-cli] Or switch to uv:  uv tool install --force " + cmd[-1],
+            file=sys.stderr,
+        )
+    else:
+        print(
+            f"[tl-cli] To upgrade manually, run:\n  {' '.join(cmd)}",
+            file=sys.stderr,
+        )
+    if combined_err.strip():
+        print("[tl-cli] Upgrader output:", file=sys.stderr)
+        sys.stderr.write(combined_err if combined_err.endswith('\n') else combined_err + '\n')
 
 
 def _resync_integrations() -> None: