thoughtleaders-cli 0.6.0__tar.gz → 0.6.2__tar.gz

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/AGENTS.md

@@ -20,7 +20,7 @@ When adding a new data command, follow this pattern. See `sponsorships.py` for t
 
 `deals`, `matches`, and `proposals` are shortcut commands that delegate to sponsorships' `do_list`/`do_show`/`do_create` with a pre-set status filter. They reject explicit `status:` filters — users should use `tl sponsorships list` for finer-grained status filtering.
 
-`recommender` (`commands/recommender.py`) wraps the vector-recommender API at `/api/cli/v1/recommender/*` — `tags` (free), `top`, `inspect-channel`, `inspect-brand`, `similar-to-profile` (all 50 credits flat, Intelligence-gated). Channel→channel and brand→brand similarity stay on `tl channels similar` / `tl brands similar`. When updating the SKILL or examples, prefer steering category/topic discovery (e.g. "Cooking channels") to `tl recommender top "<tag>"` rather than `WHERE content_category = <code>` SQL — the recommender is ranked, not equality-based, and returns matching brand profiles alongside channels. The underlying recommender code uses "element"/"field_name" terminology; the CLI/API layer renames these to "tag" at the boundary.
+`recommender` (`commands/recommender.py`) wraps the vector-recommender API at `/api/cli/v1/recommender/*` — `tags` (free), `top-channels` / `top-profiles` / `top-brands`, `inspect-channel`, `inspect-brand`, `similar-to-profile` (all 50 credits flat, Intelligence-gated). The three `top-*` URLs share one server resolver; `top-brands` dedupes the underlying profile rows by brand. Channel→channel and brand→brand similarity stay on `tl channels similar` / `tl brands similar`. When updating the SKILL or examples, prefer steering category/topic discovery (e.g. "Cooking channels") to `tl recommender top-channels "<tag>"` rather than `WHERE content_category = <code>` SQL — the recommender is ranked, not equality-based. The underlying recommender code uses "element"/"field_name" terminology; the CLI/API layer renames these to "tag" at the boundary.
 
 ## Filter Parsing (`filters.py`)
 

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.0
+Version: 0.6.2
 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
@@ -83,14 +83,17 @@ tl uploads show 1174310:0BehkmVa7ak
 
 # Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
 # (run `tl schema pg` once to confirm the live column set).
+# NOTE: For topic / category discovery, prefer the vector recommender over
+# `content_category` equality — `tl recommender top-channels "<tag>"`
+# returns channels ranked by how strongly they load on the topic, not just
+# rows where the single category code matches exactly.
 tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
           WHERE content_category = <COOKING_CODE> AND total_views >= 100000
           ORDER BY total_views DESC LIMIT 50 OFFSET 0"
 tl db pg "SELECT id, channel_name FROM thoughtleaders_channel
           WHERE is_tl_channel = TRUE LIMIT 200 OFFSET 0"             # all TPP channels (~169)
-# MSN status (media_selling_network_join_date) is scrubbed from the
-# advertiser sandbox view — for MSN-only / non-MSN lookups, the
-# structured filter is the right tool: `tl channels list msn:yes|no`.
+# MSN status: filter on `media_selling_network_join_date IS [NOT] NULL`
+# in the same raw SQL query (column is scrubbed from advertiser sandboxes).
 
 # Show channel detail — accepts numeric ID or channel name.
 # Names that match more than one active channel print a candidate list
@@ -109,8 +112,9 @@ tl channels similar "Tremending girls" min-score:0.85 --limit 5
 # `tags` is free; `top`, `inspect-*`, and `similar-to-profile` cost 50 credits flat.
 tl recommender tags                              # List every tag (free)
 tl recommender tags cooking                      # Search tag names by substring
