thoughtleaders-cli 0.5.0__py3-none-any.whl

thoughtleaders_cli-0.5.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: thoughtleaders-cli
+Version: 0.5.0
+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
+Project-URL: Documentation, https://github.com/ThoughtLeaders-io/thoughtleaders-cli/blob/main/docs/architecture.md
+Author-email: ThoughtLeaders <dev@thoughtleaders.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,influencer,sponsorship,thoughtleaders
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.12
+Requires-Dist: authlib>=1.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=25.0
+Requires-Dist: rich>=13.0
+Requires-Dist: toon-format>=0.9.0b1
+Requires-Dist: typer[all]>=0.12
+Description-Content-Type: text/markdown
+
+# tl cli
+
+ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence from the terminal.
+
+## Install
+
+### As a developer
+
+```bash
+git clone https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+cd thoughtleaders-cli
+python -m venv .venv
+pip install -e .
+```
+
+### As a user
+
+```bash
+pipx install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+# or
+uv tool install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+# or (but try to avoid it because just "pip" will not create a new venv for the product - only "uv" and "pipx" will do that)
+pip install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
+```
+
+Then set up:
+```bash
+tl auth login          # authenticate with ThoughtLeaders
+tl setup claude        # install Claude Code plugin (optional)
+tl setup opencode      # install OpenCode skill (optional)
+```
+
+## Quick Start
+
+```bash
+# Login
+tl auth login
+
+# Query sponsorships
+tl sponsorships list status:sold brand:"Nike" purchase-date:2026-01
+
+# Shortcut commands for sponsorship types
+tl deals list brand:"Nike"                    # Agreed-upon sponsorships
+tl deals list created-at:today                # Deals created today (date keywords: today, yesterday, tomorrow)
+tl matches list                               # Possible brand-channel pairings
+tl proposals list                             # Matches proposed to both sides
+
+# Show a specific sponsorship
+tl sponsorships show 12345
+
+# Search videos (note: this only shows "your" videos)
+tl uploads list q:code --csv
+
+# Show upload details (supports colon-containing IDs)
+tl uploads show 1174310:0BehkmVa7ak
+
+# Search channels. msn and tpp are tri-state filters (yes/no/both; default 'both').
+# msn = opted-in to receive sponsorship offers; tpp = exclusively TL-managed.
+# Both are also returned as boolean fields on every channel response.
+tl channels list category:cooking min-subs:100k
+tl channels list msn:yes                  # MSN channels only (~11k)
+tl channels list tpp:yes                  # TPP channels only (~169)
+tl channels list msn:no min-subs:500k     # big non-MSN channels
+
+# Show channel detail — accepts numeric ID or channel name.
+# Names that match more than one active channel print a candidate list
+# and exit; retry with a specific ID.
+tl channels show 12345
+tl channels show "Economics Explained"
+
+# Find similar channels (vector recommender, 50 credits, Intelligence plan).
+# msn: is tri-state (default msn:yes): yes = MSN only, no = non-MSN only, both = no filter.
+# tpp: is tri-state (default tpp:both): yes = TPP only, no = non-TPP only, both = no filter.
+# Same ID-or-name resolution rules as `channels show`.
+tl channels similar 12345 --limit 10
+tl channels similar "Tremending girls" min-score:0.85 --limit 5
+
+# Brand intelligence
+tl brands show Nike
+
+# Run a saved report
+tl reports run 42
+
+# Comments on a sponsorship
+tl comments list 12345
+tl comments add 12345 "Looks good"
+
+# Show information about the logged-in user
+tl whoami
+
+# Check credits
+tl balance
+```
+
+## Credits
+
+Every data query costs credits based on the type and number of results. Use `tl describe` to see credit rates and `tl balance` to check your balance.
+
+```bash
+tl describe                           # All resources + credit costs
+tl describe show sponsorships --filters    # Available filters for sponsorships
+tl balance                     # Your credit balance
+```
+
+# Terminology
+
+ThoughtLeaders has its internal terminology that's exposed throughout this tool.
+
+* **Brands** - Usually companies, sometimes individual products. Brands are the sponsors.
+* **Channels** - Usually YouTube channels, sometimes podcasts. Channels are creators, they are being sponsored.
+* **Sponsorships** - Either possible or realised business deals between brands and channels. There are several specific types of sponsorships:
+    * *Deals* - Contractually agreed-upon sponsorships. AKA sold sponsorships. They can be either in a production pipeline or already published / live.
+    * *Matches* - Possible matches between brands and channels, i.e. all pairings that ThoughtLeaders thinks could possibly be right for each other.
+    * *Proposals* - Matches that are actually proposed to both sides to consider.
+- **Adspots** — types of ads a channel carries (e.g. mention, dedicated video, product placement). Returned by `tl channels show`; each carries price/cost and computed CPM.
+
+Sponsorships are the centre of attention in ThoughtLeaders - all other analytics and operations serve to produce or optimise sponsorships.
+Note that the term "Sponsorship" is wide, and can encompass deals that yet need to be approved by either side. There is a funnel of
+sponsorship types: the pool of Sponsorships is large, the pool of Metches (considered from either Brand or Channel side) is smaller,
+the pool of Proposals is yet smaller, and the pool of Deals is the smallest.
+
+# Integrations
+
+## Claude Code Integration
+
+If you use Claude Code, install the plugin for natural language access:
+
+```bash
+tl setup claude
+```
+
+This registers the ThoughtLeaders marketplace, installs the plugin, and copies skills to `~/.claude/` for short `/tl` invocation. If the `claude` binary isn't on PATH, it still installs the standalone skills and prints manual instructions for the plugin.
+
+### Using the skills
+
+Talk naturally in Claude Code:
+
+```
+/tl Which channels did we sponsor in Q1?
+/tl sold sponsorships for Nike in Q1
+/tl show me pending proposals with send dates in April
+/tl what channels does Nike sponsor?
+/tl check my balance
+```
+
+Resource-specific slash commands:
+```
+/tl-sponsorships pending with send dates in April
+/tl-channels cooking channels over 100k subscribers
+/tl-brands Nike
+/tl-reports run my Q1 pipeline
+/tl-balance
+```
+
+### Updating
+
+```bash
+tl setup claude                    # re-installs skills and updates plugin
+```
+
+## OpenCode Integration
+
+```bash
+tl setup opencode
+```
+
+This copies the tl skill to `~/.config/opencode/skills/` where OpenCode discovers it automatically. The agent will use it when you ask about sponsorships, deals, channels, or brands.
+
+## Output Formats
+
+By default, output is a styled table in the terminal and JSON when piped.
+
+```bash
+tl sponsorships list status:sold                          # Pretty table
+tl sponsorships list status:sold --json                   # JSON
+tl sponsorships list status:sold --csv > sponsorships.csv # CSV
+tl sponsorships list status:sold --json | jq '.results'   # Pipe to jq
+```
+
+## Documentation
+
+- [Architecture & Design](docs/architecture.md) — full design doc covering commands, data scoping, credit metering, and server-side API
+- `tl describe` — discover available resources, fields, filters, and credit costs from the CLI itself
+- `tl <command> --help` — detailed help for any command
+
+# Notes
+
+* Tested with OpenCode and the `nemotron-cascade-2-30b-a3b-i1` local model.

