thoughtleaders-cli 0.5.0__py3-none-any.whl

tl_cli/commands/setup.py

@@ -0,0 +1,401 @@
+"""tl setup — Install Claude Code plugin and other integrations."""
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from tl_cli import __version__
+
+app = typer.Typer(help="Set up integrations (Claude Code, OpenCode)")
+console = Console(stderr=True)
+
+MARKETPLACE_SOURCE = "ThoughtLeaders-io/thoughtleaders-cli"
+MARKETPLACE_NAME = "thoughtleaders-plugins"
+PLUGIN_NAME = "tl-cli"
+PLUGIN_KEY = f"{PLUGIN_NAME}@{MARKETPLACE_NAME}"
+
+CLAUDE_HOME = Path.home() / ".claude"
+CLAUDE_PLUGINS_DIR = CLAUDE_HOME / "plugins"
+CLAUDE_SKILLS_DIR = CLAUDE_HOME / "skills"
+CLAUDE_COMMANDS_DIR = CLAUDE_HOME / "commands"
+
+OPENCODE_SKILLS_DIR = Path.home() / ".config" / "opencode" / "skills"
+
+
+def _find_plugin_root() -> Path | None:
+    """Locate the plugin assets directory.
+
+    Tries two locations:
+    1. _plugin/ inside the installed package (pip/pipx installs via hatch force-include)
+    2. Repo root relative to this file (editable installs)
+    """
+    bundled = Path(__file__).resolve().parent.parent / "_plugin"
+    if (bundled / ".claude-plugin" / "plugin.json").is_file():
+        return bundled
+
+    repo_root = Path(__file__).resolve().parent.parent.parent.parent
+    if (repo_root / ".claude-plugin" / "plugin.json").is_file():
+        return repo_root
+
+    return None
+
+
+def _find_claude_binary() -> str | None:
+    """Find the claude binary on PATH."""
+    return shutil.which("claude")
+
+
+def _run_claude(args: list[str], claude_bin: str) -> tuple[bool, str]:
+    """Run a claude CLI command and return (success, output)."""
+    try:
+        result = subprocess.run(
+            [claude_bin] + args,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        output = result.stdout.strip()
+        if result.returncode != 0:
+            output = result.stderr.strip() or output
+        return result.returncode == 0, output
+    except subprocess.TimeoutExpired:
+        return False, "Command timed out"
+    except Exception as e:
+        return False, str(e)
+
+
+def _get_installed_plugin_version() -> str | None:
+    """Try to read the installed plugin version from the cache."""
+    version_file = CLAUDE_PLUGINS_DIR / "tl-cli" / ".version"
+    if version_file.exists():
+        return version_file.read_text().strip()
+    return None
+
+
+def check_plugin_version() -> list[str]:
+    """Check if installed plugin versions match CLI version.
+
+    Returns a list of warning messages for outdated installs. Empty if all OK.
+    """
+    warnings = []
+
+    # Claude Code
+    claude_version_file = CLAUDE_PLUGINS_DIR / "tl-cli" / ".version"
+    if claude_version_file.exists():
+        installed = claude_version_file.read_text().strip()
+        if installed != __version__:
+            warnings.append(f"Claude Code plugin is outdated (v{installed} vs CLI v{__version__}). Run 'tl setup claude' to update.")
+
+    # OpenCode
+    opencode_version_file = OPENCODE_SKILLS_DIR / ".tl-version"
+    if opencode_version_file.exists():
+        installed = opencode_version_file.read_text().strip()
+        if installed != __version__:
+            warnings.append(f"OpenCode skill is outdated (v{installed} vs CLI v{__version__}). Run 'tl setup opencode' to update.")
+
+    return warnings
+
+
+def _install_standalone_skills(plugin_root: Path) -> int:
+    """Copy skills and commands to ~/.claude/ for non-namespaced invocation.
+
+    Returns the number of items installed.
+    """
+    count = 0
+
+    # Skills: skills/<name>/SKILL.md → ~/.claude/skills/<name>/SKILL.md
+    skills_src = plugin_root / "skills"
+    if skills_src.is_dir():
+        for skill_dir in skills_src.iterdir():
+            if skill_dir.is_dir() and (skill_dir / "SKILL.md").is_file():
+                dst = CLAUDE_SKILLS_DIR / skill_dir.name
+                if dst.exists():
+                    shutil.rmtree(dst)
+                shutil.copytree(skill_dir, dst)
+                count += 1
+
+    # Commands: commands/<name>.md → ~/.claude/commands/<name>.md
+    commands_src = plugin_root / "commands"
+    if commands_src.is_dir():
+        CLAUDE_COMMANDS_DIR.mkdir(parents=True, exist_ok=True)
+        for cmd_file in commands_src.glob("*.md"):
+            dst = CLAUDE_COMMANDS_DIR / cmd_file.name
+            shutil.copy2(cmd_file, dst)
+            count += 1
+
+    return count
+
+
+def _print_manual_instructions() -> None:
+    """Print manual install instructions when claude binary is not found."""
+    console.print()
+    console.print("[yellow]Claude Code binary not found on PATH.[/yellow]")
+    console.print()
+    console.print("Install Claude Code first, then run these commands inside Claude Code:")
+    console.print()
+    console.print(f"  [cyan]/plugin marketplace add {MARKETPLACE_SOURCE}[/cyan]")
+    console.print(f"  [cyan]/plugin install {PLUGIN_KEY}[/cyan]")
+    console.print()
+    console.print("Or start Claude Code with the plugin loaded directly:")
+    console.print()
+    console.print(f"  [cyan]claude --plugin-dir /path/to/tl-cli[/cyan]")
+
+
+@app.command("claude")
+def setup_claude(
+    json_output: bool = typer.Option(False, "--json", help="JSON output (non-interactive)"),
+) -> None:
+    """Install the TL CLI plugin for Claude Code.
+
+    Registers the ThoughtLeaders marketplace, installs the tl-cli plugin,
+    and copies skills/commands to ~/.claude/ for short /tl invocation.
+    If the claude binary is not on PATH, prints manual instructions.
+
+    Examples:
+        tl setup claude
+        tl setup claude --json
+    """
+    if json_output:
+        _setup_noninteractive()
+        return
+
+    console.print()
+    console.print(f"[bold]tl-cli[/bold] v{__version__} — Claude Code Plugin Setup")
+    console.print()
+
+    # Check tl is on PATH
+    tl_bin = shutil.which("tl")
+    if tl_bin:
+        console.print(f"  [green]✓[/green] tl CLI found: {tl_bin}")
+    else:
+        console.print("  [red]✗[/red] tl CLI not found on PATH")
+        console.print("    Claude Code's Bash tool won't be able to run tl commands.")
+        console.print("    Install with: [cyan]pipx install thoughtleaders-cli[/cyan]")
+
+    # Find plugin assets
+    plugin_root = _find_plugin_root()
+    if plugin_root is None:
+        console.print("  [red]✗[/red] Plugin assets not found")
+        console.print("    Try reinstalling: [cyan]pipx install thoughtleaders-cli[/cyan]")
+        raise SystemExit(1)
+    console.print(f"  [green]✓[/green] Plugin assets found: {plugin_root}")
+
+    # Check claude binary
+    claude_bin = _find_claude_binary()
+    if not claude_bin:
+        # Still install standalone skills even without claude binary
+        console.print("  [yellow]![/yellow] claude binary not found on PATH")
+        _install_standalone_skills_step(plugin_root)
+        console.print()
+        _print_manual_instructions()
+        raise SystemExit(1)
+
+    console.print(f"  [green]✓[/green] claude binary found: {claude_bin}")
+    console.print()
+
+    # Step 1: Register marketplace
+    console.print("[bold]Registering marketplace...[/bold]")
+    ok, output = _run_claude(["plugin", "marketplace", "add", MARKETPLACE_SOURCE], claude_bin)
+    if ok:
+        console.print(f"  [green]✓[/green] Marketplace registered: {MARKETPLACE_NAME}")
+    else:
+        if "already" in output.lower() or "exists" in output.lower():
+            console.print(f"  [green]✓[/green] Marketplace already registered: {MARKETPLACE_NAME}")
+            console.print("  Updating marketplace...")
+            _run_claude(["plugin", "marketplace", "update", MARKETPLACE_NAME], claude_bin)
+        else:
+            console.print(f"  [red]✗[/red] Marketplace registration failed: {output}")
+            _print_manual_instructions()
+            raise SystemExit(1)
+
+    # Step 2: Install plugin
+    console.print("[bold]Installing plugin...[/bold]")
+    ok, output = _run_claude(["plugin", "install", PLUGIN_KEY], claude_bin)
+    if ok:
+        console.print(f"  [green]✓[/green] Plugin installed: {PLUGIN_KEY}")
+    else:
+        if "already" in output.lower():
+            console.print(f"  [green]✓[/green] Plugin already installed: {PLUGIN_KEY}")
+        else:
+            console.print(f"  [red]✗[/red] Plugin installation failed: {output}")
+            console.print("    Try running inside Claude Code:")
+            console.print(f"    [cyan]/plugin install {PLUGIN_KEY}[/cyan]")
+            raise SystemExit(1)
+
+    # Step 3: Install standalone skills for short /tl invocation
+    _install_standalone_skills_step(plugin_root)
+
+    # Write version stamp
+    version_dir = CLAUDE_PLUGINS_DIR / "tl-cli"
+    version_dir.mkdir(parents=True, exist_ok=True)
+    (version_dir / ".version").write_text(__version__)
+
+    console.print()
+    console.print("[green]Setup complete![/green]")
+    console.print()
+    console.print("Available skills in Claude Code:")
+    console.print("  [cyan]/tl[/cyan]                  — data analyst (smart query router)")
+    console.print("  [cyan]/tl-sponsorships[/cyan]     — sponsorship lookup")
+    console.print("  [cyan]/tl-brands[/cyan]           — brand intelligence")
+    console.print("  [cyan]/tl-channels[/cyan]         — channel search")
+    console.print("  [cyan]/tl-reports[/cyan]          — saved reports")
+    console.print("  [cyan]/tl-balance[/cyan]          — credit balance")
+    console.print()
+    console.print("Try it:")
+    console.print("  [cyan]/tl Which channels did we sponsor in Q1?[/cyan]")
+    console.print()
+    console.print("[dim]To update, run: tl setup claude[/dim]")
+
+
+def _install_standalone_skills_step(plugin_root: Path) -> None:
+    """Install standalone skills and print status."""
+    console.print("[bold]Installing skills for /tl shortcut...[/bold]")
+    count = _install_standalone_skills(plugin_root)
+    if count > 0:
+        console.print(f"  [green]✓[/green] Installed {count} skills/commands to ~/.claude/")
+    else:
+        console.print("  [yellow]![/yellow] No skills found to install")
+
+
+def _setup_noninteractive() -> None:
+    """Non-interactive setup for --json/agent usage."""
+    result = {
+        "cli_version": __version__,
+        "marketplace_source": MARKETPLACE_SOURCE,
+        "marketplace_name": MARKETPLACE_NAME,
+        "plugin_key": PLUGIN_KEY,
+    }
+
+    plugin_root = _find_plugin_root()
+    if plugin_root is None:
+        result["status"] = "error"
+        result["error"] = "Plugin assets not found"
+        print(json.dumps(result, indent=2))
+        raise SystemExit(1)
+
+    claude_bin = _find_claude_binary()
+
+    # Register marketplace + install plugin (if claude binary available)
+    if claude_bin:
+        ok, output = _run_claude(["plugin", "marketplace", "add", MARKETPLACE_SOURCE], claude_bin)
+        if not ok and "already" not in output.lower() and "exists" not in output.lower():
+            result["marketplace_registered"] = False
+        else:
+            result["marketplace_registered"] = True
+            _run_claude(["plugin", "marketplace", "update", MARKETPLACE_NAME], claude_bin)
+
+        ok, output = _run_claude(["plugin", "install", PLUGIN_KEY], claude_bin)
+        result["plugin_installed"] = ok or "already" in output.lower()
+    else:
+        result["marketplace_registered"] = False
+        result["plugin_installed"] = False
+
+    # Always install standalone skills
+    count = _install_standalone_skills(plugin_root)
+    result["standalone_skills_installed"] = count
+
+    # Write version stamp
+    version_dir = CLAUDE_PLUGINS_DIR / "tl-cli"
+    version_dir.mkdir(parents=True, exist_ok=True)
+    (version_dir / ".version").write_text(__version__)
+
+    result["status"] = "ok"
+    print(json.dumps(result, indent=2))
+
+
+# --- OpenCode setup ---
+
+
+def _install_opencode_skills(plugin_root: Path) -> int:
+    """Copy skills to ~/.config/opencode/skills/ for OpenCode discovery.
+
+    Returns the number of skills installed.
+    """
+    count = 0
+    skills_src = plugin_root / "skills"
+    if skills_src.is_dir():
+        for skill_dir in skills_src.iterdir():
+            if skill_dir.is_dir() and (skill_dir / "SKILL.md").is_file():
+                dst = OPENCODE_SKILLS_DIR / skill_dir.name
+                if dst.exists():
+                    shutil.rmtree(dst)
+                shutil.copytree(skill_dir, dst)
+                count += 1
+    return count
+
+
+@app.command("opencode")
+def setup_opencode(
+    json_output: bool = typer.Option(False, "--json", help="JSON output (non-interactive)"),
+) -> None:
+    """Install the TL CLI skills for OpenCode.
+
+    Copies skill files to ~/.config/opencode/skills/ so OpenCode's
+    agent can discover and use them automatically.
+
+    Examples:
+        tl setup opencode
+        tl setup opencode --json
+    """
+    if json_output:
+        result = {"cli_version": __version__}
+        plugin_root = _find_plugin_root()
+        if plugin_root is None:
+            result["status"] = "error"
+            result["error"] = "Plugin assets not found"
+            print(json.dumps(result, indent=2))
+            raise SystemExit(1)
+        count = _install_opencode_skills(plugin_root)
+        OPENCODE_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+        (OPENCODE_SKILLS_DIR / ".tl-version").write_text(__version__)
+        result["skills_installed"] = count
+        result["status"] = "ok"
+        print(json.dumps(result, indent=2))
+        return
+
+    console.print()
+    console.print(f"[bold]tl-cli[/bold] v{__version__} — OpenCode Setup")
+    console.print()
+
+    # Check tl is on PATH
+    tl_bin = shutil.which("tl")
+    if tl_bin:
+        console.print(f"  [green]✓[/green] tl CLI found: {tl_bin}")
+    else:
+        console.print("  [red]✗[/red] tl CLI not found on PATH")
+        console.print("    OpenCode's Bash tool won't be able to run tl commands.")
+        console.print("    Install with: [cyan]pipx install git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git[/cyan]")
+
+    # Find plugin assets
+    plugin_root = _find_plugin_root()
+    if plugin_root is None:
+        console.print("  [red]✗[/red] Plugin assets not found")
+        console.print("    Try reinstalling: [cyan]pipx install --force git+https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git[/cyan]")
+        raise SystemExit(1)
+    console.print(f"  [green]✓[/green] Plugin assets found: {plugin_root}")
+    console.print()
+
+    # Install skills
+    console.print("[bold]Installing skills...[/bold]")
+    count = _install_opencode_skills(plugin_root)
+    if count > 0:
+        console.print(f"  [green]✓[/green] Installed {count} skill(s) to {OPENCODE_SKILLS_DIR}/")
+    else:
+        console.print("  [yellow]![/yellow] No skills found to install")
+        raise SystemExit(1)
+
+    # Write version stamp
+    OPENCODE_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+    (OPENCODE_SKILLS_DIR / ".tl-version").write_text(__version__)
+
+    console.print()
+    console.print("[green]Setup complete![/green]")
+    console.print()
+    console.print("OpenCode will automatically discover the tl skill.")
+    console.print("The agent can use it when you ask about sponsorships, deals, channels, or brands.")
+    console.print()
+    console.print("[dim]To update, run: tl setup opencode[/dim]")

tl_cli/commands/snapshots.py

@@ -0,0 +1,93 @@
+"""tl snapshots — Firebolt time-series metrics for channels and videos."""
+
+import typer
+
+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.command("channel")
+def channel_snapshots(
+    channel_id: int = typer.Argument(..., help="Channel ID"),
+    since: str | None = typer.Option(None, "--since", help="Start date (YYYY-MM-DD)"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(100, "--limit", "-l", help="Max data points"),
+) -> None:
+    """Channel metrics over time (subscribers, total views).
+
+    Requires a paid plan.
+
+    Examples:
+        tl snapshots channel 12345
+        tl snapshots channel 12345 --since 2025-01-01
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+
+    params: dict[str, str] = {"limit": str(limit)}
+    if since:
+        params["since"] = since
+
+    client = get_client()
+    try:
+        data = client.get(f"/snapshots/channel/{channel_id}", params=params)
+        output(
+            data,
+            fmt,
+            columns=["scrape_date", "reach", "total_views"],
+            title=f"Channel {channel_id} Metrics",
+        )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("video")
+def video_snapshots(
+    video_id: str = typer.Argument(..., help="Video/article ID"),
+    channel: int = typer.Option(
+        ..., "--channel", "-c",
+        help="Channel ID (required — Firebolt needs this for fast queries)",
+    ),
+    since: str | None = typer.Option(None, "--since", help="Start date (YYYY-MM-DD)"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(100, "--limit", "-l", help="Max data points"),
+) -> None:
+    """Video view curve over time (views, likes, comments by age).
+
+    --channel is required because Firebolt's primary index is (channel_id, id).
+    Without it, queries scan 7.4 billion rows.
+
+    Requires a paid plan.
+
+    Examples:
+        tl snapshots video dQw4w9WgXcQ --channel 12345
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+
+    params: dict[str, str] = {"channel_id": str(channel), "limit": str(limit)}
+    if since:
+        params["since"] = since
+
+    client = get_client()
+    try:
+        data = client.get(f"/snapshots/video/{video_id}", params=params)
+        output(
+            data,
+            fmt,
+            columns=["scrape_date", "age", "view_count", "like_count", "comment_count"],
+            title=f"Video {video_id} View Curve",
+        )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()

tl_cli/commands/sponsorships.py

@@ -0,0 +1,193 @@
+"""tl sponsorships — List, show, and create sponsorships."""
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from tl_cli.client.errors import handle_api_error, ApiError
+from tl_cli.client.http import get_client
+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
+
+COLUMNS = ["sponsorship_id", "created_at", "brand_id", "brand", "channel_id", "channel", "article_id", "views", "impressions_guarantee", "status", "price", "cost", "cpm", "owner_sales_email"]
+COLUMN_CONFIG = {
+    "price": {"justify": "right"},
+    "cost": {"justify": "right"},
+    "views": {"justify": "right"},
+    "impressions_guarantee": {"justify": "right"},
+    "cpm": {"justify": "right"},
+}
+
+
+def _format_results(results: list[dict]) -> list[dict]:
+    """Clean up sponsorship results for display."""
+    for row in results:
+        sd = row.get("send_date")
+        if sd and isinstance(sd, str) and "T" in sd:
+            row["send_date"] = sd[:10]
+        for field in ("price", "cost", "impressions_guarantee"):
+            val = row.get(field)
+            if val is not None:
+                try:
+                    row[field] = str(int(float(val)))
+                except (ValueError, TypeError):
+                    pass
+    return results
+
+
+def do_list(
+    args: list[str],
+    fmt: str,
+    limit: int,
+    offset: int,
+    *,
+    default_status: str | None = None,
+    title: str = "Sponsorships",
+) -> None:
+    """Shared list logic with optional default status filter."""
+    filters = parse_filters(args)
+
+    # Status values that are equivalent to each shortcut's default
+    _EQUIVALENT_STATUSES = {
+        "deal": {"deal", "sold"},
+        "match": {"match", "matched"},
+        "proposal": {"proposal", "proposed", "pending", "outreach"},
+    }
+
+    if default_status and "status" in filters:
+        allowed = _EQUIVALENT_STATUSES.get(default_status, {default_status})
+        if filters["status"] not in allowed:
+            Console(stderr=True).print(
+                f"[red]Error:[/red] The [bold]{title.lower()}[/bold] command does not accept status:{filters['status']}.\n"
+                f"Use [bold]tl sponsorships list[/bold] for finer-grained status filtering."
+            )
+            raise typer.Exit(1)
+
+    if default_status:
+        filters.setdefault("status", default_status)
+
+    client = get_client()
+    try:
+        params = {**filters, "limit": str(limit), "offset": str(offset)}
+        data = client.get("/sponsorships", params=params)
+        if "results" in data:
+            data["results"] = _format_results(data["results"])
+            for r in data["results"]:
+                r["sponsorship_id"] = r.pop("id", None)
+        output(data, fmt, columns=COLUMNS, title=title, column_config=COLUMN_CONFIG)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+def do_show(item_id: str, fmt: str) -> None:
+    """Shared show logic."""
+    client = get_client()
+    try:
+        data = client.get(f"/sponsorships/{item_id}")
+        for r in (data.get("results", []) if isinstance(data.get("results"), list) else []):
+            r["sponsorship_id"] = r.pop("id", None)
+        output_single(data, fmt)
+        if fmt == "table" and data.get("show_cta"):
+            record = data.get("results", data)
+            if isinstance(record, list) and record:
+                record = record[0]
+            if isinstance(record, dict):
+                hint = detail_hint(client, brand=record.get("brand"), channel=record.get("channel"))
+                if hint:
+                    Console(stderr=True).print(f"\n[yellow]{hint}[/yellow]")
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+def do_create(
+    channel: int,
+    brand: int,
+    price: float | None,
+    fmt: str,
+    status: str | None = None,
+) -> None:
+    """Shared create logic."""
+    body: dict = {"channel_id": channel, "brand_id": brand}
+    if price is not None:
+        body["price"] = price
+    if status is not None:
+        body["status"] = status
+
+    client = get_client()
+    try:
+        data = client.post("/sponsorships", json_body=body)
+        output_single(data, fmt)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+# --- Typer app ---
+
+app = typer.Typer(help="Sponsorships (deals, matches, proposals)")
+
+
+@app.callback(invoke_without_command=True)
+def sponsorships(ctx: typer.Context) -> None:
+    """Sponsorships — the centre of attention in ThoughtLeaders."""
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(list_cmd, args=[], json_output=False, csv_output=False, md_output=False, limit=50, offset=0)
+
+
+@app.command("list")
+def list_cmd(
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs). Run 'tl describe show sponsorships' for available filters."),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output"),
+    md_output: bool = typer.Option(False, "--md", help="Markdown output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results"),
+    offset: int = typer.Option(0, "--offset", help="Pagination offset"),
+) -> None:
+    """List sponsorships with optional filters.
+
+    Examples:
+        tl sponsorships list                              # List recent sponsorships
+        tl sponsorships list status:sold brand:"Nike"     # Filter sponsorships
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    do_list(args or [], fmt, limit, offset)
+
+
+@app.command("show")
+def show_cmd(
+    item_id: str = typer.Argument(..., help="Sponsorship ID"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Show sponsorship detail by ID.
+
+    Examples:
+        tl sponsorships show 12345
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    do_show(item_id, fmt)
+
+
+@app.command("create")
+def create_cmd(
+    channel: int = typer.Option(..., "--channel", "-c", help="Channel ID"),
+    brand: int = typer.Option(..., "--brand", "-b", help="Brand ID"),
+    price: Optional[float] = typer.Option(None, "--price", "-p", help="Deal price"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Create a new sponsorship proposal (free, no credits charged).
+
+    Examples:
+        tl sponsorships create --channel 1 --brand 2
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    do_create(channel, brand, price, fmt, status="proposed")