-tl recommender top "Cooking" msn:yes --limit 50  # Top channels & brand profiles for a tag
-tl recommender top "USA share" mbn:yes           # Demographic tag, MBN brands only
+tl recommender top-channels "Cooking" msn:yes --limit 50  # Top channels for a tag
+tl recommender top-profiles "Cooking" mbn:yes --limit 30  # Top brand profiles (one brand → potentially multiple profiles)
+tl recommender top-brands "Cooking" --limit 30            # Top brands (deduped from profiles)
 tl recommender inspect-channel 12345             # Per-tag breakdown of a channel's vector
 tl recommender inspect-brand Nike                # Per-tag breakdown of a brand's ideal vector
 tl recommender similar-to-profile 842            # Channels closest to a brand profile

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/README.md

@@ -56,14 +56,17 @@ tl uploads show 1174310:0BehkmVa7ak
 
 # Search channels via raw SQL — `tl db pg` against thoughtleaders_channel
 # (run `tl schema pg` once to confirm the live column set).
+# NOTE: For topic / category discovery, prefer the vector recommender over
+# `content_category` equality — `tl recommender top-channels "<tag>"`
+# returns channels ranked by how strongly they load on the topic, not just
+# rows where the single category code matches exactly.
 tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
           WHERE content_category = <COOKING_CODE> AND total_views >= 100000
           ORDER BY total_views DESC LIMIT 50 OFFSET 0"
 tl db pg "SELECT id, channel_name FROM thoughtleaders_channel
           WHERE is_tl_channel = TRUE LIMIT 200 OFFSET 0"             # all TPP channels (~169)
-# MSN status (media_selling_network_join_date) is scrubbed from the
-# advertiser sandbox view — for MSN-only / non-MSN lookups, the
-# structured filter is the right tool: `tl channels list msn:yes|no`.
+# MSN status: filter on `media_selling_network_join_date IS [NOT] NULL`
+# in the same raw SQL query (column is scrubbed from advertiser sandboxes).
 
 # Show channel detail — accepts numeric ID or channel name.
 # Names that match more than one active channel print a candidate list
@@ -82,8 +85,9 @@ tl channels similar "Tremending girls" min-score:0.85 --limit 5
 # `tags` is free; `top`, `inspect-*`, and `similar-to-profile` cost 50 credits flat.
 tl recommender tags                              # List every tag (free)
 tl recommender tags cooking                      # Search tag names by substring
-tl recommender top "Cooking" msn:yes --limit 50  # Top channels & brand profiles for a tag
-tl recommender top "USA share" mbn:yes           # Demographic tag, MBN brands only
+tl recommender top-channels "Cooking" msn:yes --limit 50  # Top channels for a tag
+tl recommender top-profiles "Cooking" mbn:yes --limit 30  # Top brand profiles (one brand → potentially multiple profiles)
+tl recommender top-brands "Cooking" --limit 30            # Top brands (deduped from profiles)
 tl recommender inspect-channel 12345             # Per-tag breakdown of a channel's vector
 tl recommender inspect-brand Nike                # Per-tag breakdown of a brand's ideal vector
 tl recommender similar-to-profile 842            # Channels closest to a brand profile

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/commands/tl.md

@@ -18,8 +18,8 @@ The user wants to query ThoughtLeaders data. Translate their request into the ri
 ## Examples
 
 - "/tl sold sponsorships for Nike in Q1" → `tl sponsorships list status:sold brand:"Nike" purchase-date-start:2026-01-01 purchase-date-end:2026-03-31`