thoughtleaders_cli-0.5.0.dist-info/RECORD

@@ -0,0 +1,59 @@
+tl_cli/__init__.py,sha256=bguKIARDylFfGSBlrE9gEnztZdCc_rALTrDcaBeS4wE,112
+tl_cli/_completions.py,sha256=kOyEUqC26vbYvyXWi513WX8fF73qQLR5WWuRSe_wqyk,164
+tl_cli/config.py,sha256=teQF2Smk38AFkrkaUnR0peo-CPy5CMIKiNoA0D5R9jQ,1945
+tl_cli/filters.py,sha256=jymgt21vl2d67yTXD_ceRIxTn6H6OYI5-QvQyE4Y4z0,2937
+tl_cli/hints.py,sha256=cT8kuDtkAZqwXkc2RV0Yg_abofK-g9UiXwTTBunX78U,1557
+tl_cli/main.py,sha256=EK3DZ0EwI2qSwXZyDOTuZh5K2rfe0jI5Wo-HWy82KK8,6924
+tl_cli/self_update.py,sha256=elLAH5gBOY00COWbSq5G6iwFx3e-59heKKWFrnAbQDg,5438
+tl_cli/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tl_cli/auth/commands.py,sha256=uf4grUdpPnY-oUBUNHJQVW30eCFBguwVm1mGwgwPX2Q,1589
+tl_cli/auth/login.py,sha256=6Jhfw7_eXGxZvUfNP33AZPRmnqmu_scvgt4AcOydsrE,10665
+tl_cli/auth/pkce.py,sha256=4Q6Ip-TeZFNG9c3swXNi4gH7mdMkltKa62gZZNybt8U,658
+tl_cli/auth/token_store.py,sha256=ZASTs8qllxu1cmkphQThq9NHSYN0dadZje1rEDquc18,2673
+tl_cli/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tl_cli/client/errors.py,sha256=PxHZv0O6zvaHZeKh3TTAXziX7WOJB_hhGOp72nxakX0,2531
+tl_cli/client/http.py,sha256=65Df8B9EjIod_Yv2p2dMxROHSejCJll7NsfSCxerZHg,3763
+tl_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tl_cli/commands/ask.py,sha256=dRt2H80MCzKB-EYYRFJMpr6gA798NE9Qlsi5D6kODII,2062
+tl_cli/commands/balance.py,sha256=2cWQIktn_EYvGc3qDhKF-qrun857_6AYOzDxvowsjl0,2091
+tl_cli/commands/brands.py,sha256=W-J7FdSqwNudWLTRHZ8k7QMIIJxdXVVoZSuj9R9_8zM,6638
+tl_cli/commands/changelog.py,sha256=D1PtDdHpawTlWqUHjKzVmv9yXLSU915UVmI3dZzEwyA,4241
+tl_cli/commands/channels.py,sha256=637rJX_vjK-G8HRZ2m0oESmmLotxB7dpChxFyDn2zwI,12494
+tl_cli/commands/comments.py,sha256=AgpnLtB7RYgc1grWWHPV51kI44BE2JdTlpOmtnPwFeY,2059
+tl_cli/commands/db.py,sha256=XpP6OE43puZrGILfspoRyVXpKPdteztJE2aySD9DJOI,4030
+tl_cli/commands/deals.py,sha256=9-boF_HVO6xQ5ULPxatWRxbCIwMjzKCbCUb12tEwAe0,2093
+tl_cli/commands/describe.py,sha256=QjTTdAxG7eWV5Z8jNkonikZ-5ScWOZ8NO5_xYublxUY,5527
+tl_cli/commands/doctor.py,sha256=UWLdlb041s3qbwW9OMgtQrEuaAu8j_SrKl5nUDLnYAU,2297
+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/reports.py,sha256=mgpg_sSNfAkDD40NI32wJH2-HGSwU2gryUhGYLTXB0Y,12849
+tl_cli/commands/schema.py,sha256=pMCVmX_v0HuCnLiJzAG0RZqmrKEo2g2uH8YcUid7kQw,1511
+tl_cli/commands/setup.py,sha256=tlU4UyTD0MJOK4mKTq5jOepdPIF2r3cqf5RWkP-9wXM,15180
+tl_cli/commands/snapshots.py,sha256=7zl8iQhKqmGSVXKOP39Q1jZV8N1boy7cQoKQHLJ_ROE,3347
+tl_cli/commands/sponsorships.py,sha256=uECLoX4AvUAaGBQDeUNu4EtGr3vGH_sv1pVwAUcFrv4,6981
+tl_cli/commands/uploads.py,sha256=Vtm9VO-PSwZBhFlTemFf1OEVhXJEc1AevT5HhWemYos,3179
+tl_cli/commands/whoami.py,sha256=HL_0X0hWI-NsmWfjgy0mhWO3TNdWztt_AAlWRJysyVk,7342
+tl_cli/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tl_cli/output/formatter.py,sha256=9NjUVUlCr17lizMIiV98vvDSFgY9ZZ5bHDlqAYvrhNI,15137
+tl_cli/_plugin/.claude-plugin/marketplace.json,sha256=l56PMmyjfGXNGlV30wRyOAe74B6gJNCVNCxgsBbSNxc,446
+tl_cli/_plugin/.claude-plugin/plugin.json,sha256=V9ojf_hNDdxmF0QEDMwFZLV-NX6L4jojKMnJZOwyPvU,466
+tl_cli/_plugin/agents/tl-analyst.md,sha256=bcmtgkOIaFe4uOsdIxStbruvBsEX9vNvgoDZUsGpOQU,3830
+tl_cli/_plugin/commands/tl-balance.md,sha256=0sQjVBu1xZXmzoTBqFZF8MhYAsuc9F7Vci23nbTDZ9Q,204
+tl_cli/_plugin/commands/tl-brands.md,sha256=FxZadL5utdJOrko0gl9HmVBvTDgVV1B2YzsBtjRWvwM,543
+tl_cli/_plugin/commands/tl-channels.md,sha256=B-vbF83rxW0S1PDwpU22SyoXGdfhQ1y6b_31Z8x5zIw,2207
+tl_cli/_plugin/commands/tl-reports.md,sha256=uB1u9gvcSSgxsXEPfHvT1iZjSxm-jH63nUbs_wsS5_o,511
+tl_cli/_plugin/commands/tl-sponsorships.md,sha256=8vm4qUWWy1A3n1t3fvLMLjNvgirI-6M3FifSjH3Gn3g,1259
+tl_cli/_plugin/commands/tl.md,sha256=qh1rnqSo7PJeFathrEOyk67XtvYqtz_vIw81nw5yd3w,1335
+tl_cli/_plugin/hooks/hooks.json,sha256=lU4w5iZGSnVJ1sZn18kbJGh2s-iOvG3TtAXmiVK61mE,476
+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=CE2XqRWnpCttlIIv3jDP9oCPLgZREGq6vSeuUrZNAxM,30437
+tl_cli/_plugin/skills/tl/references/business-glossary.md,sha256=PNQIxpIZ0zIxb3nHnvPeKUSFpjvnm4Q-950nQkNkfUM,7598
+tl_cli/_plugin/skills/tl/references/elasticsearch-schema.md,sha256=c7zFBj3PHweyw7AhrV_-Fy0GAxz9aralWdDSC16yd_s,10713
+tl_cli/_plugin/skills/tl/references/firebolt-schema.md,sha256=WocgEZSoa6phbbuWT49FsGPCWliq1QvA0hC_J0u6vcc,10043
+tl_cli/_plugin/skills/tl/references/postgres-schema.md,sha256=cBTclNLCh15MWVDRKM9VCLX7WVgfKk_bLxJrFEkheSQ,10677
+thoughtleaders_cli-0.5.0.dist-info/METADATA,sha256=oPYYQNkITzBs4kKB6EAc5Ln-668-qOx2TguAy3bV6vA,7989
+thoughtleaders_cli-0.5.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+thoughtleaders_cli-0.5.0.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
+thoughtleaders_cli-0.5.0.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
+thoughtleaders_cli-0.5.0.dist-info/RECORD,,

