thoughtleaders-cli 0.7.1__py3-none-any.whl → 0.7.2__py3-none-any.whl

{thoughtleaders_cli-0.7.1.dist-info → thoughtleaders_cli-0.7.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.7.1
+Version: 0.7.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
@@ -68,7 +68,7 @@ ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligenc
 - [duckdb](https://duckdb.org/)
 - [yt-dlp](https://github.com/yt-dlp/yt-dlp)
 
-For automated installs on MacOS, prefer installing Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv` and installing everything locally.
+For automated installs on MacOS, prefer installing Python and the requirements on Homebrew and use the pipx package manager, but ask the user if they have the admin access (sudo) password first. If not, proceed by using `uv`.
 
 ## Install
 
@@ -280,6 +280,7 @@ The plugin ships several focused skills (installed by all the `tl setup *` comma
 - **`tl-report-builder`** — builds TL reports (channels / brands / sponsorships / videos) from natural-language requests. Produces an in-chat preview by default; saves a real campaign when the user is explicit ("save", "create the report").
 - **`tl-import`** / **`bulk-import`** — superuser-only; bulk-add or exclude lists of channels, brands, videos, or sponsorships against a report.
 - **`tl-views-guarantee`** — sizes a multi-video sponsorship buy for a channel, returning the video bundle size, views guarantee, and likelihood to hit.
+- **`tl-top-partnerships`** — brand-user performance report. Ranks a brand's sold sponsorships by live eCPM vs the sold-date projection, aggregates per channel, and delivers a two-tab Google Sheet ("By Deal" / "By Channel") via `gws`. Uses only public CLI commands (`tl whoami`, `tl sponsorships list`).
 
 ## Output Formats
 

{thoughtleaders_cli-0.7.1.dist-info → thoughtleaders_cli-0.7.2.dist-info}/RECORD

@@ -1,12 +1,13 @@
-tl_cli/__init__.py,sha256=qheEAJU-hUoE234IhRTFfabmqGg2OSLfwFC7YP2Qzbo,112
+tl_cli/__init__.py,sha256=w380YYlqGtwTYG78LJyZu5ljV8MmIBzKLk-R9Kq8Apw,112
 tl_cli/_completions.py,sha256=kOyEUqC26vbYvyXWi513WX8fF73qQLR5WWuRSe_wqyk,164
+tl_cli/_typer_utils.py,sha256=ZiZsCVmEznPvBw-dYbr3tu3zWZ0iN6kjoQmK3gMqD28,860
 tl_cli/config.py,sha256=UV_OYTXuQnAIqbi_oVCXx0hhIdZWR678RRapVv51UwQ,1859
 tl_cli/filters.py,sha256=jymgt21vl2d67yTXD_ceRIxTn6H6OYI5-QvQyE4Y4z0,2937
 tl_cli/hints.py,sha256=cT8kuDtkAZqwXkc2RV0Yg_abofK-g9UiXwTTBunX78U,1557
-tl_cli/main.py,sha256=mCPERzboCOJXa_uMix-qS-1eENpUH89Goi8VQO20tg0,5721
+tl_cli/main.py,sha256=A_8b2SQjBKATxrjO7AGC5Ab1QWlP35gGo4TWzYZtlOM,5806
 tl_cli/self_update.py,sha256=akXOWYgBX2otyaVlx9CDl04gG2s_hYigE2Vkpubt0SA,18302
 tl_cli/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tl_cli/auth/commands.py,sha256=PfTSb1vE0QY5VD0a3o8hI7ofE12pxKLwlMRQkWRI5k0,6204
+tl_cli/auth/commands.py,sha256=NtM5WGnReXrpZ3bysNudUYT_TcRRPE0Ho1EwbRgM_Ws,6285
 tl_cli/auth/finalize.py,sha256=74x8U39dK4nhEnIUMKhX5rNsn1Qjjm8or1n1nUH0SbQ,3346
 tl_cli/auth/login.py,sha256=6Jhfw7_eXGxZvUfNP33AZPRmnqmu_scvgt4AcOydsrE,10665
 tl_cli/auth/pkce.py,sha256=4Q6Ip-TeZFNG9c3swXNi4gH7mdMkltKa62gZZNybt8U,658
@@ -16,37 +17,37 @@ tl_cli/client/errors.py,sha256=KcTIieHtiEeBBDXTtEBSWsMcx2qaQskMyc_2_0l9WM4,2597
 tl_cli/client/http.py,sha256=pUJYYuT0q92_SwqCuMj3ozBthvchKuKL9v9U_eCQv20,4164
 tl_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/commands/_comments_common.py,sha256=x91WPSpDdV8AwE8Mwx4VtZQKWXBufsnBnC1lFD0Tzys,4522
-tl_cli/commands/balance.py,sha256=zUrlWUAcsgq1L0Z1dZzvmwSC-sOQd-WlT9j5zGqzZpc,2651
-tl_cli/commands/brands.py,sha256=eRN7XcOTjnLiKgJx8I2s1ar_opcIDZhbglypVY-qkbc,12362
+tl_cli/commands/balance.py,sha256=JHSmKdAUNtd-9zlKZhit9_BmhHXrEk0kQ-oSlQ0Eo6Y,2732
+tl_cli/commands/brands.py,sha256=rvYRrhkDhHDlvFpWrf8TtGbBt8KyNxHcVodjjFNpmHY,12443
 tl_cli/commands/bulk_import.py,sha256=d4y1k_lD52LPJcCqXxEmyHIqcIwomZgbjqs1_QxPjeQ,4536
 tl_cli/commands/changelog.py,sha256=D1PtDdHpawTlWqUHjKzVmv9yXLSU915UVmI3dZzEwyA,4241
-tl_cli/commands/channels.py,sha256=XEmdMNXde5oOL4LhpVPVx2MYmEKSrfvkcBXgBUECPLg,17136
-tl_cli/commands/credits.py,sha256=JFZCZ__v5KZdsGvJ3ypZVer8I2nGVQRu2VIXu7vlN4Q,7227
-tl_cli/commands/db.py,sha256=K1_EAokTMdwjbzEdkOpOQVtdErSJW_p6k_7cCdYKpvE,4972
-tl_cli/commands/deals.py,sha256=9-boF_HVO6xQ5ULPxatWRxbCIwMjzKCbCUb12tEwAe0,2093
-tl_cli/commands/describe.py,sha256=6rN-s2NY2kFkgxuOsJZoB-furb0iZq1WXs9R-mHJFAg,12151
-tl_cli/commands/doctor.py,sha256=DZvfQN8LRSg3CsnUyI3nlTqTY2za4EHISdavBAWwKzU,8943
-tl_cli/commands/matches.py,sha256=C4_kWRpTGu2lduDmrFpgi-D0Q4MuPc_3Cc76Ud2_i1g,2805
-tl_cli/commands/proposals.py,sha256=MWohD2UdEVRIVzYX-5uKlKE8U56nQu4OJMHbiaXuM_s,2837
-tl_cli/commands/recommender.py,sha256=Yw7WaKW5OBh5rCkxURGbeuHfp1vCA37qE0fBF_bX53M,18841
-tl_cli/commands/reports.py,sha256=rcJEjGEunf-6j5kNwQBNP2GKoJsufiyRBoExV0CQA70,22462
-tl_cli/commands/schema.py,sha256=ejL_7zln_Hh8Z43ZxA7VsjndLZNL82GCLH8VHTTZbVQ,5904
-tl_cli/commands/setup.py,sha256=bY7ZpkJnx3YuoF-M57djilFW8rC_U6XIg1CLCozxjKI,21839
-tl_cli/commands/snapshots.py,sha256=7zl8iQhKqmGSVXKOP39Q1jZV8N1boy7cQoKQHLJ_ROE,3347
-tl_cli/commands/sponsorships.py,sha256=VBDrJ84hLFcdMFFy3nBrRoWB5RR1LrJtV5zMsB5gl5c,10319
-tl_cli/commands/uploads.py,sha256=mUvsUX5H7_rf1Xko0jmo5yChz5vXubojWWnGMfVfidM,1445
-tl_cli/commands/whoami.py,sha256=T9Bdr794Hlmu2d_1rY52_QSzXPvS3RTJc5YYO4Axhd0,7785
+tl_cli/commands/channels.py,sha256=EgwTzweKsQEerBTwiWGCP1myCTW3KQFu4Om2j4Htfzk,17217
+tl_cli/commands/credits.py,sha256=2xCht2e420LmaFBKNdKoMz8GlTh31qSWSlJAnVzoZic,7308
+tl_cli/commands/db.py,sha256=rdIQrxT7sdrPEnBbByNHvPr2X6iIg-wb19X9bWYwDRc,5053
+tl_cli/commands/deals.py,sha256=ZK9yneInsC6DXoCPS65oyLoVR0eRW1xdRlEN7oRp1pc,2174
+tl_cli/commands/describe.py,sha256=Ox2B1hoVuJ6pJc_x5BJjAhEJhlae-el9zwoJKutw3X8,12232
+tl_cli/commands/doctor.py,sha256=KUKglwhMc7B26XXy_3M0LkHu7wqfFO5T0YPHO1SH1VY,9024
+tl_cli/commands/matches.py,sha256=K5o6B8FLECp7825dU4W3X8n-wuXvGJz57xpQPXeXQ-0,2886
+tl_cli/commands/proposals.py,sha256=khsjorluIfgrJ22DiwzIAFcYD4JbirjkOBz1KuQ0Sdk,2918
+tl_cli/commands/recommender.py,sha256=DIRvnSbV2TwvVUgA5luGJ7uQUOjHx2CULFsZVaqUYw4,18922
+tl_cli/commands/reports.py,sha256=1QDJN6FrUmWCuvaMxN884_bVdy-l7anBuS2jkCZF1VQ,22543
+tl_cli/commands/schema.py,sha256=GCBEE4fDatQhVasLKKr7bkGhELRZ0scYm_hUCbDYmuA,5985
+tl_cli/commands/setup.py,sha256=QST6DCSxJHLFNX1UUJHwZ3hTDTnySATaV2Tc2JsdYYY,21920
+tl_cli/commands/snapshots.py,sha256=mWxnZI_UBzbZZHsA3uP0Q7Gt2XsLLoRD5dRNGt-mGUE,3428
+tl_cli/commands/sponsorships.py,sha256=MWjyaReMMhmVKAbrCBCVw_J6dzkML_TIo_2kyPOYQOM,10400
+tl_cli/commands/uploads.py,sha256=Tf9tqAEm9FGe3A7sr_EDX9OzdNInCmrWNr10wWGuMUo,1526
+tl_cli/commands/whoami.py,sha256=aUXwBRwh1vAGrvz8CKGfHYtEOKJCIDfwrGesKAwYZMk,7866
 tl_cli/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/output/formatter.py,sha256=pqlKmb2nZ1Z2e1A9m8l5mgVemJinVAP4in1tUzFWHno,22522
 tl_cli/_plugin/.claude-plugin/marketplace.json,sha256=l56PMmyjfGXNGlV30wRyOAe74B6gJNCVNCxgsBbSNxc,446
-tl_cli/_plugin/.claude-plugin/plugin.json,sha256=g5iR6MaPe2-Bp5koMopkkYWL7N53ZoAeCjAecU6v1MM,466
+tl_cli/_plugin/.claude-plugin/plugin.json,sha256=_Im3uBChUbEhtgMa7p_Efg10yDoSSS0GtrAKAL_E6ME,466
 tl_cli/_plugin/agents/tl-analyst.md,sha256=6J3X3NANkWg6OOUCvNirkN4ulIk80KSumPncDUBt75E,6761
 tl_cli/_plugin/agents/youtube-comment-classifier.md,sha256=S5lr_htA98FIX0su8FJ2ntiHfbdK8OB2NQKC4lTnQcw,2178
 tl_cli/_plugin/hooks/hooks.json,sha256=FSWibw1xAjA-suFV3fR8btIb2kQ82LQ08otTr-NpmFw,835
 tl_cli/_plugin/hooks/scripts/load-tl-skill.mjs,sha256=EBsyZ-caei-CBJsRtqzJXJs_20O3H22MuVmDpu96umo,805
 tl_cli/_plugin/hooks/scripts/post-usage.sh,sha256=WVvZLkZik6lbeZ20Kh-wgm4JkRFHFN0Uwl4C8S3Y0sY,759
 tl_cli/_plugin/hooks/scripts/pre-check.sh,sha256=E9KeuXy6yeHEBOnOFW4hDW-Et-Dbp1Oh--3WXKfOX78,898
-tl_cli/_plugin/skills/tl/SKILL.md,sha256=ZkaaPZZGuJhEHaXp2CsxMDb9BvyKrO9dyC8K40E9DUM,58115
+tl_cli/_plugin/skills/tl/SKILL.md,sha256=fKxHgoe0oX1vFwVFUTzF95h4fq5fAmFlodqZr7cdbeA,58174
 tl_cli/_plugin/skills/tl/references/business-glossary.md,sha256=FCS-qBOGpdJCmHdglRGRjAuTQAtzpxJNpMkEWThuvlI,17779
 tl_cli/_plugin/skills/tl/references/elasticsearch-schema.md,sha256=OpHvixZ8UcZYJd8GdwgumryFyKwPAxj3AvPkl1QreMY,9316
 tl_cli/_plugin/skills/tl/references/firebolt-schema.md,sha256=KagpSWWEWIRfsAWz271PvAqVbSPvWLoogWhCA_XFSZw,10642
@@ -71,7 +72,7 @@ tl_cli/_plugin/skills/tl-channel-authenticity/scripts/tl_cli.py,sha256=lzW3l9TBt
 tl_cli/_plugin/skills/tl-channel-authenticity/scripts/video_integrity.py,sha256=Pj9cZkFHX-fwfmkSjicy_B04fQ3TW3gLrGliHwCwX5g,11120
 tl_cli/_plugin/skills/tl-channel-authenticity/scripts/view_curves.py,sha256=wx4cgi_HSOBDEy9bI_8RGnAFpY8q8xHOlF7DYojmi0c,4447
 tl_cli/_plugin/skills/tl-import/SKILL.md,sha256=k0-2yCpQ75yXk_wGrgSkInQeUeUp6-lne3vRXGcef8A,20245
-tl_cli/_plugin/skills/tl-keyword-research/SKILL.md,sha256=YPWG4ILsPnCMRuePlkY2oqvMDvIqBkwEA8DgsbpfepQ,10425
+tl_cli/_plugin/skills/tl-keyword-research/SKILL.md,sha256=xV_efeBwKpjHX1VleHDyr5vqpOhsP-EXH8UqN_SIIrE,10484
 tl_cli/_plugin/skills/tl-keyword-research/scripts/probe.py,sha256=bM6p-AyaSOp8EpV9oxBVtMwolWCXjU48MisaEROeGZs,4796
 tl_cli/_plugin/skills/tl-report-builder/SKILL.md,sha256=wGm7V0C8vqJAqWBfJOtGAAp19EI4xIL2TdY-KPxgLdU,144690
 tl_cli/_plugin/skills/tl-report-builder/examples/e2e_findings.md,sha256=9JD8BA8QrW6d7TlWX6_vGVSvpo_EGPl5gihmSK86tiI,17453
@@ -94,7 +95,7 @@ tl_cli/_plugin/skills/tl-report-builder/tools/sample_judge.md,sha256=Gl-wBNhsjni
 tl_cli/_plugin/skills/tl-report-builder/tools/similar_channels.md,sha256=ta1Q-GelJ_nFaYFWXDMhhgkTXRRYUSxhgjKdAeHtCrY,2071
 tl_cli/_plugin/skills/tl-report-builder/tools/topic_matcher.md,sha256=KIuqCFm_zcgQcxDRoAisFnN64P9M-ueKfy8qmWIgYAg,13395
 tl_cli/_plugin/skills/tl-report-builder/tools/widget_builder.md,sha256=da2dJN7M1j9QXtlEPs0CGUp5GHbO-tsgMuJRIxQAtAY,14392
-tl_cli/_plugin/skills/tl-save-report/SKILL.md,sha256=xS8ayH6b3YI43osiHYYNmPseM1pGkzDgMP6bu8dj19U,36917
+tl_cli/_plugin/skills/tl-save-report/SKILL.md,sha256=B3sv_G3pfIkqPLReez6RAwy5Dx6Nf4kz1C7UdaIAZLo,36976
 tl_cli/_plugin/skills/tl-save-report/references/columns_brands.md,sha256=H5G308GOzMWvWw6smkPGdb2CBuuxkrojCpJgWS9X4sA,3559
 tl_cli/_plugin/skills/tl-save-report/references/columns_channels.md,sha256=g57ET_VI611lB7fVrGwYFvTDqMkNB63OmmfrnbMZF1I,4684
 tl_cli/_plugin/skills/tl-save-report/references/columns_content.md,sha256=Y9YL5sm7zK44vSHTXOV4NY7nSOcJ9i3D0HFCo1g63WU,3466
@@ -106,10 +107,12 @@ tl_cli/_plugin/skills/tl-save-report/references/sortable_columns.json,sha256=WxA
 tl_cli/_plugin/skills/tl-save-report/references/sponsorship_filterset_schema.json,sha256=MlbxtBwCArdCmKynrZU6UL0Ve5Dp15tx6iIQJ5xhivY,10753
 tl_cli/_plugin/skills/tl-save-report/references/sponsorship_widget_schema.json,sha256=bCCl1yF9PBdJndvlT6Ek5UbDYHMvufByKNDN1aunpHE,9530
 tl_cli/_plugin/skills/tl-save-report/references/widgets.md,sha256=OFN6FOMjkBqiFN5EHP_pUqrp6Zqou5JuAXJ75cHWyyE,9798
+tl_cli/_plugin/skills/tl-top-partnerships/SKILL.md,sha256=hvH05hIaGlc0RfTE0GLBtDiB6043TmdIYOOczfOEqLM,6517
+tl_cli/_plugin/skills/tl-top-partnerships/scripts/top_partnerships.py,sha256=_13W6-HuD_jtl7AWQQcZQ0SQO9qODMymlcL-1s4-VwU,13248
 tl_cli/_plugin/skills/tl-views-guarantee/SKILL.md,sha256=IH7q1WJDWri9TWJMiga1FMGJO_GKSbWwaDS6CVNZ9c0,9270
 tl_cli/_plugin/skills/tl-views-guarantee/scripts/vg.py,sha256=Qp5poinHEqh9374anq0bLtlxj2YL6ipBicaT960-Cws,15825
-thoughtleaders_cli-0.7.1.dist-info/METADATA,sha256=R5s_D2PZeJMy_96dWj9S22R4rfaGWCJ-Wse-UUjo8kU,18149
-thoughtleaders_cli-0.7.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-thoughtleaders_cli-0.7.1.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
-thoughtleaders_cli-0.7.1.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
-thoughtleaders_cli-0.7.1.dist-info/RECORD,,
+thoughtleaders_cli-0.7.2.dist-info/METADATA,sha256=7BN2D4RB5Aq2zWM6krJwjpR6IAFOZczDvjnUeN67q0A,18452
+thoughtleaders_cli-0.7.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+thoughtleaders_cli-0.7.2.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
+thoughtleaders_cli-0.7.2.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
+thoughtleaders_cli-0.7.2.dist-info/RECORD,,

{thoughtleaders_cli-0.7.1.dist-info → thoughtleaders_cli-0.7.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.29.0
+Generator: hatchling 1.30.1
 Root-Is-Purelib: true
 Tag: py3-none-any

tl_cli/__init__.py

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

tl_cli/_plugin/.claude-plugin/plugin.json

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

tl_cli/_plugin/skills/tl/SKILL.md

@@ -434,6 +434,8 @@ If unsure about what information to find where, read the [references/postgresql-
 
 If a user asks for one of the **Unavailable** items, say so explicitly and propose the closest `tl`-based approximation rather than silently degrading.
 
+If the user requests a chart, create it as a SVG graphic.
+
 ### Discovery & system
 ```bash
 tl describe                            # List all resources with credit costs (free)

tl_cli/_plugin/skills/tl-keyword-research/SKILL.md

@@ -164,3 +164,4 @@ Each probe is `size:0` + `track_total_hits:true` with no aggregations — no row
 5. `keywords` array is sorted descending by `count`.
 6. Each entry has exactly `keyword` (string) and `count` (integer).
 7. The seed keyword(s) appear in the output.
+8. If the user requests a chart, create it as a SVG graphic

tl_cli/_plugin/skills/tl-save-report/SKILL.md

@@ -503,6 +503,8 @@ Echo the saved URL + ID, plus a follow-up offer for refinement:
 
 The follow-up offer matters because **FilterSet changes (keywords, demographics, M2M lists) can't be patched in place** via `tl reports update` — they require saving a new variant. Surface that limitation only if the user actually asks to change FilterSet fields.
 
+If the user requests a chart, create it as a SVG graphic.
+
 ### On failure
 
 If the command exits non-zero, the CLI prints the error on stderr (shape: `Error (NNN): <detail>` for most codes; specific lines for 401/402/403). **Surface the error verbatim** — do NOT silently report success.

tl_cli/_plugin/skills/tl-top-partnerships/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: tl-top-partnerships
+description: External brand-user performance report. Ranks a brand's sponsorships by effective CPM once the sponsored videos went live, and compares live eCPM against the sold-date projection. Use whenever a brand user asks "which of my sponsorships performed best", "top partnerships this year", "best ROI deals", "effective CPM on my deals", "which sponsorships overperformed", "/top-partnerships", or any variation of "show me my best-performing sponsorships". This is the brand-side equivalent of internal performance reporting — fire it eagerly any time a brand wants to look back at their booked deals through a performance lens, even if they don't say the words "CPM" or "eCPM".
+---
+
+# Top Partnerships (Brand-side)
+
+Helps a brand look back at their sold sponsorships and see which ones delivered the lowest effective CPM (eCPM) once the videos went live, vs the projection at sale.
+
+## Triggers
+
+- `/top-partnerships` — defaults to calendar YTD
+- `/top-partnerships <range>` — e.g. `/top-partnerships 2025`, `/top-partnerships "last 12 months"`, `/top-partnerships "Q1 2026"`
+- Natural language: "top partnerships this year", "best sponsorships", "which deals performed best", "effective CPM on my deals", "show me my best ROI sponsorships"
+
+## What this skill computes
+
+For every sold sponsorship the brand has where the video has actually gone live (has a `publish_date` and a non-null live `views` count):
+
+- **Sold-date eCPM** = `price / projected_views_at_purchase_date * 1000`
+  - The projection captured on the adlink at the moment the deal was sold. This is the eCPM the brand "agreed to."
+- **Live eCPM** = `price / views * 1000`
+  - The actual eCPM now that the video has accumulated views.
+- **View ratio** = `views / projected_views_at_purchase_date`
+  - >1 means the video out-delivered its projection.
+- **Delta** = `live_eCPM - sold_date_eCPM`
+  - Negative delta = the deal got *cheaper* per view than promised (good for the brand). Positive delta = the deal underdelivered.
+
+It also pulls **future bookings** — any sponsorship with status sold / proposal_approved / pending and a send date strictly after today — and tags each deal and each channel with the earliest future send date, or "Re-book - no future spot" if none exists. This turns the report into an actionable list, not just a backward look.
+
+## Output
+
+A Google Sheet with two tabs, owned by the caller's Google account:
+
+- **By Deal** — one row per sponsorship, ranked by live eCPM (best first). Columns: rank, channel, title, video_url, send_date, publish_date, price, promised_views, live_views, view_ratio, sold_date_ecpm, live_ecpm, delta_ecpm, measurable, next_booking.
+- **By Channel** — one row per channel, aggregated across all that channel's deals in range. Combined live eCPM is `sum(price) / sum(live_views) * 1000` (volume-weighted, not an average of CPMs). Sorted by combined live eCPM. Columns: channel, deals, measurable_deals, total_price_usd, total_promised_views, total_live_views, view_ratio, sold_date_ecpm, live_ecpm, delta_ecpm, next_booking.
+
+In chat: a short summary + top-10 channels table + the sheet URL.
+
+## Workflow
+
+### Step 1 — Resolve the brand
+
+Run `tl whoami --json` and read the `brands` array.
+
+- One brand → use it silently.
+- Zero brands → tell the user this skill is for brand-user profiles and stop.
+- Multiple brands → ask which one. Don't guess.
+
+### Step 2 — Resolve the time range
+
+Default = calendar YTD (Jan 1 of the current year through today).
+
+Accept these forms in the user's input:
+
+- `2025` or `"2024"` → that full calendar year
+- `"last 12 months"` → trailing 12 months ending today
+- `"Q1 2026"`, `"Q4 2025"` → that quarter
+- `"YTD"` → explicit current YTD
+- Anything else → ask the user to clarify, don't silently pick
+
+Convert to a `send-date-start` / `send-date-end` pair (YYYY-MM-DD strings). Use `send_date` as the time anchor because that is when the sponsorship actually ran for the brand — purchase_date can be months earlier.
+
+### Step 3 — Run the script
+
+```bash
+python3 <SKILL_DIR>/scripts/top_partnerships.py \
+  --brand "<BRAND_NAME>" \
+  --send-date-start <YYYY-MM-DD> \
+  --send-date-end <YYYY-MM-DD>
+```
+
+`<SKILL_DIR>` resolves to this skill's directory at invocation time (same convention as `tl-views-guarantee`, `tl-keyword-research`).
+
+The script does everything: pulls sold deals in range (paginated), pulls all future bookings, computes per-deal and per-channel metrics, creates a Google Sheet with two tabs, shares it back to the caller, and prints a markdown summary plus the sheet URL.
+
+It uses `tl` for data and `gws` for sheet creation. Both must be on PATH and authed.
+
+### Step 4 — Present the result
+
+Take the script's stdout as-is. It already contains:
+
+1. **Summary line** — total sold deals, measurable count, median live eCPM, count overperforming.
+2. **Top 10 channels by combined live eCPM** — markdown table with the Next booking column bolded when it says "Re-book."
+3. **Sheet URL** — point the user at the two tabs.
+
+If more than half the top-10 channels show "Re-book", call that out in one sentence as the headline action item. If most of the top channels already have follow-ups booked, congratulate briefly and stop.
+
+Keep the writeup tight. No em dashes, no "just wanted to", no hedging. The data does the talking.
+
+## Brand-user mode notes
+
+- This skill assumes a brand-user `tl` auth. It uses only public CLI commands (`tl whoami`, `tl sponsorships list`) — no `tl db pg` and no Elasticsearch.
+- The `tl sponsorships list` endpoint already filters to deals the calling profile is allowed to see, so passing `brand:"<name>"` is a belt-and-braces filter rather than a privacy boundary.
+- View counts come from TL's own tracking on the `views` field returned by the CLI. They're the same numbers the brand sees in the TL dashboard, so the eCPMs are reconcilable with what they see in-app.
+- Don't include creators' contact emails, internal notes, or owner_* fields in the brand-facing output. The script already drops them from the CSV.
+
+## Edge cases worth mentioning to the user (only if they apply)
+
+- A deal that ran very recently (last 14-28 days) may show a misleadingly high Live eCPM because views are still accumulating. Mention this only if more than half the top-10 deals have a send date inside the last 28 days.
+- If the brand has zero measurable deals in the range, say so plainly and suggest broadening the range (e.g., last 12 months).

tl_cli/_plugin/skills/tl-top-partnerships/scripts/top_partnerships.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""
+Pull a brand's sold sponsorships in a date range, compute live vs sold-date eCPM,
+also pull future bookings, build per-deal and per-channel views, upload a
+two-tab Google Sheet, and print a top-10 markdown summary.
+"""
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from datetime import date, timedelta
+from pathlib import Path
+
+
+def slugify(s: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-") or "brand"
+
+
+def to_float(x):
+    if x is None or x == "":
+        return None
+    try:
+        return float(x)
+    except (TypeError, ValueError):
+        return None
+
+
+def to_int(x):
+    f = to_float(x)
+    return int(f) if f is not None else None
+
+
+def youtube_url(article_id):
+    if not article_id or ":" not in article_id:
+        return ""
+    vid = article_id.split(":", 1)[1]
+    return f"https://www.youtube.com/watch?v={vid}"
+
+
+def fmt_money(x):
+    return f"${x:,.0f}" if x is not None else "n/a"
+
+
+def fmt_int(x):
+    return f"{x:,}" if x is not None else "n/a"
+
+
+def fmt_ratio(x):
+    return f"{x:.2f}x" if x is not None else "n/a"
+
+
+def fmt_cpm(x):
+    return f"${x:,.2f}" if x is not None else "n/a"
+
+
+def tl_list(*args) -> list[dict]:
+    rows: list[dict] = []
+    limit = 200
+    offset = 0
+    while True:
+        out = subprocess.run(
+            ["tl", "sponsorships", "list", *args,
+             "--limit", str(limit), "--offset", str(offset), "--json"],
+            capture_output=True, text=True, check=True,
+        ).stdout
+        data = json.loads(out)
+        page = data.get("results", data) if isinstance(data, dict) else data
+        if not page:
+            break
+        rows.extend(page)
+        if len(page) < limit:
+            break
+        offset += limit
+    return rows
+
+
+def fetch_future_bookings(brand: str) -> dict[str, dict]:
+    """Return channel -> {send_date, status} for the earliest future booking per channel.
+    Future = send_date strictly after today, status in {sold, proposal_approved, pending}.
+    """
+    today = date.today()
+    cutoff = (today + timedelta(days=1)).isoformat()
+    end = (today + timedelta(days=365 * 2)).isoformat()
+    rows: list[dict] = []
+    for status in ("sold", "proposal_approved", "pending"):
+        rows.extend(tl_list(
+            f"brand:{brand}",
+            f"status:{status}",
+            f"send-date-start:{cutoff}",
+            f"send-date-end:{end}",
+        ))
+    by_channel: dict[str, dict] = {}
+    for r in rows:
+        ch = r.get("channel")
+        sd = r.get("send_date")
+        st = r.get("status")
+        if not ch or not sd:
+            continue
+        if ch not in by_channel or sd < by_channel[ch]["send_date"]:
+            by_channel[ch] = {"send_date": sd, "status": st}
+    return by_channel
+
+
+def build_deal_rows(raw: list[dict], future: dict[str, dict]) -> list[dict]:
+    out = []
+    for r in raw:
+        price = to_float(r.get("price"))
+        promised = to_int(r.get("projected_views_at_purchase_date"))
+        views = to_int(r.get("views"))
+        publish_date = r.get("publish_date")
+        live_cpm = (price / views * 1000) if (price and views) else None
+        sold_cpm = (price / promised * 1000) if (price and promised) else None
+        ratio = (views / promised) if (views and promised) else None
+        delta = (live_cpm - sold_cpm) if (live_cpm is not None and sold_cpm is not None) else None
+        measurable = bool(publish_date and views)
+        ch = r.get("channel")
+        f = future.get(ch)
+        next_booking = f"{f['send_date']} ({f['status']})" if f else "Re-book - no future spot"
+        out.append({
+            "channel": ch,
+            "title": (r.get("title") or "").strip(),
+            "video_url": youtube_url(r.get("article_id")),
+            "send_date": r.get("send_date"),
+            "publish_date": publish_date,
+            "price": price,
+            "price_currency": r.get("price_currency", "USD"),
+            "promised_views": promised,
+            "live_views": views,
+            "view_ratio": ratio,
+            "sold_date_ecpm": sold_cpm,
+            "live_ecpm": live_cpm,
+            "delta_ecpm": delta,
+            "measurable": measurable,
+            "next_booking": next_booking,
+        })
+    return out
+
+
+def build_channel_rows(deals: list[dict], future: dict[str, dict]) -> list[dict]:
+    agg: dict[str, dict] = {}
+    for d in deals:
+        ch = d["channel"] or "(unknown)"
+        a = agg.setdefault(ch, {"deals": 0, "measurable": 0, "price": 0.0, "promised": 0.0, "live": 0.0})
+        a["deals"] += 1
+        a["price"] += d["price"] or 0
+        if d["promised_views"]:
+            a["promised"] += d["promised_views"]
+        if d["live_views"]:
+            a["live"] += d["live_views"]
+            a["measurable"] += 1
+    out = []
+    for ch, a in agg.items():
+        live_cpm = (a["price"] / a["live"] * 1000) if (a["live"] and a["price"]) else None
+        sold_cpm = (a["price"] / a["promised"] * 1000) if (a["promised"] and a["price"]) else None
+        ratio = (a["live"] / a["promised"]) if a["promised"] and a["live"] else None
+        delta = (live_cpm - sold_cpm) if (live_cpm is not None and sold_cpm is not None) else None
+        f = future.get(ch)
+        next_booking = f"{f['send_date']} ({f['status']})" if f else "Re-book - no future spot"
+        out.append({
+            "channel": ch,
+            "deals": a["deals"],
+            "measurable_deals": a["measurable"],
+            "total_price": a["price"],
+            "total_promised": int(a["promised"]),
+            "total_live": int(a["live"]),
+            "view_ratio": ratio,
+            "sold_date_ecpm": sold_cpm,
+            "live_ecpm": live_cpm,
+            "delta_ecpm": delta,
+            "next_booking": next_booking,
+        })
+    out.sort(key=lambda r: (r["live_ecpm"] is None, r["live_ecpm"] if r["live_ecpm"] is not None else 0))
+    return out
+
+
+def whoami_email() -> str | None:
+    try:
+        out = subprocess.run(["tl", "whoami", "--json"], capture_output=True, text=True, check=True).stdout
+        return json.loads(out).get("user", {}).get("email")
+    except Exception:
+        return None
+
+
+def gws(cmd: list[str], params: dict | None = None, body: dict | None = None) -> dict:
+    args = ["gws", *cmd]
+    if params is not None:
+        args += ["--params", json.dumps(params)]
+    if body is not None:
+        args += ["--json", json.dumps(body)]
+    r = subprocess.run(args, capture_output=True, text=True, check=True)
+    # gws may print non-JSON preamble like "Using keyring backend: keyring" — find the JSON block
+    out = r.stdout
+    start = out.find("{")
+    return json.loads(out[start:]) if start >= 0 else {}
+
+
+def upload_sheet(brand: str, deals: list[dict], channels: list[dict], rankable: list[dict]) -> str:
+    title = f"{brand} Top Partnerships ({deals[0]['send_date'][:4] if deals else 'no-data'})"
+
+    # 1) Create empty spreadsheet via Sheets API
+    sheet = gws(["sheets", "spreadsheets", "create"], body={
+        "properties": {"title": title},
+        "sheets": [
+            {"properties": {"title": "By Deal"}},
+            {"properties": {"title": "By Channel"}},
+        ],
+    })
+    sid = sheet["spreadsheetId"]
+
+    # 2) Write By Deal
+    deal_header = ["rank", "channel", "title", "video_url", "send_date", "publish_date",
+                   "price", "promised_views", "live_views", "view_ratio",
+                   "sold_date_ecpm", "live_ecpm", "delta_ecpm", "measurable", "next_booking"]
+    rank_ids = {id(d): i + 1 for i, d in enumerate(rankable)}
+    # Order: ranked first (best live_ecpm), then unranked-measurable, then unmeasurable
+    ranked_set = {id(d) for d in rankable}
+    measurable_unranked = [d for d in deals if d["measurable"] and id(d) not in ranked_set]
+    unmeasurable = [d for d in deals if not d["measurable"]]
+    ordered = rankable + measurable_unranked + unmeasurable
+
+    deal_values = [deal_header]
+    for d in ordered:
+        deal_values.append([
+            rank_ids.get(id(d), ""),
+            d["channel"] or "", d["title"], d["video_url"], d["send_date"] or "",
+            (d["publish_date"] or "")[:10], d["price"] or "",
+            d["promised_views"] or "", d["live_views"] or "",
+            round(d["view_ratio"], 4) if d["view_ratio"] is not None else "",
+            round(d["sold_date_ecpm"], 4) if d["sold_date_ecpm"] is not None else "",
+            round(d["live_ecpm"], 4) if d["live_ecpm"] is not None else "",
+            round(d["delta_ecpm"], 4) if d["delta_ecpm"] is not None else "",
+            "TRUE" if d["measurable"] else "FALSE",
+            d["next_booking"],
+        ])
+    gws(["sheets", "spreadsheets", "values", "update"],
+        params={"spreadsheetId": sid, "range": f"'By Deal'!A1:O{len(deal_values)}",
+                "valueInputOption": "RAW"},
+        body={"values": deal_values})
+
+    # 3) Write By Channel
+    ch_header = ["channel", "deals", "measurable_deals", "total_price_usd",
+                 "total_promised_views", "total_live_views", "view_ratio",
+                 "sold_date_ecpm", "live_ecpm", "delta_ecpm", "next_booking"]
+    ch_values = [ch_header]
+    for c in channels:
+        ch_values.append([
+            c["channel"], c["deals"], c["measurable_deals"],
+            round(c["total_price"], 2), c["total_promised"], c["total_live"],
+            round(c["view_ratio"], 4) if c["view_ratio"] is not None else "",
+            round(c["sold_date_ecpm"], 4) if c["sold_date_ecpm"] is not None else "",
+            round(c["live_ecpm"], 4) if c["live_ecpm"] is not None else "",
+            round(c["delta_ecpm"], 4) if c["delta_ecpm"] is not None else "",
+            c["next_booking"],
+        ])
+    gws(["sheets", "spreadsheets", "values", "update"],
+        params={"spreadsheetId": sid, "range": f"'By Channel'!A1:K{len(ch_values)}",
+                "valueInputOption": "RAW"},
+        body={"values": ch_values})
+
+    # 4) Share with the caller (writer, no email)
+    email = whoami_email()
+    if email:
+        try:
+            gws(["drive", "permissions", "create"],
+                params={"fileId": sid, "sendNotificationEmail": False},
+                body={"role": "writer", "type": "user", "emailAddress": email})
+        except Exception:
+            pass
+
+    return f"https://docs.google.com/spreadsheets/d/{sid}/edit"
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--brand", required=True)
+    ap.add_argument("--send-date-start", required=True)
+    ap.add_argument("--send-date-end", required=True)
+    ap.add_argument("--top", type=int, default=10)
+    args = ap.parse_args()
+
+    raw = tl_list(
+        "status:sold", f"brand:{args.brand}",
+        f"send-date-start:{args.send_date_start}", f"send-date-end:{args.send_date_end}",
+    )
+    future = fetch_future_bookings(args.brand)
+    deals = build_deal_rows(raw, future)
+    channels = build_channel_rows(deals, future)
+
+    rankable = [d for d in deals if d["measurable"] and d["live_ecpm"] is not None and d["sold_date_ecpm"] is not None]
+    rankable.sort(key=lambda d: d["live_ecpm"])
+
+    measurable_count = sum(1 for d in deals if d["measurable"] and d["live_ecpm"] is not None)
+    unmeasurable_count = sum(1 for d in deals if not d["measurable"])
+
+    print("## Summary\n")
+    print(f"- Sold sponsorships in range: **{len(deals)}**")
+    print(f"- Measurable (video live with views): **{measurable_count}**")
+    if rankable:
+        median = sorted(d["live_ecpm"] for d in rankable)[len(rankable) // 2]
+        overperformed = sum(1 for d in rankable if d["delta_ecpm"] is not None and d["delta_ecpm"] < 0)
+        print(f"- Median live eCPM: **{fmt_cpm(median)}**")
+        print(f"- Deals that overperformed: **{overperformed} / {len(rankable)}**")
+    print()
+
+    if channels:
+        ranked_channels = [c for c in channels if c["live_ecpm"] is not None]
+        print(f"## Top {min(args.top, len(ranked_channels))} channels by combined live eCPM\n")
+        print("| # | Channel | Deals | Total spend | Total live views | View ratio | Live eCPM | Delta | Next booking |")
+        print("|---|---------|-------|-------------|------------------|------------|-----------|-------|--------------|")
+        for i, c in enumerate(ranked_channels[: args.top], 1):
+            next_cell = c["next_booking"]
+            if next_cell.startswith("Re-book"):
+                next_cell = f"**{next_cell}**"
+            print(
+                f"| {i} | {c['channel']} | {c['deals']} | {fmt_money(c['total_price'])} | "
+                f"{fmt_int(c['total_live'])} | {fmt_ratio(c['view_ratio'])} | "
+                f"{fmt_cpm(c['live_ecpm'])} | {fmt_cpm(c['delta_ecpm'])} | {next_cell} |"
+            )
+        print()
+
+    if unmeasurable_count:
+        print(f"_{unmeasurable_count} deals in range are not yet measurable (video not live or no view data yet). They appear in the sheet but not in the ranking._\n")
+
+    if deals:
+        url = upload_sheet(args.brand, deals, channels, rankable)
+        print(f"**Google Sheet:** {url}")
+        print("Two tabs — *By Deal* (one row per sponsorship) and *By Channel* (aggregated, one row per channel).")
+    else:
+        print("_No deals found in this range._")
+
+
+if __name__ == "__main__":
+    main()

tl_cli/_typer_utils.py

@@ -0,0 +1,23 @@
+"""Shared Typer customizations for the tl CLI.
+
+The single export here, ``AlphaSortedTyperGroup``, makes ``--help`` render
+its subcommands alphabetically instead of in registration order. It is
+applied via ``cls=AlphaSortedTyperGroup`` on every ``typer.Typer(...)``
+instantiation in the project so the behavior is consistent at every help
+level (``tl --help``, ``tl brands --help``, ``tl db --help``, etc.).
+"""
+
+import typer
+from typer.core import TyperGroup
+
+
+class AlphaSortedTyperGroup(TyperGroup):
+    """Render subcommands in alphabetical order on ``--help``.
+
+    Typer / Click default ``list_commands`` to insertion order; users
+    looking at long help listings want them sorted so the command they
+    are after is easy to find.
+    """
+
+    def list_commands(self, ctx: typer.Context) -> list[str]:
+        return sorted(super().list_commands(ctx))

tl_cli/auth/commands.py

@@ -4,6 +4,7 @@ import sys
 import time
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 from rich.prompt import Prompt
 
@@ -11,7 +12,7 @@ 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 KIND_API_KEY, StoredTokens, clear_tokens, load_tokens, save_tokens
 
-app = typer.Typer(help="Authentication commands")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Authentication commands")
 console = Console(stderr=True)
 
 

tl_cli/commands/balance.py

@@ -3,6 +3,7 @@
 import json
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 from rich.table import Table
 
@@ -10,7 +11,7 @@ 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="Credit balance and usage (free)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Credit balance and usage (free)")
 console = Console()
 
 

tl_cli/commands/brands.py

@@ -9,6 +9,7 @@ import json as _json
 import urllib.parse
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 
 from rich.console import Console
 
@@ -18,7 +19,7 @@ from tl_cli.commands._comments_common import register_comment_commands
 from tl_cli.hints import detail_hint
 from tl_cli.output.formatter import detect_format, output, output_single
 
-app = typer.Typer(help="Brand intelligence (detail, find, similar)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Brand intelligence (detail, find, similar)")
 register_comment_commands(app, "brand", "brand")
 
 

tl_cli/commands/channels.py

@@ -4,6 +4,7 @@ import json as _json
 import urllib.parse
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 
 from tl_cli.client.errors import ApiError, handle_api_error
@@ -13,7 +14,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 (detail and similar-channel recommendations)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="YouTube channels (detail and similar-channel recommendations)")
 register_comment_commands(app, "channel", "channel")
 
 _HISTORY_DEPRECATION = (

tl_cli/commands/credits.py

@@ -18,6 +18,7 @@ import webbrowser
 from decimal import Decimal, InvalidOperation
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.prompt import Prompt
@@ -27,7 +28,7 @@ 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)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Buy credits and view top-up history (free)")
 console = Console()
 err = Console(stderr=True)
 

tl_cli/commands/db.py

@@ -4,12 +4,13 @@ import json
 import sys
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 
 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, output, output_pricing_estimate
 
-app = typer.Typer(help="Raw read-only queries against PostgreSQL, Firebolt, or Elasticsearch (full-access only)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Raw read-only queries against PostgreSQL, Firebolt, or Elasticsearch (full-access only)")
 
 
 def _read_query(query: str | None) -> str:

tl_cli/commands/deals.py

@@ -3,11 +3,12 @@
 from typing import Optional
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 
 from tl_cli.commands.sponsorships import do_create, do_list, do_show
 from tl_cli.output.formatter import detect_format
 
-app = typer.Typer(help="Deals — agreed-upon sponsorships (shortcut for sponsorships status:deal)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Deals — agreed-upon sponsorships (shortcut for sponsorships status:deal)")
 
 
 @app.callback(invoke_without_command=True)

tl_cli/commands/describe.py

@@ -3,6 +3,7 @@
 import json
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 from rich.table import Table
 
@@ -10,7 +11,7 @@ from tl_cli.client.errors import ApiError, handle_api_error
 from tl_cli.client.http import get_client
 from tl_cli.output.formatter import _fmt_credits, detect_format
 
-app = typer.Typer(help="Discover available resources, fields, filters, and credit costs")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Discover available resources, fields, filters, and credit costs")
 console = Console()
 
 

tl_cli/commands/doctor.py

@@ -6,6 +6,7 @@ import statistics
 import time
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 from rich.table import Table
 
@@ -77,7 +78,7 @@ _RECOMMENDED_TOOLS: tuple[tuple[str, str, dict[str, str]], ...] = (
     ),
 )
 
-app = typer.Typer(help="Health check (auth, connectivity, version)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Health check (auth, connectivity, version)")
 console = Console()
 
 

tl_cli/commands/matches.py

@@ -3,11 +3,12 @@
 from typing import Optional
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 
 from tl_cli.commands.sponsorships import do_create, do_list, do_show
 from tl_cli.output.formatter import detect_format
 
-app = typer.Typer(help="Matches — possible brand-channel pairings (shortcut for sponsorships status:match)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Matches — possible brand-channel pairings (shortcut for sponsorships status:match)")
 
 
 @app.callback(invoke_without_command=True)

tl_cli/commands/proposals.py

@@ -3,11 +3,12 @@
 from typing import Optional
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 
 from tl_cli.commands.sponsorships import do_create, do_list, do_show
 from tl_cli.output.formatter import detect_format
 
-app = typer.Typer(help="Proposals — matches proposed to both sides (shortcut for sponsorships status:proposal)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Proposals — matches proposed to both sides (shortcut for sponsorships status:proposal)")
 
 
 @app.callback(invoke_without_command=True)

tl_cli/commands/recommender.py

@@ -13,6 +13,7 @@ For 1:1 similarity use `tl channels similar` and `tl brands similar`.
 import urllib.parse
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 
 from tl_cli.client.errors import ApiError, handle_api_error
@@ -20,7 +21,7 @@ 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="Recommender (similarity tags, top-channels/profiles/brands, similarity-profile inspection, profile→channel and channel→brand similarity)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Recommender (similarity tags, top-channels/profiles/brands, similarity-profile inspection, profile→channel and channel→brand similarity)")
 
 
 TOP_CHANNEL_COLUMNS = ["value", "channel_id", "channel_name", "slug"]

tl_cli/commands/reports.py

@@ -4,6 +4,7 @@ import json
 import time
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.panel import Panel
@@ -13,7 +14,7 @@ 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, output, output_single
 
-app = typer.Typer(help="Saved reports (list, run, create, update)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Saved reports (list, run, create, update)")
 err = Console(stderr=True)
 
 # Report type labels matching Django's ReportType enum

tl_cli/commands/schema.py

@@ -4,6 +4,7 @@ import json
 import re
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 import yaml
 from pytoon import encode as toon_encode
 from rich.console import Console
@@ -14,7 +15,7 @@ from rich.tree import Tree
 from tl_cli.client.errors import ApiError, handle_api_error
 from tl_cli.client.http import get_client
 
-app = typer.Typer(help="Show schema documentation for raw db queries (`tl db pg|fb|es`)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Show schema documentation for raw db queries (`tl db pg|fb|es`)")
 console = Console()
 
 # Pulls the YAML body out of the server's ```yaml … ``` fenced block. Any

tl_cli/commands/setup.py

@@ -13,12 +13,13 @@ import subprocess
 from pathlib import Path
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from pytoon import encode as toon_encode
 from rich.console import Console
 
 from tl_cli import __version__
 
-app = typer.Typer(help="Set up integrations (Claude Code, OpenCode, Gemini, Codex)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Set up integrations (Claude Code, OpenCode, Gemini, Codex)")
 console = Console(stderr=True)
 
 MARKETPLACE_SOURCE = "ThoughtLeaders-io/thoughtleaders-cli"

tl_cli/commands/snapshots.py

@@ -1,12 +1,13 @@
 """tl snapshots — Firebolt time-series metrics for channels and videos."""
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 
 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, output
 
-app = typer.Typer(help="Historical metrics snapshots (Firebolt time-series)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Historical metrics snapshots (Firebolt time-series)")
 
 
 @app.command("channel")

tl_cli/commands/sponsorships.py

@@ -4,6 +4,7 @@ import json as _json
 from typing import Optional
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from rich.console import Console
 
 from tl_cli.client.errors import handle_api_error, ApiError
@@ -137,7 +138,7 @@ def do_create_body(body: dict, fmt: str) -> None:
 
 # --- Typer app ---
 
-app = typer.Typer(help="Sponsorships (deals, matches, proposals)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Sponsorships (deals, matches, proposals)")
 
 
 @app.callback(invoke_without_command=True)

tl_cli/commands/uploads.py

@@ -1,13 +1,14 @@
 """tl uploads — Show video uploads by ID."""
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 
 from tl_cli.client.errors import ApiError, handle_api_error
 from tl_cli.client.http import get_client
 from tl_cli.commands._comments_common import register_comment_commands
 from tl_cli.output.formatter import detect_format, output_single
 
-app = typer.Typer(help="Video uploads (YouTube content from Elasticsearch)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Video uploads (YouTube content from Elasticsearch)")
 register_comment_commands(app, "upload", "upload")
 
 

tl_cli/commands/whoami.py

@@ -3,6 +3,7 @@
 import json
 
 import typer
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from pytoon import encode as toon_encode
 from rich.console import Console
 from rich.panel import Panel
@@ -13,7 +14,7 @@ from tl_cli.client.errors import handle_api_error, ApiError
 from tl_cli.client.http import get_client
 from tl_cli.output.formatter import detect_format
 
-app = typer.Typer(help="Show current user, profile, org, and brands (free)")
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Show current user, profile, org, and brands (free)")
 
 
 def _render_whoami(data: dict) -> None:

tl_cli/main.py

@@ -10,6 +10,7 @@ import typer
 from rich.console import Console
 
 from tl_cli import __version__
+from tl_cli._typer_utils import AlphaSortedTyperGroup
 from tl_cli import config as tl_config
 from tl_cli.auth.commands import app as auth_app
 from tl_cli.commands.balance import app as balance_app
@@ -38,6 +39,7 @@ app = typer.Typer(
     help=f"ThoughtLeaders CLI v{__version__} — query sponsorship data, channels, brands, and intelligence.",
     no_args_is_help=True,
     rich_markup_mode="rich",
+    cls=AlphaSortedTyperGroup,
 )