-- "/tl cooking channels over 100k subs" → `tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel WHERE content_category = <COOKING_CODE> AND total_views >= 100000 ORDER BY total_views DESC LIMIT 50 OFFSET 0"`
-- "/tl mobile-first US cooking channels" → `tl db pg "SELECT id, channel_name, demographic_usa_share FROM thoughtleaders_channel WHERE content_category = <COOKING_CODE> AND demographic_device_primary = 'mobile' AND demographic_usa_share >= 50 ORDER BY total_views DESC LIMIT 50 OFFSET 0"`
+- "/tl cooking channels over 100k subs" → `tl recommender top-channels "cooking" --limit 50` (then post-filter by `subscribers >= 100000` on the resulting IDs)
+- "/tl mobile-first US cooking channels" → `tl recommender top-channels "cooking" --limit 100` (then narrow by `demographic_device_primary = 'mobile'` / `demographic_usa_share >= 50` with raw SQL on the resulting IDs)
 - "/tl Nike's sponsorship activity" → `tl brands show Nike`
 - "/tl run my Q1 report" → `tl reports --json` then `tl reports run <id>`
 - "/tl check my balance" → `tl balance`

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/docs/architecture.md

@@ -48,7 +48,6 @@ All data commands use explicit subcommands: `list`, `show`, `create`/`add`. Runn
 | `tl proposals create --channel <id> --brand <id>` | Create a proposal (free) |
 | `tl uploads list [filters...]` | List video uploads (ES) |
 | `tl uploads show <id> [<id>...]` | Show upload detail(s) by ID |
-| `tl channels list [filters...]` | Search channels. Responses carry boolean `msn` (Media Selling Network) and `tpp` (TL-managed) fields; filterable via `msn:` / `tpp:` tri-state (`yes` / `no` / `both`, default `both`). |
 | `tl channels show <id-or-name>` | Channel detail, including active adspots with price/cost/CPM |
 | `tl channels history <id-or-name>` | Sponsorship history (videos with detected sponsors) |
 | `tl channels similar <id-or-name>` | Vector-similarity recommender. 50 credits; Intelligence plan. Tri-state `msn:` (default `yes`) and `tpp:` (default `both`) filters. Ambiguous names return 400 + candidates list. Hidden `look-alike` alias. |
@@ -75,8 +74,10 @@ Filters are passed as `key:value` pairs after `list`:
 tl sponsorships list status:sold brand:"Nike" purchase-date:2026-01
 tl sponsorships list status:pending send-date:2026-03
 tl uploads list channel:12345 type:longform since:2026-03
-# Channel discovery is raw SQL — the structured `tl channels list` covers
-# only narrow lookups. Default to:
+# Channel discovery is raw SQL — default to:
+# (For topic/category lookups, `tl recommender top-channels "<tag>"` is a
+# better starting point than `content_category` equality — it ranks by
+# how strongly each channel loads on the topic, not exact-match.)
 tl db pg "SELECT id, channel_name, total_views FROM thoughtleaders_channel
           WHERE content_category = <COOKING_CODE> AND language = 'en'
             AND total_views >= 1000000
@@ -387,7 +388,6 @@ Most CLI endpoints can reuse existing views/utilities rather than being built fr
 | **`POST /api/cli/v1/sponsorships`** | `api/create-bulk-proposal` (`CreateBulkProposalView`) + MCP `save_proposals_for_email` in `mcp/proposals.py` | Adapt for single-proposal creation from CLI params |
 | **`GET /api/cli/v1/uploads`** | `api/articles` (`ArticlesView`) — full ES article search with configurable columns, filters, aggregation. Already handles channel format, brand filters, content type. | Translate CLI filters → ArticlesView params. Restrict to VIDEO format. |
 | **`GET /api/cli/v1/uploads/<id>`** | `api/articles/<id>` (`SingleArticleView`) | Add CLI envelope |
