thoughtleaders-cli 0.5.0__py3-none-any.whl

tl_cli/commands/changelog.py

@@ -0,0 +1,119 @@
+"""tl changelog — Show release notes for one or more CLI versions."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.text import Text
+
+from tl_cli import __version__
+from tl_cli.client.errors import ApiError, handle_api_error
+from tl_cli.client.http import get_client
+from tl_cli.self_update import _fetch_latest_version, _version_tuple
+
+
+def _normalize(v: str) -> str:
+    v = v.strip()
+    if not v:
+        return ''
+    return v if v.startswith('v') else f'v{v}'
+
+
+def _build_request_body(args: list[str]) -> tuple[dict, str | None]:
+    """Translate CLI args into the API request body. Returns (body, error_or_none)."""
+    if not args:
+        # No args: bound the request to either the current version (when up to
+        # date) or strictly the gap between current and latest. Never request
+        # the full version history.
+        latest = _fetch_latest_version()
+        current = f'v{__version__}'
+        if not latest:
+            return {'versions': [current]}, None
+        try:
+            if _version_tuple(latest) <= _version_tuple(__version__):
+                return {'versions': [current]}, None
+        except ValueError:
+            return {'versions': [current]}, None
+        return {'since': current}, None
+
+    if len(args) >= 2 and args[0].lower() == 'since':
+        since = _normalize(args[1])
+        if not since:
+            return {}, "'since' requires a version (e.g. tl changelog since v0.4.10)"
+        return {'since': since}, None
+
+    versions = [_normalize(v) for v in args if v.strip()]
+    if not versions:
+        return {}, 'no valid versions in arguments'
+    return {'versions': versions}, None
+
+
+def _render(data: dict, json_output: bool, md_output: bool) -> None:
+    results = data.get('results', []) or []
+
+    if json_output or (not sys.stdout.isatty() and not md_output):
+        print(json.dumps(data, indent=2, default=str))
+        return
+
+    if not results:
+        Console(stderr=True).print('[dim]No changelog entries returned.[/dim]')
+        return
+
+    if md_output:
+        for entry in results:
+            print(f"## {entry.get('version', '?')}")
+            date = entry.get('release_date') or ''
+            if date:
+                print(f"_Released {date}_\n")
+            print(entry.get('summary', '').strip() or '_(no summary)_')
+            print()
+        return
+
+    console = Console()
+    for entry in results:
+        version = entry.get('version', '?')
+        date = entry.get('release_date') or ''
+        title = Text(version, style='bold cyan')
+        if date:
+            title.append(f"  ·  released {date}", style='dim')
+        body = entry.get('summary', '').strip() or '_(no summary)_'
+        console.print(Panel(Markdown(body), title=title, title_align='left', border_style='cyan'))
+
+
+def changelog_command(
+    ctx: typer.Context,
+    json_output: bool = typer.Option(False, '--json', help='JSON output'),
+    md_output: bool = typer.Option(False, '--md', help='Markdown output (good for piping into a doc)'),
+) -> None:
+    """Show release notes for tl-cli versions.
+
+    Positional arguments are version numbers, or the special form
+    `since <version>` to get everything between that version and the latest
+    release. With no arguments, shows the current version's notes (or the
+    gap from current to latest if you're behind).
+
+    Examples:
+        tl changelog                       # current version (or current..latest if outdated)
+        tl changelog v0.4.17 v0.4.18       # explicit list
+        tl changelog since v0.4.10         # everything from v0.4.10 to latest
+        tl changelog --md > CHANGELOG.md   # capture for a doc
+    """
+    raw_args = [a for a in (ctx.args or []) if a and not a.startswith('-')]
+    body, err = _build_request_body(raw_args)
+    if err:
+        Console(stderr=True).print(f'[red]Error:[/red] {err}')
+        raise typer.Exit(2)
+
+    client = get_client()
+    try:
+        data = client.post('/changelog', json_body=body)
+        _render(data, json_output, md_output)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()

tl_cli/commands/channels.py

@@ -0,0 +1,291 @@
+"""tl channels — Search and show YouTube channels."""
+
+import urllib.parse
+
+import typer
+from rich.console import Console
+
+from tl_cli.client.errors import ApiError, handle_api_error
+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
+
+app = typer.Typer(help="YouTube channels (search, detail, and similar-channel recommendations)")
+
+# Columns for the `similar` endpoint result table. The server enriches every
+# row so the user can size up each suggestion without follow-up queries.
+SIMILAR_COLUMNS = ["score", "channel_id", "name", "msn", "tpp", "subscribers", "projected_views", "total_views", "cpm", "audience"]
+SIMILAR_COLUMN_CONFIG = {
+    "score": {"justify": "right"},
+    "subscribers": {"justify": "right"},
+    "projected_views": {"justify": "right"},
+    "total_views": {"justify": "right"},
+    "cpm": {"justify": "right"},
+}
+
+
+@app.callback(invoke_without_command=True)
+def channels(ctx: typer.Context) -> None:
+    """YouTube channels — search and detail."""
+    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 channels' 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:
+    """Search channels with optional filters.
+
+    Examples:
+        tl channels list                                  # List channels
+        tl channels list category:cooking min-subs:100k   # Search with filters
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    filters = parse_filters(args or [])
+
+    client = get_client()
+    try:
+        params = {**filters, "limit": str(limit), "offset": str(offset)}
+        data = client.get("/channels", params=params)
+        for r in data.get("results", []):
+            r["channel_id"] = r.pop("id", None)
+        output(
+            data,
+            fmt,
+            columns=["channel_id", "name", "url", "msn", "tpp", "subscribers", "gender", "countries", "category", "sponsorship_score", "trend"],
+            title="Channels",
+        )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("show")
+def show_cmd(
+    channel_ref: str = typer.Argument(..., help="Channel ID (numeric) or name (partial match, must be unique)"),
+    json_output: bool = typer.Option(False, "--json", help="JSON output"),
+    csv_output: bool = typer.Option(False, "--csv", help="CSV output (flattens adspots: one row per adspot)"),
+    toon_output: bool = typer.Option(False, "--toon", help="TOON output (token-efficient for LLMs)"),
+) -> None:
+    """Show channel detail by ID or name (includes active adspots).
+
+    Accepts either a numeric channel ID or a partial name. Names that
+    match more than one active channel return a 400 with the candidate
+    IDs listed so you can retry with a specific ID.
+
+    Examples:
+        tl channels show 12345
+        tl channels show "Economics Explained"
+        tl channels show 12345 --csv > channel.csv
+    """
+    fmt = detect_format(json_output, csv_output, False, toon_output)
+
+    encoded_ref = urllib.parse.quote(channel_ref, safe="")
+    client = get_client()
+    try:
+        data = client.get(f"/channels/{encoded_ref}")
+        for i, r in enumerate(data.get("results", []) if isinstance(data.get("results"), list) else []):
+            renamed = {}
+            for k, v in r.items():
+                if k == "id":
+                    renamed["channel_id"] = v
+                else:
+                    renamed[k] = v
+            data["results"][i] = renamed
+        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, channel=record.get("name"))
+                if hint:
+                    Console(stderr=True).print(f"\n[yellow]{hint}[/yellow]")
+    except ApiError as e:
+        _handle_channel_api_error(e)
+    finally:
+        client.close()
+
+
+def _handle_channel_api_error(e: ApiError) -> None:
+    """Print a candidates list for 400 responses with `candidates` in the
+    body (ambiguous channel name) and exit 1; otherwise defer to the
+    default handler. Used by both `show` and `similar` since they share
+    the server-side _resolve_channel helper and the same error shape.
+    """
+    if e.status_code == 400 and isinstance(e.raw, dict) and e.raw.get("candidates"):
+        err = Console(stderr=True)
+        err.print(f"[yellow]{e.detail}[/yellow]")
+        err.print()
+        err.print("[bold]Candidates:[/bold]")
+        err.print(f"  {'channel_id':>10}  {'subscribers':>12}  name")
+        err.print(f"  {'-' * 10}  {'-' * 12}  {'-' * 40}")
+        for c in e.raw["candidates"]:
+            subs = c.get("subscribers") or 0
+            err.print(f"  {c['channel_id']:>10}  {subs:>12,}  {c['name']}")
+        raise typer.Exit(1)
+    handle_api_error(e)
+
+
+def _format_score(results: list[dict]) -> list[dict]:
+    """Convert raw cosine score (0.0-1.0) to percentage string for table/csv/md."""
+    for row in results:
+        score = row.get("score")
+        if isinstance(score, (int, float)):
+            row["score"] = f"{score * 100:.1f}%"
+    return results
+
+
+def _do_similar(channel_ref: str, args: list[str], fmt: str, limit: int) -> None:
+    """Shared implementation for `similar` and `look-alike`.
+
+    Server-side filters: language, msn, min-score (passed through in the
+    query string). Client-side filters: category, min-subs, max-subs,
+    exclude (applied to the returned, enriched rows).
+    """
+    filters = parse_filters(args)
+
+    # Split filters into server-side and client-side sets.
+    server_keys = {"language", "msn", "min-score"}
+    server_params = {k: filters.pop(k) for k in list(filters) if k in server_keys}
+    server_params["limit"] = str(limit)
+
+    encoded_ref = urllib.parse.quote(channel_ref, safe="")
+    client = get_client()
+    try:
+        data = client.get(f"/channels/{encoded_ref}/similar", params=server_params)
+
+        # Client-side post-filters
+        results = data.get("results", [])
+        if "category" in filters:
+            target = filters["category"]
+            results = [r for r in results if str(r.get("category", "")) == target]
+        if "min-subs" in filters:
+            try:
+                n = int(filters["min-subs"])
+                results = [r for r in results if (r.get("subscribers") or 0) >= n]
+            except ValueError:
+                pass
+        if "max-subs" in filters:
+            try:
+                n = int(filters["max-subs"])
+                results = [r for r in results if (r.get("subscribers") or 0) <= n]
+            except ValueError:
+                pass
+        if "exclude" in filters:
+            excluded = {int(x) for x in filters["exclude"].split(",") if x.strip().isdigit()}
+            results = [r for r in results if r.get("id") not in excluded]
+
+        data["results"] = results
+        for r in data["results"]:
+            r["channel_id"] = r.pop("id", None)
+        if fmt in ("table", "md"):
+            _format_score(data["results"])
+        output(
+            data,
+            fmt,
+            columns=SIMILAR_COLUMNS,
+            title=f"Channels similar to {channel_ref}",
+            column_config=SIMILAR_COLUMN_CONFIG,
+        )
+    except ApiError as e:
+        _handle_channel_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("similar")
+def similar_cmd(
+    channel_ref: str = typer.Argument(..., help="Channel ID (numeric) or name (partial match, must be unique)"),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs). Run 'tl describe show channels' 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(20, "--limit", "-l", help="Max results (1-100)"),
+) -> None:
+    """Find channels similar to a given one (by id or name).
+
+    Costs 50 credits per call. Intelligence plan required. Results are
+    ranked by cosine similarity and enriched with subscribers, impression,
+    total_views, category, and the channel's representative CPM.
+
+    Server-side filters (pushed to the recommender):
+        language:<iso>      Restrict to a content language (default: en)
+        msn:<true|false>    Restrict to Media Selling Network (default: true)
+        min-score:<0-1>     Minimum cosine similarity (default: 0.5)
+
+    Client-side post-filters (applied after fetch):
+        category:<code>     Keep only rows matching this content_category
+        min-subs:<N>        Subscribers >= N
+        max-subs:<N>        Subscribers <= N
+        exclude:<id,id,…>   Drop specific channel ids
+
+    Examples:
+        tl channels similar 12345
+        tl channels similar "MrBeast" language:en msn:false
+        tl channels similar 12345 min-score:0.7 min-subs:1000000 --limit 10
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    _do_similar(channel_ref, args or [], fmt, limit)
+
+
+@app.command("history")
+def history_cmd(
+    channel_ref: str = typer.Argument(..., help="Channel ID (numeric) or name (partial match, must be unique)"),
+    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:
+    """Show a channel's sponsorship history (videos with detected sponsors).
+
+    Requires an Intelligence plan.
+
+    Examples:
+        tl channels history 157060
+        tl channels history "Economics Explained"
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    encoded_ref = urllib.parse.quote(channel_ref, safe="")
+    client = get_client()
+    try:
+        params = {"limit": str(limit), "offset": str(offset)}
+        data = client.get(f"/channels/{encoded_ref}/history", params=params)
+        channel_name = data.get("channel", {}).get("name", channel_ref)
+        output(
+            data,
+            fmt,
+            columns=["video_id", "title", "brands", "views", "publication_date", "is_tl"],
+            title=f"Channel History: {channel_name}",
+        )
+    except ApiError as e:
+        _handle_channel_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("look-alike", hidden=True)
+def look_alike_cmd(
+    channel_ref: str = typer.Argument(..., help="Channel ID or name"),
+    args: list[str] = typer.Argument(None, help="Filters (key:value pairs). Run 'tl describe show channels' 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(20, "--limit", "-l", help="Max results"),
+) -> None:
+    """Alias for `tl channels similar` (matches internal "look-alike channels" terminology)."""
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    _do_similar(channel_ref, args or [], fmt, limit)

tl_cli/commands/comments.py

@@ -0,0 +1,63 @@
+"""tl comments — List and add comments on sponsorships."""
+
+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, output_single
+
+app = typer.Typer(help="Comments on sponsorships (free, no credits)")
+
+
+@app.command("list")
+def list_cmd(
+    adlink_id: int = typer.Argument(..., help="Sponsorship (adlink) 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:
+    """List comments on a sponsorship (free, no credits).
+
+    Examples:
+        tl comments list 12345
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+
+    client = get_client()
+    try:
+        data = client.get(f"/comments/{adlink_id}")
+        for r in data.get("results", []):
+            r["comment_id"] = r.pop("id", None)
+        output(
+            data,
+            fmt,
+            columns=["comment_id", "author", "text", "created_at"],
+            title=f"Comments on Sponsorship #{adlink_id}",
+        )
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("add")
+def add_comment(
+    adlink_id: int = typer.Argument(..., help="Sponsorship (adlink) ID"),
+    message: str = typer.Argument(..., help="Comment text"),
+    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:
+    """Add a comment to a sponsorship (free, no credits).
+
+    Examples:
+        tl comments add 12345 "Looks good, ready to send"
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+
+    client = get_client()
+    try:
+        data = client.post(f"/comments/{adlink_id}", json_body={"text": message})
+        output_single(data, fmt)
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()

tl_cli/commands/db.py

@@ -0,0 +1,104 @@
+"""tl db — Run raw queries against PostgreSQL, Firebolt, or Elasticsearch."""
+
+import json
+import sys
+
+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="Raw read-only queries against PostgreSQL, Firebolt, or Elasticsearch (full-access only)")
+
+
+def _read_query(query: str | None) -> str:
+    if query is not None and query != "-":
+        return query
+    if sys.stdin.isatty():
+        raise typer.BadParameter("Provide a query argument or pipe one on stdin")
+    return sys.stdin.read()
+
+
+def _run(path: str, body: dict, fmt: str, title: str) -> None:
+    client = get_client()
+    try:
+        data = client.post(path, json_body=body)
+        output(data, fmt, title=title)
+        aggs = data.get("aggregations")
+        if aggs and fmt != "json":
+            from rich.console import Console
+            from rich.json import JSON
+            console = Console()
+            console.print("\n[bold]Aggregations[/bold]")
+            console.print(JSON(json.dumps(aggs, default=str)))
+    except ApiError as e:
+        handle_api_error(e)
+    finally:
+        client.close()
+
+
+@app.command("pg")
+def pg_cmd(
+    query: str = typer.Argument(None, help="Raw PostgreSQL SELECT (or '-' to read from stdin)"),
+    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"),
+) -> None:
+    """Run a raw PostgreSQL SELECT query.
+
+    Examples:
+        tl db pg "SELECT id, name FROM thoughtleaders_brand LIMIT 10 OFFSET 0"
+        cat query.sql | tl db pg -
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    sql = _read_query(query)
+    _run("/raw/pg", {"query": sql}, fmt, "Postgres results")
+
+
+@app.command("fb")
+def fb_cmd(
+    query: str = typer.Argument(None, help="Raw Firebolt SELECT (or '-' to read from stdin)"),
+    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"),
+) -> None:
+    """Run a raw Firebolt SELECT query.
+
+    The query must filter the leading index column of the table (channel_id
+    for article_metrics, id for channel_metrics) — see the Firebolt schema.
+
+    Examples:
+        tl db fb "SELECT scrape_date, view_count FROM article_metrics WHERE channel_id = 5607 AND id = 'EjeGzoQI3gQ'"
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    sql = _read_query(query)
+    _run("/raw/fb", {"query": sql}, fmt, "Firebolt results")
+
+
+@app.command("es")
+def es_cmd(
+    query: str = typer.Argument(None, help="Elasticsearch search body as JSON (or '-' to read from stdin)"),
+    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"),
+) -> None:
+    """Run a raw Elasticsearch search query.
+
+    The index is fixed server-side; the client cannot select it.
+
+    Examples:
+        tl db es '{"size": 5, "query": {"term": {"channel.id": 5607}}}'
+        tl db es '{"size": 0, "aggs": {"by_channel": {"terms": {"field": "channel.id"}}}}'
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    raw = _read_query(query)
+    try:
+        body_query = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"Query is not valid JSON: {exc}") from exc
+
+    _run("/raw/es", {"query": body_query}, fmt, "Elasticsearch results")

tl_cli/commands/deals.py

@@ -0,0 +1,52 @@
+"""tl deals — Shortcut for contractually agreed-upon sponsorships."""
+
+from typing import Optional
+
+import typer
+
+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.callback(invoke_without_command=True)
+def deals(ctx: typer.Context) -> None:
+    """Deals — contractually agreed-upon sponsorships."""
+    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 deals with optional filters.
+
+    Examples:
+        tl deals list                         # List recent deals
+        tl deals list brand:"Nike"            # Filter deals
+    """
+    fmt = detect_format(json_output, csv_output, md_output, toon_output)
+    do_list(args or [], fmt, limit, offset, default_status="deal", title="Deals")
+
+
+@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 deal detail by ID.
+
+    Examples:
+        tl deals show 12345
+    """
+    fmt = detect_format(json_output, False, False, toon_output)
+    do_show(item_id, fmt)