thoughtleaders-cli 0.6.25__tar.gz → 0.6.27__tar.gz

{thoughtleaders_cli-0.6.25 → thoughtleaders_cli-0.6.27}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.25 → thoughtleaders_cli-0.6.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.25
+Version: 0.6.27
 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.25 → thoughtleaders_cli-0.6.27}/pyproject.toml

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

{thoughtleaders_cli-0.6.25 → thoughtleaders_cli-0.6.27}/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.27/skills/tl-import/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: tl-import
+description: Import a list of channels, brands, uploads (videos), or sponsorships into a ThoughtLeaders report — either an existing report (caller supplies `campaign_id` or a TL report URL) or a fresh new one (skill creates a minimal container, then populates). Superuser-only. **Trigger on explicit intent to import the listed entities into a report**, NOT on the mere presence of a list (a user can paste a list and want analysis, comparison, or similar-channel discovery — those go to `tl-cli:tl-report-builder` or `tl-cli:tl`). The deciding question is: *would the user be satisfied if those exact entities ended up as the report's contents, no transformation?* If yes, this is the skill. Phrasings: "import these channels into report 1234", "add brands to campaign 5678", "exclude these channels from report Z", "bulk-add these videos to report X", "create a new report with these channels: <list>", "make a campaign containing these brands: <list>".
+---
+
+# tl-import
+
+Imports a list of identifiers (channels / brands / articles / sponsorships) into a report. Two flows depending on whether the user references an existing report or wants a new one — see "Decide which flow" below. Both end in the same step: `tl bulk-import` submits the identifiers, polls until done, and the skill renders a per-row result table.
+
+## When to use
+
+The deciding test is the **user's intent**, not just what they pasted. The user must want the listed entities to land in a report as-given — no filtering, no analysis, no similarity expansion on top.
+
+Trigger on:
+
+- "Import @mkbhd, @veritasium into report 1234" → **existing-report flow**
+- "Add these brands to campaign 5678" → **existing-report flow**
+- "Bulk-add this list of channels to report 999" → **existing-report flow**
+- "Exclude these channels from report Z" → **existing-report flow**
+- "Create a new report with these channels: \<list\>" → **new-report flow**
+- "Make a campaign containing these brands: \<list\>" → **new-report flow**
+- "Build me a report from these adlinks: \<list\>" → **new-report flow** *(the verb "build" doesn't matter — what matters is that the user wants exactly those adlinks in the report.)*
+
+**Do NOT trigger** when the user pastes a list but wants something other than direct import — those belong to `tl-cli:tl-report-builder` or `tl-cli:tl`:
+
+- *"Find me channels similar to these: \<list\>"* — discovery using the list as a seed, not as the answer.
+- *"Build a report of TPP channels in the same niche as these: \<list\>"* — discovery with filters and similarity expansion.
+- *"Compare engagement across these channels"* — analysis on top of the list.
+- *"Show me which of these have sponsored fintech brands"* — filtered lookup.
+
+If you're about to do anything beyond "put these exact entities into a report", the wrong skill is running.
+
+Single-identifier requests still work for the import intent (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.
+
+## Decide which flow
+
+Look at the user's request and pick exactly one of three responses:
+
+| Signal | Response |
+|---|---|
+| User references an existing report (campaign ID number, `?campaign=<id>` in a pasted URL, "report X", "this campaign") | **Existing-report flow** — skip to "Inputs to gather" |
+| User explicitly asks for a new report ("new report", "a new campaign", "create a report with…", "make a campaign of…") | **New-report flow** — read "Create a fresh container first" below, then continue |
+| User provides a list with no destination cue at all (no campaign reference AND no "new" wording) | **Ambiguous — ask once** before proceeding: *"Should I add these to an existing report (give me the report ID or URL), or create a new one?"* Wait for the answer. Then dispatch to the matching flow above. |
+
+Never silently create a new report when the destination is ambiguous; never silently use an existing report when none was referenced. The skill's only acceptable action without a clear destination is to ask.
+
+## Create a fresh container first (new-report flow only)
+
+The user wants the report to contain exactly the identifiers they're about to import — nothing else. No keyword research, no discovery query, no review pipeline. Just a minimal container that holds the list. **The persistence step uses the same primitive `tl-cli:tl-report-builder` calls at the end of its workflow** (`tl reports create --config-file`), but with a tiny config and none of the upstream phases.
+
+Steps:
+
+1. **Title.** If the user gave one (e.g. *"create a Q1 cohort report with…"* → title *"Q1 cohort"*), use it. Otherwise ask once: *"What should I name the new report?"* Title must be ≤ 60 chars, non-empty.
+2. **Description.** Auto-generate a 1-sentence description; don't ask the user. Format: `"Bulk-imported list of <N> <entity> (<YYYY-MM-DD>)."`. Required by the platform on save (not optional).
+3. **Map entity → `report_type`:**
+   - `channels` → **3** (THOUGHTLEADERS)
+   - `brands` → **2** (BRANDS)
+   - `articles` (uploads/videos) → **1** (CONTENT)
+   - `sponsorships` (adlinks/deals) → **8** (CAMPAIGN_MANAGEMENT)
+4. **Pick default columns.** Read the matching columns reference file in the sibling `tl-report-builder` skill and use its **"always include"** defaults — do NOT duplicate the list inline here, that's where the canonical default lives:
+   - channels → `../tl-report-builder/references/columns_channels.md` (look for the "Defaults — always include" section)
+   - brands → `../tl-report-builder/references/columns_brands.md`
+   - articles → `../tl-report-builder/references/columns_content.md`
+   - sponsorships → `../tl-report-builder/references/columns_sponsorships.md`
+
+   Convert the column display names into the dict shape: `{"Channel": {"display": true}, "TL Channel Summary": {"display": true}, …}`.
+5. **Compose the minimal config:**
+
+   ```json
+   {
+     "report_title": "<from step 1>",
+     "report_description": "<from step 2>",
+     "report_type": <from step 3>,
+     "type": 2,
+     "filterset": {},
+     "columns": <from step 4>
+   }
+   ```
+
+   `type: 2` is DYNAMIC (the only valid campaign type for save). `filterset: {}` is intentional — no keyword/topic/demographic filters; the report's contents will come entirely from the include list bulk-import populates next.
+6. **Persist via the same primitive `tl-report-builder` uses.** Write the config dict to a temp file using your file-writing tool — **do not use shell `echo` or heredocs**, those break on titles containing apostrophes, dollar signs, backticks, etc. The whole point of `--config-file` is to bypass shell quoting entirely. Pick any temp path the agent's filesystem tool can write to (e.g. `/tmp/tl-import-container.json` on Unix, the OS temp dir on Windows).
+
+   Then run:
+
+   ```bash
+   tl reports create --config-file <path-you-just-wrote> --yes --json
+   ```
+
+   With `--yes --json` the CLI emits a single JSON document on stdout containing the save response — parse it with one `json.loads()` and pull out `campaign_id` (and `report_url` for the summary). If `tl reports create` returns HTTP 400 with `Missing required field: report_title` or `…report_description`, the config is malformed — re-check step 1/2.
+
+7. **Hand off to bulk-import** using the new `campaign_id` as if the user had supplied it. Continue with "Inputs to gather" and the rest of this skill below.
+
+Surface the new report URL alongside the bulk-import results in the final summary, e.g. *"Created [Q1 cohort](https://app.thoughtleaders.io/#/thoughtleaders?campaign=23859) and imported 50 channels:"* followed by the per-row table.
+
+## 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. In the new-report flow, use the `campaign_id` returned by `tl reports create` above.
+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 run `tl-report-builder`'s discovery pipeline (keyword research, topic matching, validation cycles, review). When a user gives a fixed list of identifiers, they've already done the discovery themselves — the report is a container for their list, not a query result. Use `tl-report-builder` only when the user wants you to *find* channels/brands/etc. by criteria.
+- Doesn't change existing report metadata (title, description, columns, filters) after creation. For that, use the platform UI or a dedicated edit flow. The new-report flow in this skill sets minimum-required metadata once at creation and never revisits it.
+- 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.25 → thoughtleaders_cli-0.6.27}/skills/tl-report-builder/SKILL.md

@@ -13,7 +13,15 @@ description: |
 
   Save-intent variants ("save a campaign of …", "create the report …", "make a TL report for …") trigger auto-save; everything else previews. Off-taxonomy keywords ("crypto / Web3"), brand-exclusion logic ("not pitched to X"), demographic floors ("US audience ≥30%"), TPP/MSN scoping, and competitive-pitch shapes are all this skill's job — not the general `tl-cli:tl` data-analyst skill.
 
-  **Skip this skill** only for: counts, metrics, trends, single-record show-by-ID lookups, raw exploratory queries, or analytical questions that aren't shaped as "give me a list". Those go to `tl-cli:tl`.
+  **Skip this skill** for:
+  - counts, metrics, trends, single-record show-by-ID lookups, raw exploratory queries, or analytical questions that aren't shaped as "give me a list" → route to `tl-cli:tl`.
+  - **explicit intent to import a list of identifiers into a report — existing or new.** The routing test is the **user's import intent**, NOT the mere presence of a list. A user can paste 50 channel URLs and want analysis, comparison, similar-channel discovery, or filtered lookup — those still belong here (or in `tl-cli:tl`), not in tl-import. They can also paste 50 URLs and want exactly those channels to land in a report as-given — that is import, route to `tl-cli:tl-import`. The deciding question: *"Would the user be satisfied if the listed entities simply ended up as the report's contents exactly as-given, no transformation?"* If yes → import intent → `tl-cli:tl-import`. If they expect filtering, analysis, similarity expansion, or any other transformation on top of the list → it's not import, keep it here.
+
+    Concrete phrasings that route to `tl-cli:tl-import` (intent: import + list = report contents): *"import these channels into report 1234"*, *"add these brands to campaign 5678"*, *"create a new report with these channels: <list>"*, *"build me a campaign from these adlinks: <list>"*, *"make a report containing these uploads: <list>"*.
+
+    Phrasings that **stay here** even with a list attached (intent: discovery / analysis using the list as input, not as the answer): *"find me channels similar to these: <list>"*, *"build a report of TPP channels in the same niche as these: <list>"*, *"show me which of these have sponsored fintech brands"*, *"compare engagement across these channels"*.
+
+    If you find yourself about to resolve a URL/handle to a channel ID *as the deliverable* (no analysis, no filtering, no discovery on top), stop and hand off — that's the import shape.
 ---
 
 # TL Report Builder Skill

{thoughtleaders_cli-0.6.25 → thoughtleaders_cli-0.6.27}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.25 → thoughtleaders_cli-0.6.27}/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.27/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.25 → thoughtleaders_cli-0.6.27}/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.25 → thoughtleaders_cli-0.6.27}/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")