-| **`GET /api/cli/v1/channels`** | `api/v2/external-youtube-thoughtleaders` (`ExternalYoutubeThoughtleadersView`) — rich ES-powered channel search with configurable columns, aggregation. Also `api/v1/channels/dropdown` for simple name search. | Translate CLI filters → existing view params |
 | **`GET /api/cli/v1/channels/<id>`** | `api/v1/channels/<id>` (`ChannelAPIViewSet.retrieve`) — returns channel detail with loyalty metrics | Add CLI envelope + breadcrumbs linking to snapshots |
 | **`GET /api/cli/v1/brands/<query>`** | `api/v1/brands` (`BrandsViewSet`) for brand lookup + `api/articles` with `sponsored_brand_mentions` filter for intelligence data. Also `api/brand/<id>/matcher` (`BrandChannelMatcherAPI`) for channel discovery. | Combine brand lookup + ES brand mention query |
 | **`GET /api/cli/v1/snapshots/channel/<id>`** | `api/v2/channel-history` (`ChannelHistoryView`) — already queries Firebolt `channel_metrics` with pagination, uses `get_firebolt_query_results()` utility. Also `api/v2/external-channel-total-views` for time-series with granularity. | Direct reuse — just translate params + add CLI envelope |

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/pyproject.toml

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

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/skills/tl/SKILL.md

@@ -95,7 +95,7 @@ When querying sponsorship bookings, query by `status:sold` and filter the the da
 
 Where possible, if searching for a sponsorship match between channels and brands, first search for what do similar brands sponsor / which brands is the channel usually sponsored by. The similarity judgement should be preferably based on similar topics, similar upload frequency, similar channel sizes, and only after all that, on demographics.
 
-Use the `tl channels similar` and `tl brands similar` commands to explore 1:1 similarity between known channels or brands. For category- or topic-driven discovery (e.g. "find me Cooking channels", "who scores high on USA share?"), use `tl recommender top "<tag>"` against the vector recommender — that's faster, ranked by category-strength, and returns both channels and matching brand profiles. Run `tl recommender tags` to discover the valid tag names.
+Use the `tl channels similar` and `tl brands similar` commands to explore 1:1 similarity between known channels or brands. For category- or topic-driven discovery (e.g. "find me Cooking channels", "who scores high on USA share?"), use `tl recommender top-channels "<tag>"` (or `top-brands`/`top-profiles`) against the vector recommender — that's faster, ranked by category-strength. Run `tl recommender tags` to discover the valid tag names.
 
 ## Workflow
 
@@ -130,8 +130,7 @@ tl proposals show <id>                 # Proposal detail (2 credits)
 tl proposals create --channel <id> --brand <id>  # Create proposal (free)
 tl uploads list [filters...]           # Video uploads from ES — list curve, mult 1.0
 tl uploads show <id>                   # Upload detail (2 credits)
-tl channels list [filters...]          # Channel search — list curve, mult 1.0
-tl channels show <id-or-name>          # Channel detail (2 credits; accepts numeric ID or name)
+tl channels show <id-or-name>          # Channel detail (2 credits; accepts numeric ID or name) — for channel search use raw SQL on thoughtleaders_channel
 tl channels history <id-or-name>       # Sponsorship history (5 credits/result, linear)
 tl channels similar <id-or-name>       # Vector-similarity recommender (50 credits flat; Intelligence plan)
 tl brands show <id-or-name>            # Brand detail (1 credit)
@@ -139,7 +138,9 @@ tl brands history <id-or-name>         # Sponsorship history (5 credits/result,
 tl brands history <query> --channel <id>  # Brand mentions on specific channel
 tl brands similar <id-or-name>         # Find similar brands via profile vector KNN (50 credits flat)
 tl recommender tags [query]            # List vector tag names — categories, demographics, formats (free)
-tl recommender top "<tag>"             # Top channels & profiles loaded on a vector tag (50 credits; Intelligence)
+tl recommender top-channels "<tag>"    # Top channels loaded on a vector tag (50 credits; Intelligence)
+tl recommender top-profiles "<tag>"    # Top brand profiles loaded on a vector tag (50 credits)
+tl recommender top-brands "<tag>"      # Top brands (deduped from profiles) loaded on a vector tag (50 credits)
 tl recommender inspect-channel <ref>   # Show a channel's feature-vector breakdown (50 credits; Intelligence)
 tl recommender inspect-brand <ref>     # Show a brand profile's ideal-vector breakdown (50 credits; Intelligence)
 tl recommender similar-to-profile <id> # Channels closest to a brand profile's ideal vector (50 credits; Intelligence)