thoughtleaders_cli-0.5.0.dist-info/WHEEL

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

thoughtleaders_cli-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tl = tl_cli.main:cli

thoughtleaders_cli-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ThoughtLeaders
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tl_cli/__init__.py

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

tl_cli/_completions.py

@@ -0,0 +1,4 @@
+"""Shell completion helpers for the TL CLI."""
+
+# Shell completions are handled by Typer's built-in support.
+# Users can install them with: tl --install-completion

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

@@ -0,0 +1,17 @@
+{
+  "name": "thoughtleaders-plugins",
+  "owner": {
+    "name": "ThoughtLeaders",
+    "email": "dev@thoughtleaders.io"
+  },
+  "metadata": {
+    "description": "ThoughtLeaders CLI plugin for Claude Code — query sponsorship data from the terminal"
+  },
+  "plugins": [
+    {
+      "name": "tl-cli",
+      "source": "./",
+      "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence"
+    }
+  ]
+}

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

@@ -0,0 +1,12 @@
+{
+  "name": "tl-cli",
+  "version": "0.5.0",
+  "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
+  "author": {
+    "name": "ThoughtLeaders",
+    "email": "dev@thoughtleaders.io"
+  },
+  "homepage": "https://docs.thoughtleaders.io/cli",
+  "repository": "https://github.com/ThoughtLeaders-io/thoughtleaders-cli",
+  "keywords": ["thoughtleaders", "sponsorship", "influencer", "data", "cli"]
+}

