thoughtleaders-cli 0.5.0__tar.gz

thoughtleaders_cli-0.5.0/.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"
+    }
+  ]
+}

thoughtleaders_cli-0.5.0/.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"]
+}

thoughtleaders_cli-0.5.0/.github/workflows/python-publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$tag" != "$version" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject version $version" >&2
+            exit 1
+          fi
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs: [release-build]
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/thoughtleaders-cli/${{ github.event.release.name }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

thoughtleaders_cli-0.5.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.vscode/

thoughtleaders_cli-0.5.0/AGENTS.md

@@ -0,0 +1,106 @@
+# Project Overview
+
+**tl-cli** is a Python CLI for querying ThoughtLeaders sponsorship data (sponsorships, channels, brands, uploads, snapshots, reports). Built with Typer + Rich + httpx. Designed as an "agent-first tool" — the CLI handles structured commands and output, while the user's AI agent (Claude) provides intelligence.
+
+# Architecture
+
+## Entry Point & Command Registration
+
+`src/tl_cli/main.py` creates the root Typer app and registers all subcommands via `app.add_typer()`. The console script `tl` maps to `tl_cli.main:cli`, which wraps the Typer app with top-level error handling (respects `--debug`). System commands (`auth`, `setup`, `balance`, `doctor`, `whoami`) are free and don't cost credits.
+
+## Command Pattern (all data commands follow this)
+
+Every data command in `src/tl_cli/commands/` uses explicit Typer subcommands:
+- `list` — list/search with `key:value` filters as positional args
+- `show` — detail view by ID
+- `history` — historical data list
+- `create` / `add` — create new records (where applicable)
+
+When adding a new data command, follow this pattern. See `sponsorships.py` for the reference implementation.
+
+`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.
+
+## Filter Parsing (`filters.py`)
+
+`parse_filters()` handles `key:value` and `key:"quoted value"` syntax. Returns `dict[str, str]` passed as query params. Date filter keys (listed in `DATE_FILTER_KEYS` — e.g. `since`, `created-at`, `created-at-start`, `publish-date-end`) accept keywords `today`, `yesterday`, `tomorrow`. Sponsorship date fields (`created-at`, `publish-date`, `purchase-date`, `send-date`) each expose three filter shapes: bare `<field>:<date>` matches within that date/period, and `<field>-start:` / `<field>-end:` give inclusive lower/upper bounds (both sides inclusive; partial dates expand to the whole period). Empty-string values result in `IS NULL` queries on the backend.
+
+## Auth Flow (`auth/`)
+
+- **PKCE + Auth0**: Browser-based login with localhost callback server (`login.py`)
+- **Token Storage** (`token_store.py`): OS keyring primary, `~/.config/tl/credentials.json` fallback (0o600)
+- **Env override**: `TL_API_KEY` env var takes priority over keyring (for CI)
+- **Auto-refresh**: `TLClient` refreshes expired tokens on 401
+
+## HTTP Client (`client/http.py`)
+
+`TLClient` wraps httpx with auth header injection and automatic token refresh on 401. All API calls go through `_request()`.
+
+Every request includes an `X-TL-Client: cli/<version>` header. This header is used server-side in a Cloudflare WAF rule to skip managed challenges (JS/CAPTCHA) for CLI traffic on `/api/cli/*` paths. The header is not a secret — Cloudflare bypass is safe because the API enforces its own auth via Bearer tokens. If Cloudflare starts blocking CLI requests again, verify the WAF rule matches the current header value.
+
+## Error Handling (`client/errors.py`)
+
+Exit codes: 1 (forbidden/not-found), 2 (auth required), 3 (rate-limit/server-error), 4 (insufficient credits).
+
+## Output (`output/formatter.py`)
+
+TTY-aware: Rich tables in terminal, JSON when piped. Flags: `--json`, `--csv`, `--md`. Usage footer (credits charged + balance) goes to stderr. Breadcrumbs suggest next commands.
+
+## AI Agent Integration
+
+The CLI integrates with AI coding agents via skills, commands, agents, and hooks.
+
+- **Claude Code** - `tl setup claude`
+- **OpenCode** - `tl setup opencode`
+
+This repo is also a Claude Code plugin, and can directly be installed as one.
+
+### Skill content boundaries
+
+Skills under `skills/` are split into a `SKILL.md` and one or more `references/*.md` files. To prevent drift, each fact has exactly one home:
+
+- **CLI-shaped facts live in `SKILL.md`** — command surface, flags, filter syntax, output shapes, workflow, credit-cost curve, status-label mapping the CLI emits.
+- **Schema-shaped facts live in `references/`** — table/column catalogues, accepted-query rules for raw DB engines (PG/ES/Firebolt), index constraints, field types, ID formats.
+- **Business-shaped facts live in `references/business-glossary.md`** (or the equivalent glossary file) — revenue/pipeline definitions, performance grades, ownership semantics, MSN/TPP meaning, team rosters.
+
+When adding or updating skill content, place the fact in its single home and link from the others. Do not duplicate or "quick-recap" content across files — recaps are the highest drift surface.
+
+## API Response Envelope
+
+All list endpoints return: `{ results, total, limit, offset, usage: { credits_charged, credit_rate, balance_remaining }, _breadcrumbs }`.
+
+### Key Environment Variables
+
+- `TL_API_URL` — API base (default: `https://app.thoughtleaders.io`)
+- `TL_API_KEY` — Bearer token override for CI/scripts
+- `TL_AUTH0_DOMAIN`, `TL_AUTH0_CLIENT_ID`, `TL_AUTH0_AUDIENCE` — Auth0 config
+- `TL_LLM_KEY` — User's own LLM key for `tl ask` (avoids surcharge)
+
+## Credit System
+
+Every data query costs credits (rates vary by resource). `tl describe` shows rates, `tl balance` shows remaining. The `402` status means insufficient credits. Hooks automatically warn when balance drops below 500.
+
+## Version Bumps
+
+The version string is defined in three files and all three must be updated together:
+- `pyproject.toml` — `version = "x.y.z"`
+- `.claude-plugin/plugin.json` — `"version": "x.y.z"`
+- `src/tl_cli/__init__.py` — `__version__ = "x.y.z"`
+
+## Important Constraint
+
+`tl snapshots video` requires `--channel` flag — Firebolt queries without a channel partition are unbounded.
+
+## Coding
+
+* Do not reference internal architecture of the ThoughtLeaders app in comments or skills. Specifially: do not reference internal table names, field names, API endpoints, Python modules or functions (including the sanitizer).
+* Place all imports at the start of the Python module file
+
+# Git commit rules
+
+Do not reference internal architecture of the ThoughtLeaders app in commit messages.
+
+When a feature is purely server-side but changes the data the CLI receives (e.g. adding, removing, or renaming a field on a response, changing a credit rate, expanding an enum), make a forced empty commit on the tl-cli repo (`git commit --allow-empty`) describing the change. This keeps the CLI repo's history a complete log of what users see, even when no client code had to change.
+
+# Be aware of tests
+
+Be sure to check if tests need to be updated when changing any data structures or function names, in all repos involved in the change.

thoughtleaders_cli-0.5.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

thoughtleaders_cli-0.5.0/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.

thoughtleaders_cli-0.5.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,188 @@
+# 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.