@@ -153,7 +154,7 @@ tl comments add <adlink-id> "msg"      # Add comment (free)
 
 **"List curve"** above means non-linear pricing: `cost = 1 + mult × 0.126 × n^1.2`. The flat 1-credit setup applies to every list call; the `mult` reflects per-resource complexity. `tl db {pg,fb,es}` shares the same curve at mult=1.4. Concrete totals:
 
-| Rows | mult=1.0 (channels, brands, comments, uploads, sponsorships) | mult=1.2 (snapshots) | mult=1.3 (reports) | mult=1.4 (db.pg / db.fb / db.es) |
+| Rows | mult=1.0 (comments, uploads, sponsorships) | mult=1.2 (snapshots) | mult=1.3 (reports) | mult=1.4 (db.pg / db.fb / db.es) |
 |---:|---:|---:|---:|---:|
 | 1 | 1 | 1 | 1 | 1 |
 | 10 | 3 | 3 | 4 | 4 |
@@ -332,9 +333,9 @@ tl recommender tags cooking
 tl recommender tags "usa"
 
 # Top channels & profiles loaded on a vector tag (50 credits; Intelligence)
-tl recommender top "Cooking" msn:yes --limit 50
-tl recommender top "Tech" --limit 30
-tl recommender top "USA share" mbn:yes --limit 50
+tl recommender top-channels "Cooking" msn:yes --limit 50
+tl recommender top-channels "Tech" --limit 30
+tl recommender top-brands "USA share" mbn:yes --limit 50
 ```
 
 Use `tl db pg` only for predicates the recommender can't express — pure attribute filters (`is_tl_channel`, `language`, `demographic_device_primary`), aggregations, and joins. Run `tl schema pg` once to confirm the live column set; the columns referenced below are stable.
@@ -358,7 +359,7 @@ tl db pg "SELECT id, channel_name, demographic_device_primary, total_views
 
 For per-country share beyond the recommender's "USA share" tag, use the `demographic_geo` jsonb in raw SQL: `(demographic_geo->>'gb')::int >= 25`. Same pattern with `demographic_device->>'mobile'` for non-primary device shares.
 
-**MSN status (`media_selling_network_join_date`) is scrubbed from the advertiser sandbox view.** Raw SQL can't filter on it from an advertiser context; use the structured `tl channels list msn:yes|no|both` for MSN-specific lookups, then drop down to SQL on the resulting IDs (`WHERE id IN (...)`) for further analysis.
+**MSN status (`media_selling_network_join_date`) is scrubbed from the advertiser sandbox view.** Raw SQL can't filter on it from an advertiser context. For MSN-only / non-MSN lookups, run the same raw SQL with `media_selling_network_join_date IS [NOT] NULL` from a context that has access to it (full-access role), or rely on the recommender's MSN-aware filters: `tl recommender top-channels "<tag>" msn:yes|no|all`.
 
 ### Output flags
 - `--json` — structured JSON (use this for parsing)
@@ -396,7 +397,7 @@ Every query costs credits. Before running expensive queries:
 Users only see data their plan allows:
 - **Media buyers** see deals where their org is the brand. They see `price` but never `cost`.
 - **Media sellers** see deals where their org is the publisher. They see `cost` but never `price`.
-- **Intelligence plan** required for `tl brands`, full `tl channels list` search, and full `tl uploads list`.
+- **Intelligence plan** required for `tl brands`, the full `tl recommender` surface, and full `tl uploads list`.
 - **Paid plan** required for `tl snapshots`.
 
 ## Important: Status Labels
@@ -434,8 +435,8 @@ tl reports run 42 --json
 "Find Cooking channels with US-heavy mobile audiences":
 ```bash
 # Use the vector recommender for the topic, then narrow with structured filters / SQL on the IDs.