tl_cli/_plugin/agents/tl-analyst.md

@@ -0,0 +1,66 @@
+---
+name: tl-analyst
+description: Use when the user asks to analyze, compare, investigate, or summarize ThoughtLeaders data across multiple dimensions. Chains tl CLI commands to answer complex questions that require multiple queries, cross-referencing, or aggregation. Triggers on "analyze", "compare", "investigate", "deep dive", "cross-reference", "trend", "correlation".
+tools: [Bash, Read]
+---
+
+# TL Data Analyst Agent
+
+You are an autonomous data analyst for ThoughtLeaders. You chain multiple `tl` CLI commands to answer complex questions that require cross-referencing, aggregation, or multi-step reasoning.
+
+## Before Starting Any Analysis
+
+1. **Check auth**: `tl auth status`
+2. **Check balance**: `tl balance --json` — estimate total cost for your planned queries
+3. **Discover schema**: `tl describe show <resource> --json` for each resource you'll query
+4. **Check saved reports**: `tl reports --json` — a saved report might already answer the question
+
+If estimated cost > 200 credits, ask the user to confirm before proceeding.
+
+## Analysis Patterns
+
+### Multi-step research
+"Find channels similar to the ones Nike sponsors and compare their pricing"
+1. `tl brands show Nike --json` → extract initial channel IDs from mentions
+2. `tl channels similar <initial-id> --json --limit 20` for each top initial channel → one 50-credit call per initial, returns enriched rows with subscribers / impression / cpm. The `msn:` filter is tri-state with default `msn:yes` (MSN channels only): use `msn:both` to broaden to all, or `msn:no` for non-MSN only. Ambiguous name arguments return 400 with candidates.
+3. Union + dedupe, then compile comparison table by cpm / subscribers.
+
+### Cross-resource analysis
+"Show me deal slippage this month"
+1. `tl sponsorships list status:pending send-date-end:2026-03-31 --json`
+2. Identify sponsorships with past send dates that aren't sold
+3. Present findings, suggest `tl comments add` for each
+
+### Report comparison
+"Compare Q1 to Q4 performance"
+1. `tl reports --json` → find relevant report ID
+2. `tl reports run <id> --since 2026-01-01 --until 2026-03-31 --json`
+3. `tl reports run <id> --since 2025-10-01 --until 2025-12-31 --json`
+4. Compute deltas and trends
+
+### Discovery workflows
+"What's our best performing brand this quarter?"
+1. `tl deals list purchase-date-start:2026-01-01 --json` → aggregate revenue by brand
+2. `tl brands show <top_brand> --json` → sponsorship intelligence
+3. `tl snapshots channel <id> --json` → performance metrics for top channels
+
+### Channel deep dive
+"Give me a full picture of channel 12345"
+1. `tl channels show 12345 --json` → profile, scores, and demographics
+2. `tl snapshots channel 12345 --json` → growth over time
+3. `tl deals list channel:12345 --json` → deal history
+4. `tl uploads list channel:12345 --json` → recent content
+
+### Demographics screenshots check
+"Does channel X have demographics screenshots uploaded?"
+1. `tl channels show <id-or-name> --json` → check `demographics_updated_at` field
+2. If non-null, screenshots are on file (the timestamp shows when they were last processed via OCR). If null, no screenshots have been uploaded for this channel.
+
+## Rules
+
+- **Always resolve numeric codes to human-readable labels** in your output. Never show "Status 3" — show "Sold". Status mapping: 0=Proposed, 1=Unavailable, 2=Pending, 3=Sold, 4=Rejected by Advertiser, 5=Rejected by Publisher, 6=Proposal Approved, 7=Matched, 8=Reached Out, 9=Rejected by Agency.
+- Always use `--json` for output you need to parse
+- Always include `--limit` on list queries to control credit spend
+- For `tl snapshots video`, always include `--channel` (required for Firebolt performance)
+- Present final results as a clear summary with tables when appropriate
+- Show total credits consumed at the end of your analysis

