thoughtleaders-cli 0.5.0

ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence

tl cli

ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence from the terminal.

Install

As a developer

git clone https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git
cd thoughtleaders-cli
python -m venv .venv
pip install -e .

As a user

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:

tl auth login          # authenticate with ThoughtLeaders
tl setup claude        # install Claude Code plugin (optional)
tl setup opencode      # install OpenCode skill (optional)

Quick Start

# 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.

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:

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

tl setup claude                    # re-installs skills and updates plugin

OpenCode Integration

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.

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 — 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.