-tl recommender top "Cooking" msn:yes --limit 100 --json \
-  | jq -r '.results[] | select(.kind=="channel") | .channel_id' \
+tl recommender top-channels "Cooking" msn:yes --limit 100 --json \
+  | jq -r '.results[].channel_id' \
   | paste -sd, - \
   | xargs -I {} tl db pg "SELECT id, channel_name, total_views, demographic_usa_share
                           FROM thoughtleaders_channel
@@ -467,9 +468,10 @@ tl channels similar 29834 min-subs:1000000 exclude:477487 --limit 15  # client-s
 ```bash
 tl recommender tags                                            # Full tag list (free)
 tl recommender tags cooking                                    # Search tag names by substring
-tl recommender top "Cooking" msn:yes --limit 50                # Top channels & profiles loaded on a tag (50 credits)
-tl recommender top "USA share" mbn:yes --limit 30              # Demographic tag — MBN brands only
-tl recommender top "Tech" exclude-for-profile:842              # Drop channels already proposed for profile 842
+tl recommender top-channels "Cooking" msn:yes --limit 50       # Top channels loaded on a tag (50 credits)
+tl recommender top-profiles "Cooking" --limit 30               # Top brand profiles for the tag
+tl recommender top-brands "USA share" mbn:yes --limit 30       # Top brands (deduped) — demographic tag, MBN only
+tl recommender top-channels "Tech" exclude-for-profile:842     # Drop channels already proposed for profile 842
 tl recommender inspect-channel 29834                           # Per-tag breakdown of a channel's vector
 tl recommender inspect-brand Nike                              # Per-tag breakdown of a brand's ideal vector
 tl recommender similar-to-profile 842 --limit 30               # Channels closest to a brand profile's ideal vector

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/skills/tl/references/firebolt-schema.md

@@ -117,8 +117,8 @@ Every Firebolt workflow has two steps:
 
 ```bash
 # Channels matching some category (vector recommender — preferred over content_category equality)
-tl recommender top "Tech" msn:yes --limit 50 --json \
-  | jq '.channels[].channel_id'
+tl recommender top-channels "Tech" msn:yes --limit 50 --json \
+  | jq '.results[].channel_id'
 
 # Or videos for a specific brand's deals (Postgres side, via tl sponsorships)
 tl deals list brand:"Nike" --json --limit 500 \

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/src/tl_cli/commands/channels.py

@@ -11,7 +11,7 @@ from tl_cli.filters import parse_filters
 from tl_cli.hints import detail_hint
 from tl_cli.output.formatter import detect_format, output, output_single
 
-app = typer.Typer(help="YouTube channels (search, detail, and similar-channel recommendations)")
+app = typer.Typer(help="YouTube channels (detail, history, and similar-channel recommendations)")
 
 # Columns for the `similar` endpoint result table. The server enriches every
 # row so the user can size up each suggestion without follow-up queries.
@@ -25,50 +25,6 @@ SIMILAR_COLUMN_CONFIG = {
 }
 
 