tl_cli/_plugin/commands/tl-balance.md

@@ -0,0 +1,10 @@
+---
+name: tl-balance
+description: Check credit balance and recent usage.
+---
+
+# /tl-balance — Credit Balance
+
+Show the user's credit balance and recent usage.
+
+Run `tl balance` and present the results.

tl_cli/_plugin/commands/tl-brands.md

@@ -0,0 +1,16 @@
+---
+name: tl-brands
+description: Brand intelligence lookup. Research a brand's sponsorship activity and channel mentions.
+---
+
+# /tl-brands — Brand Intelligence
+
+The user wants to research a brand's sponsorship activity. Requires Intelligence plan.
+
+1. Run `tl describe show brands --json` to discover filters
+2. Translate the user's request into a `tl brands show` command
+3. Execute and present results
+
+Examples:
+- "/tl-brands Nike" → `tl brands show Nike`
+- "/tl-brands Nike on channel 12345" → `tl brands show Nike --channel 12345`

tl_cli/_plugin/commands/tl-channels.md

@@ -0,0 +1,31 @@
+---
+name: tl-channels
+description: Channel search and lookup. Find YouTube channels by category, subscribers, language, or other criteria.
+---
+
+# /tl-channels — Channel Search
+
+The user wants to search or look up YouTube channels.
+
+1. Run `tl describe show channels --json` to discover filters
+2. Translate the user's request into a `tl channels` command
+3. Execute and present results
+
+Examples:
+- "/tl-channels cooking channels over 100k" → `tl channels list category:cooking min-subs:100000`
+- "/tl-channels 12345" → `tl channels show 12345`
+- "/tl-channels English gaming channels" → `tl channels list category:gaming language:en`
+- "/tl-channels mobile-first channels" → `tl channels list primary-device:mobile`
+- "/tl-channels channels with majority US audience" → `tl channels list min-us-share:50`
+- "/tl-channels mobile tech channels with US focus" → `tl channels list category:tech primary-device:mobile min-us-share:60`
+- "/tl-channels channels similar to 12345" → `tl channels similar 12345 --limit 10`
+- "/tl-channels look-alikes for Economics Explained at high similarity" → `tl channels similar "Economics Explained" min-score:0.85 --limit 10`
+- "/tl-channels look-alikes including non-MSN" → `tl channels similar 12345 msn:both --limit 20`
+- "/tl-channels look-alikes that are non-MSN only" → `tl channels similar 12345 msn:no --limit 20`
+- "/tl-channels TPP look-alikes for 12345" → `tl channels similar 12345 tpp:yes --limit 20`
+- "/tl-channels all TPP channels in cooking" → `tl channels list tpp:yes category:cooking`
+- "/tl-channels channels that are NOT in TPP" → `tl channels list tpp:no`
+- "/tl-channels MSN gaming channels" → `tl channels list msn:yes category:gaming`
+- "/tl-channels non-MSN channels with 500k+ subs" → `tl channels list msn:no min-subs:500000`
+
+Note: `tl channels list` and `tl channels similar` both support tri-state `msn:` and `tpp:` filters (`yes` / `no` / `both`). Defaults: `msn:yes` on `similar`, `msn:both` on `list`; `tpp:both` on both. Both values are also returned as boolean fields (`msn`, `tpp`) on every channel response — list, detail, and similar. Ambiguous name arguments return a 400 with candidate IDs listed.