-@app.callback(invoke_without_command=True)
-def channels(ctx: typer.Context) -> None:
-    """YouTube channels — search and detail."""
-    if ctx.invoked_subcommand is None:
-        ctx.invoke(list_cmd, args=[], json_output=False, csv_output=False, md_output=False, limit=50, offset=0)
-
-
-@app.command("list")
-def list_cmd(
-    args: list[str] = typer.Argument(None, help="Filters (key:value pairs). Run 'tl describe show channels' for available filters."),
-    json_output: bool = typer.Option(False, "--json", help="JSON output"),
-    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
-    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
-    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
-    limit: int = typer.Option(50, "--limit", "-l", help="Max results"),
-    offset: int = typer.Option(0, "--offset", help="Pagination offset"),
-) -> None:
-    """Search channels with optional filters.
-
-    Examples:
-        tl channels list                                  # List channels
-        tl channels list category:cooking min-subs:100k   # Search with filters
-    """
-    fmt = detect_format(json_output, csv_output, md_output, toon_output)
-    filters = parse_filters(args or [])
-
-    client = get_client()
-    try:
-        params = {**filters, "limit": str(limit), "offset": str(offset)}
-        data = client.get("/channels", params=params)
-        for r in data.get("results", []):
-            r["channel_id"] = r.pop("id", None)
-        output(
-            data,
-            fmt,
-            columns=["channel_id", "name", "url", "msn", "tpp", "subscribers", "gender", "countries", "category", "sponsorship_score", "trend"],
-            title="Channels",
-        )
-    except ApiError as e:
-        handle_api_error(e)
-    finally:
-        client.close()
-
-
 @app.command("show")
 def show_cmd(
     channel_ref: str = typer.Argument(..., help="Channel ID (numeric) or name (partial match, must be unique)"),

{thoughtleaders_cli-0.6.0 → thoughtleaders_cli-0.6.2}/src/tl_cli/commands/recommender.py

@@ -19,10 +19,12 @@ from tl_cli.client.http import get_client
 from tl_cli.filters import parse_filters
 from tl_cli.output.formatter import detect_format, output, output_single
 
-app = typer.Typer(help="Vector recommender (tags, top-by-tag, vector inspection, profile→channel similarity)")
+app = typer.Typer(help="Vector recommender (tags, top-channels/profiles/brands, vector inspection, profile→channel similarity)")
 
 
-TOP_COLUMNS = ["kind", "value", "channel_id", "profile_id", "name", "brand_name", "slug"]
+TOP_CHANNEL_COLUMNS = ["value", "channel_id", "channel_name", "slug"]
+TOP_PROFILE_COLUMNS = ["value", "profile_id", "profile_email", "brand_name", "brand_slug"]
+TOP_BRAND_COLUMNS = ["value", "brand_slug", "brand_name", "profile_id"]
 TOP_COLUMN_CONFIG = {"value": {"justify": "right"}}
 
 
@@ -70,7 +72,7 @@ def tags_cmd(
         tl recommender tags "age 18"
     """
     fmt = detect_format(json_output, csv_output, md_output, toon_output)
-    query = " ".join(args or []).strip()
+    query = _strip_quotes(" ".join(args or []).strip())
     params = {"q": query} if query else {}
     client = get_client()
     try:
@@ -78,7 +80,7 @@ def tags_cmd(
         output(
             data,
             fmt,
-            columns=["group", "field_name", "normalized_name"],
+            columns=["group", "field_name"],
             title="Recommender vector tags",
         )
     except ApiError as e:
@@ -87,36 +89,21 @@ def tags_cmd(
         client.close()
 
 
-@app.command("top")
-def top_cmd(
-    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
-    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
-    json_output: bool = typer.Option(False, "--json", help="JSON output"),
-    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
-    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
-    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
-    limit: int = typer.Option(50, "--limit", "-l", help="Max results per group (1-100)"),
-) -> None:
-    """Top channels and profiles loaded on a single vector tag.
+def _strip_quotes(value: str) -> str:
+    """Strip one matching pair of surrounding quotes if present.
 
-    Costs 50 credits per call. Intelligence plan required. Returns both
-    channels and profiles ranked by the tag's value (descending).
+    Lets users paste an example like `tl recommender top-channels "cooking"`
+    where the shell already strips quotes, but also tolerates a layer of
+    extra quoting from agents or scripts that re-wrap the literal.
+    """
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+        return value[1:-1]
+    return value
 
-    Filters:
-        msn:<yes|no|all>            MSN membership for channel rows (default: all)
-        mbn:<yes|no|all>            MBN membership for profile rows (default: all)
-        exclude-for-channel:<id>    Drop profiles already proposed for this channel
-        exclude-for-profile:<id>    Drop channels already proposed for this profile
 
-    Examples:
-        tl recommender top "Cooking"
-        tl recommender top "Tech" msn:yes --limit 30
-        tl recommender top "USA share" mbn:yes
-        tl recommender top "Cooking" exclude-for-profile:842
-    """
-    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+def _do_top(kind: str, tag: str, args: list[str], fmt: str, limit: int, columns: list[str], title: str) -> None:
+    tag = _strip_quotes(tag)
     filters = parse_filters(args or [])
-
     server_keys = {"msn", "mbn", "exclude-for-channel", "exclude-for-profile"}
     params = {k: v for k, v in filters.items() if k in server_keys}
     params["tag"] = tag
@@ -124,15 +111,12 @@ def top_cmd(
 
     client = get_client()
     try:
-        data = client.get("/recommender/top", params=params)
-        rows = data.get("results", [])
-        for r in rows:
-            r["name"] = r.get("channel_name") or r.get("profile_email") or ""
+        data = client.get(f"/recommender/top/{kind}", params=params)
         output(
             data,
             fmt,
-            columns=TOP_COLUMNS,
-            title=f"Top by tag: {tag}",
+            columns=columns,
+            title=title,
             column_config=TOP_COLUMN_CONFIG,
         )
     except ApiError as e:
@@ -141,6 +125,89 @@ def top_cmd(
         client.close()
 
 
+@app.command("top-channels")
+def top_channels_cmd(
+    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Top channels loaded on a single vector tag.
+
+    Costs 50 credits per call. Intelligence plan required.
+
+    Filters:
+        msn:<yes|no|all>            MSN membership (default: all)
+        exclude-for-profile:<id>    Drop channels already proposed for this profile
+
+    Examples:
+        tl recommender top-channels "Cooking"
+        tl recommender top-channels "Tech" msn:yes --limit 30
+        tl recommender top-channels "Cooking" exclude-for-profile:842
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    _do_top("channels", tag, args or [], fmt, limit, TOP_CHANNEL_COLUMNS, f"Top channels: {tag}")
+
+
+@app.command("top-profiles")
+def top_profiles_cmd(
+    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Top brand profiles loaded on a single vector tag.
+
+    Costs 50 credits per call. Intelligence plan required. Profiles can
+    represent the same brand more than once (one brand → multiple
+    profiles); use `top-brands` for brand-deduplicated results.
+
+    Filters:
+        mbn:<yes|no|all>            MBN membership (default: all)
+        exclude-for-channel:<id>    Drop profiles already proposed for this channel
+
+    Examples:
+        tl recommender top-profiles "Cooking"
+        tl recommender top-profiles "USA share" mbn:yes --limit 30
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    _do_top("profiles", tag, args or [], fmt, limit, TOP_PROFILE_COLUMNS, f"Top profiles: {tag}")
+
+
+@app.command("top-brands")
+def top_brands_cmd(
+    tag: str = typer.Argument(..., help='Vector tag name (e.g. "Cooking", "Age 18-24"). Run `tl recommender tags` to discover valid names.'),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs)."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Top brands loaded on a single vector tag (deduplicated from profiles).
+
+    Costs 50 credits per call. Intelligence plan required. Server-side
+    aggregates the underlying profile rows by brand, keeping the
+    highest-scoring profile per brand.
+
+    Filters:
+        mbn:<yes|no|all>            MBN membership of the underlying profile (default: all)
+        exclude-for-channel:<id>    Drop brands already proposed for this channel
+
+    Examples:
+        tl recommender top-brands "Cooking"
+        tl recommender top-brands "USA share" mbn:yes --limit 30
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    _do_top("brands", tag, args or [], fmt, limit, TOP_BRAND_COLUMNS, f"Top brands: {tag}")
+
+
 @app.command("inspect-channel")
 def inspect_channel_cmd(
     channel_ref: str = typer.Argument(..., help="Channel ID (numeric) or name (partial match, must be unique)"),