tl_cli/_plugin/commands/tl-reports.md

@@ -0,0 +1,16 @@
+---
+name: tl-reports
+description: List and run saved reports. View your organization's saved reports and execute them.
+---
+
+# /tl-reports — Saved Reports
+
+The user wants to see or run their saved reports.
+
+1. Run `tl reports --json` to list saved reports
+2. Present the list with IDs and titles
+3. If the user specifies a report, run it with `tl reports run <id> --json`
+
+Examples:
+- "/tl-reports" → `tl reports`
+- "/tl-reports run my Q1 pipeline" → list reports, find matching one, `tl reports run <id>`

tl_cli/_plugin/commands/tl-sponsorships.md

@@ -0,0 +1,23 @@
+---
+name: tl-sponsorships
+description: Quick sponsorship lookup. Query, filter, or show details for sponsorships.
+---
+
+# /tl-sponsorships — Sponsorship Lookup
+
+The user wants to query sponsorships.
+
+1. Run `tl describe sponsorships --json` to discover filters
+2. Translate the user's request into a `tl sponsorships` command
+3. Execute and present results
+
+If no specific request is given, run `tl sponsorships list --limit 10` to show recent sponsorships.
+
+Examples:
+- "/tl-sponsorships pending with send dates in April" → `tl sponsorships list status:pending send-date:2026-04`
+- "/tl-sponsorships Nike" → `tl sponsorships list brand:"Nike"`
+- "/tl-sponsorships sold deals on mobile-first channels" → `tl sponsorships list status:sold primary-device:mobile`
+- "/tl-sponsorships deals on channels with majority US audience" → `tl sponsorships list min-us-share:50`
+- "/tl-sponsorships 12345" → `tl sponsorships show 12345`
+
+`tl sponsorships show <id> --json` returns extended detail fields beyond the list view, including: `impressions_guarantee`, `integration`, `publish_count`, `common_name`, `outreach_email`, nested `publisher` (first_name/last_name/email), nested `brand_contact` (first_name/last_name/email), and `brand.organization_name`.

tl_cli/_plugin/commands/tl.md

@@ -0,0 +1,28 @@
+---
+name: tl
+description: Smart router for ThoughtLeaders data queries. Translates your request into the right tl CLI command(s).
+---
+
+# /tl — ThoughtLeaders Query Router
+
+The user wants to query ThoughtLeaders data. Translate their request into the right `tl` CLI command.
+
+## Steps
+
+1. Identify which resource(s) the request is about (sponsorships, deals, channels, brands, uploads, snapshots, reports)
+2. Run `tl describe show <resource> --json` to discover available filters
+3. Translate the user's natural language into a `tl` command with appropriate filters
+4. Execute the command
+5. Present results clearly
+
+## 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 channels list category:cooking min-subs:100000`
+- "/tl mobile-first US cooking channels" → `tl channels list category:cooking primary-device:mobile min-us-share:50`
+- "/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`
+- "/tl show sponsorship 12345" → `tl sponsorships show 12345`
+
+If the request is complex and requires multiple queries, delegate to the tl-analyst agent.

tl_cli/_plugin/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pre-check.sh",
+          "timeout": 10
+        }
+      ]
+    }
+  ],
+  "PostToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/post-usage.sh",
+          "timeout": 5
+        }
+      ]
+    }
+  ]
+}

tl_cli/_plugin/hooks/scripts/post-usage.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# PostToolUse hook: warn on low credits after tl commands.
+
+COMMAND="${TOOL_INPUT_command:-}"
+OUTPUT="${TOOL_OUTPUT:-}"
+
+# Only act on tl commands
+if [[ ! "$COMMAND" =~ ^tl[[:space:]] ]]; then
+  exit 0
+fi
+
+# Check for 402 (insufficient credits)
+if [[ "$OUTPUT" =~ "402" ]] || [[ "$OUTPUT" =~ "Insufficient credits" ]]; then
+  echo "WARN: Credits exhausted. Deposit more at https://app.thoughtleaders.io/settings/billing" >&2
+  exit 0
+fi
+
+# Check for low balance in JSON output
+if [[ "$OUTPUT" =~ \"balance_remaining\"[[:space:]]*:[[:space:]]*([0-9]+) ]]; then
+  BALANCE="${BASH_REMATCH[1]}"
+  if [[ "$BALANCE" -lt 500 ]]; then
+    echo "WARN: Low credit balance ($BALANCE remaining). Consider depositing more credits." >&2
+  fi
+fi
+
+exit 0

tl_cli/_plugin/hooks/scripts/pre-check.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# PreToolUse hook: validate auth and check credits before tl commands.
+# Only runs when the Bash command starts with "tl ".
+
+COMMAND="${TOOL_INPUT_command:-}"
+
+# Only act on tl commands
+if [[ ! "$COMMAND" =~ ^tl[[:space:]] ]]; then
+  exit 0
+fi
+
+# Skip for system commands that don't need auth
+if [[ "$COMMAND" =~ ^tl[[:space:]]+(auth|doctor|--help|--version|describe) ]]; then
+  exit 0
+fi
+
+# Check auth
+if ! tl auth status --quiet 2>/dev/null; then
+  echo "WARN: Not authenticated. Run 'tl auth login' first." >&2
+  exit 0  # Don't block, just warn
+fi
+
+# For list commands without explicit limit, suggest adding one
+if [[ "$COMMAND" =~ ^tl[[:space:]]+(deals|uploads|channels|brands)[[:space:]] ]]; then
+  if [[ ! "$COMMAND" =~ limit: ]] && [[ ! "$COMMAND" =~ --limit ]]; then
+    echo "HINT: Consider adding a limit to control credit usage (e.g., limit:50)" >&2
+  fi
+fi
+
+exit 0