thoughtleaders-cli 0.9.13__tar.gz → 0.9.14__tar.gz

{thoughtleaders_cli-0.9.13 → thoughtleaders_cli-0.9.14}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.9.13",
+  "version": "0.9.14",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

{thoughtleaders_cli-0.9.13 → thoughtleaders_cli-0.9.14}/AGENTS.md

@@ -19,7 +19,7 @@ When adding a new data command, follow this pattern. See `sponsorships.py` for t
 
 ## Auth Flow (`auth/`)
 
-- **PKCE + Auth0**: Browser-based login with localhost callback server (`login.py`)
+- **PKCE + Auth0**: Browser-based login with a localhost callback server (`login.py`) against `auth.thoughtleaders.io`, the host the web platform and the Chrome extension sign in on, so a browser already signed in to the platform completes `tl auth login` without a password; the callback then sends that browser to the platform's `/signin?go=1&from=cli` so the web session follows. `tl auth logout` posts once to `/auth/sign-out` and ThoughtLeaders signs the user out everywhere; the CLI then revokes its refresh token and clears the local store. A 401 with `code: signed_out` means the session ended elsewhere, so the client drops its credentials instead of refreshing (`forget_session`).
 - **Token Storage** (`token_store.py`): OS keyring primary, `~/.config/tl/credentials.json` fallback (chmod 0o600)
 - **Env override**: `TL_API_KEY` env var takes priority over keyring (for CI)
 - **Auto-refresh**: `TLClient` refreshes expired tokens on 401

{thoughtleaders_cli-0.9.13 → thoughtleaders_cli-0.9.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thoughtleaders-cli
-Version: 0.9.13
+Version: 0.9.14
 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
@@ -122,9 +122,15 @@ tl setup codex         # install Codex CLI skill (optional)
 
 `tl auth login` offers three options:
 
-1. **OAuth2 in a local browser** (default) — opens a URL on this machine.
+1. **OAuth2 in a local browser** (default) — opens a URL on this machine. If that browser is already signed in to the web platform, no password is asked; either way the browser ends up signed in to the platform too, and the Chrome extension follows. Pass `--no-browser` to print the URL instead of opening a window.
 2. **Device code** — for headless environments; complete the flow on another device.
-3. **API key** — paste a pre-issued `APIKey` from Django admin. The CLI verifies it via `/whoami` and stores it tagged so every request sends `X-TL-Auth: API-KEY`.
+3. **API key** — paste an API key issued to you by ThoughtLeaders. The CLI verifies it via `/whoami` and stores it tagged so every request sends `X-TL-Auth: API-KEY`.
+
+Pass `--method browser|device|api-key` to skip the menu; without a terminal the menu is an error, so agents must pass it. Without a terminal the browser method prints the URL instead of opening a window (`--no-browser` does the same at a terminal).
+
+`tl auth logout` signs you out everywhere — this machine, the web platform, the Chrome extension and any other machine running `tl`. It is always global: there is no local-only logout. If ThoughtLeaders can't be reached, this machine's credentials are still cleared, but your other sessions stay signed in until you sign out on the web platform.
+
+`tl auth status` prints who you are signed in as; `--quiet` prints nothing and just exits 0 when the next command will authenticate and 2 when it will not, which is what agent hooks check.
 
 ## Quick Start
 
@@ -180,7 +186,6 @@ tl channels similar "Tremending girls" min-score:0.85 --limit 5
 tl recommender tags                              # List every tag (free)
 tl recommender tags cooking                      # Search tag names by substring
 tl recommender top-channels "Cooking" msn:yes --limit 50   # Top channels for a tag
-tl recommender top-profiles "Cooking" mbn:yes --limit 30   # Top brand profiles (one brand → potentially multiple profiles)
 tl recommender top-brands "Cooking" --limit 30             # Top brands (deduped from profiles)
 tl recommender channels-with-tag "Cooking"                 # ALL channel IDs loaded on a tag (--min defaults to 0.00001; paged; 1 credit/result)
 tl recommender inspect-channel 12345             # Per-tag breakdown of a channel's vector

{thoughtleaders_cli-0.9.13 → thoughtleaders_cli-0.9.14}/README.md

@@ -94,9 +94,15 @@ tl setup codex         # install Codex CLI skill (optional)
 
 `tl auth login` offers three options:
 
-1. **OAuth2 in a local browser** (default) — opens a URL on this machine.
+1. **OAuth2 in a local browser** (default) — opens a URL on this machine. If that browser is already signed in to the web platform, no password is asked; either way the browser ends up signed in to the platform too, and the Chrome extension follows. Pass `--no-browser` to print the URL instead of opening a window.
 2. **Device code** — for headless environments; complete the flow on another device.
-3. **API key** — paste a pre-issued `APIKey` from Django admin. The CLI verifies it via `/whoami` and stores it tagged so every request sends `X-TL-Auth: API-KEY`.
+3. **API key** — paste an API key issued to you by ThoughtLeaders. The CLI verifies it via `/whoami` and stores it tagged so every request sends `X-TL-Auth: API-KEY`.
+
+Pass `--method browser|device|api-key` to skip the menu; without a terminal the menu is an error, so agents must pass it. Without a terminal the browser method prints the URL instead of opening a window (`--no-browser` does the same at a terminal).
+
+`tl auth logout` signs you out everywhere — this machine, the web platform, the Chrome extension and any other machine running `tl`. It is always global: there is no local-only logout. If ThoughtLeaders can't be reached, this machine's credentials are still cleared, but your other sessions stay signed in until you sign out on the web platform.
+
+`tl auth status` prints who you are signed in as; `--quiet` prints nothing and just exits 0 when the next command will authenticate and 2 when it will not, which is what agent hooks check.
 
 ## Quick Start
 
@@ -152,7 +158,6 @@ tl channels similar "Tremending girls" min-score:0.85 --limit 5
 tl recommender tags                              # List every tag (free)
 tl recommender tags cooking                      # Search tag names by substring
 tl recommender top-channels "Cooking" msn:yes --limit 50   # Top channels for a tag
-tl recommender top-profiles "Cooking" mbn:yes --limit 30   # Top brand profiles (one brand → potentially multiple profiles)
 tl recommender top-brands "Cooking" --limit 30             # Top brands (deduped from profiles)
 tl recommender channels-with-tag "Cooking"                 # ALL channel IDs loaded on a tag (--min defaults to 0.00001; paged; 1 credit/result)
 tl recommender inspect-channel 12345             # Per-tag breakdown of a channel's vector

{thoughtleaders_cli-0.9.13 → thoughtleaders_cli-0.9.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.9.13"
+version = "0.9.14"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"

{thoughtleaders_cli-0.9.13 → thoughtleaders_cli-0.9.14}/skills/tl/SKILL.md

@@ -124,7 +124,7 @@ When querying sponsorship bookings, filter the rows with `publish_status = 3` (s
 
 Where possible, if searching for a sponsorship match between channels and brands, first search for what do similar brands sponsor / which brands is the channel usually sponsored by. The similarity judgement should be preferably based on similar topics, similar upload frequency, similar channel sizes, and only after all that, on demographics.
 
-Use the `tl channels similar` and `tl brands similar` commands to find channels or brands similar to a particular channel or brand. For category- or topic-driven discovery (e.g. "Find me Cooking channels", "Who scores high on USA share?"), use `tl recommender top-channels "<tag>"` (or `top-brands`/`top-profiles`) against the recommender — that's faster, ranked by category-strength. Run `tl recommender tags` to discover the valid tag names.
+Use the `tl channels similar` and `tl brands similar` commands to find channels or brands similar to a particular channel or brand. For category- or topic-driven discovery (e.g. "Find me Cooking channels", "Who scores high on USA share?"), use `tl recommender top-channels "<tag>"` (or `top-brands`) against the recommender — that's faster, ranked by category-strength. Run `tl recommender tags` to discover the valid tag names.
 
 ## Workflow
 
@@ -205,7 +205,6 @@ tl brands find <query>                 # Resolve a string to {id, name}; matches
 tl brands similar <id-or-name>         # Find similar brands via similarity search
 tl recommender tags [query]            # List similarity tag names — categories, demographics, formats
 tl recommender top-channels "<tag>"    # Top channels loaded on a similarity tag (Intelligence)
-tl recommender top-profiles "<tag>"    # Top brand profiles loaded on a similarity tag
 tl recommender top-brands "<tag>"      # Top brands (deduped from profiles) loaded on a similarity tag
 tl recommender channels-with-tag "<tag>" [--min <v>] # ALL channel IDs scoring >= v on a tag (--min default 0.00001 drops zero-loading channels; paged, enumerates the full set; 1 credit/result; Intelligence)
 tl recommender inspect-channel <ref>   # Show a channel's similarity-profile breakdown (Intelligence)
@@ -591,7 +590,7 @@ tl brands find "NordVPN"
 
 `tl channels find` resolves spacing/typo variants on its own ("Deco Destiny" → "DecoDestiny") via YouTube lookups and fuzzy similarity matching — no need to retry with hand-made name variations. A real channel that isn't in the index yet gets queued for analysis automatically (the response says to check back in ~24 hours). A plain "Not found" means even YouTube couldn't find it — treat that as the answer.
 
-**Path 2. Curated tag / category / demographic** — user named a topic that maps cleanly to a recommender tag (`"Cooking"`, `"Tech"`, `"USA share"`, content categories, format hints). Use the recommender — it ranks channels by how strongly they load on a tag, returning ranked similarity scores instead of forcing exact equality. It also returns matching brand profiles alongside the channels — useful when the user wants to know "who buys this kind of inventory."
+**Path 2. Curated tag / category / demographic** — user named a topic that maps cleanly to a recommender tag (`"Cooking"`, `"Tech"`, `"USA share"`, content categories, format hints). Use the recommender — it ranks channels by how strongly they load on a tag, returning ranked similarity scores instead of forcing exact equality. It also ranks brands on the same tags (`top-brands`) — useful when the user wants to know "who buys this kind of inventory."
 
 ```bash
 # Discover the available tag name first (free)
@@ -600,7 +599,7 @@ tl recommender tags cooking
 # Discover tag names containing the substring
 tl recommender tags crypto
 
-# Top channels & profiles loaded on a similarity tag (Intelligence)
+# Top channels & brands loaded on a similarity tag (Intelligence)
 tl recommender top-channels "Cooking" msn:yes --limit 50
 tl recommender top-channels "Tech" --limit 30
 tl recommender top-brands "USA share" mbn:yes --limit 50
@@ -611,7 +610,6 @@ tl recommender top-brands "USA share" mbn:yes --limit 50
 | Command | Filters |
 | --- | --- |
 | `top-channels` | `msn:<yes\|no\|all>` (default all), `exclude-for-profile:<id>` |
-| `top-profiles` | `mbn:<yes\|no\|all>` (default all), `exclude-for-channel:<id>` |
 | `top-brands` | `mbn:<yes\|no\|all>` (default all) |
 | `channels-for-profile` | `language:<iso>` (default `en`), `msn:<yes\|no>` (default `no`) |
 | `channels-for-brand` | same as `channels-for-profile` |
@@ -887,7 +885,6 @@ tl channels similar 29834 min-subs:1000000 exclude:477487 --limit 15  # client-s
 tl recommender tags                                            # Full tag list (free)
 tl recommender tags cooking                                    # Search tag names by substring
 tl recommender top-channels "Cooking" msn:yes --limit 50       # Top channels loaded on a tag (25 credits)
-tl recommender top-profiles "Cooking" --limit 30               # Top brand profiles for the tag
 tl recommender top-brands "USA share" mbn:yes --limit 30       # Top brands (deduped) — demographic tag, MBN only
 tl recommender top-channels "Tech" exclude-for-profile:842     # Drop channels already proposed for profile 842
 tl recommender inspect-channel 29834                           # Per-tag breakdown of a channel's vector

{thoughtleaders_cli-0.9.13 → thoughtleaders_cli-0.9.14}/skills/tl/references/firebolt-schema.md

@@ -63,7 +63,7 @@ Tracks YouTube video metrics over time. Each row = one scrape of one video on on
 
 **Primary Index: `(channel_id, id)`** — queries MUST filter by `channel_id` first.
 
-**Shorts vs Longform:** `duration < 61` = Short. `duration >= 61` = Longform. In code: `(duration or 100) < 61`. Filter client-side after fetching — `duration` isn't an indexed column so it can't go in WHERE.
+**Shorts vs Longform:** `article_metrics` has no `content_type` column, and `duration` cannot stand in for one — YouTube counts uploads up to 180s as Shorts, so any duration cutoff mislabels them. Take the split from Elasticsearch's `content_type` (`longform` / `short` / `live`), matching on the document id `<channel_id>:<video_id>`.
 
 ### `channel_metrics` — Channel-Level Time-Series
 
@@ -158,7 +158,7 @@ tl db fb "SELECT id, age, view_count FROM article_metrics
           ORDER BY id, age"
 ```
 
-For non-indexed filters (`age IN (30, 180)`, `duration > 60`), pull a slightly wider slice and filter in `jq`/Python.
+For non-indexed filters (`age IN (30, 180)`, `view_count > 1000`), pull a slightly wider slice and filter in `jq`/Python.
 
 ## Common Query Patterns
 
@@ -171,16 +171,18 @@ tl db fb "SELECT id, age, view_count, like_count, comment_count, duration
           ORDER BY age"
 ```
 
-### Get all videos for a channel, then filter client-side to milestone ages and longform
+### Get all videos for a channel, then filter client-side to milestone ages
 
 ```bash
 tl db fb "SELECT id, age, view_count, like_count, comment_count, duration, publication_date
           FROM article_metrics
           WHERE channel_id = 12345
           ORDER BY id, age" --json \
-| jq '.results[] | select(.duration > 60 and (.age == 7 or .age == 30 or .age == 60 or .age == 90 or .age == 180 or .age == 365))'
+| jq '.results[] | select(.age == 7 or .age == 30 or .age == 60 or .age == 90 or .age == 180 or .age == 365)'
 ```
 
+To keep longform only, pull `content_type` from Elasticsearch and intersect on video id — Firebolt cannot tell Shorts apart.
+
 ### Channel subscriber/view growth over time
 
 ```bash

{thoughtleaders_cli-0.9.13 → thoughtleaders_cli-0.9.14}/src/tl_cli/__init__.py

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

thoughtleaders_cli-0.9.14/src/tl_cli/auth/commands.py

@@ -0,0 +1,329 @@
+"""Auth CLI commands: tl auth login/logout/status."""
+
+import sys
+import time
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.prompt import Prompt
+
+from tl_cli._typer_utils import AlphaSortedTyperGroup
+from tl_cli.auth.login import login_browser, login_device_code, revoke_refresh_token
+from tl_cli.auth.token_store import KIND_API_KEY, StoredTokens, clear_tokens, load_tokens, save_tokens
+from tl_cli.client.errors import SIGNED_OUT_CODE, ApiError
+from tl_cli.client.http import get_client
+from tl_cli.config import get_config
+
+app = typer.Typer(cls=AlphaSortedTyperGroup, help="Authentication commands")
+console = Console(stderr=True)
+
+
+def _read_masked(prompt: str) -> str:
+    """Read a line of input echoing `*` for each character.
+
+    Falls back to plain `input()` when stdin is not a TTY (piped input,
+    test harness). Uses stdlib `termios` on Unix and `msvcrt` on Windows
+    so no extra dependency is needed.
+    """
+    if not sys.stdin.isatty():
+        return input(prompt)
+
+    sys.stdout.write(prompt)
+    sys.stdout.flush()
+
+    buf: list[str] = []
+    if sys.platform == 'win32':
+        import msvcrt
+        while True:
+            ch = msvcrt.getwch()
+            if ch in ('\r', '\n'):
+                sys.stdout.write('\n')
+                sys.stdout.flush()
+                break
+            if ch == '\x03':  # Ctrl-C
+                raise KeyboardInterrupt
+            if ch in ('\b', '\x7f'):
+                if buf:
+                    buf.pop()
+                    sys.stdout.write('\b \b')
+                    sys.stdout.flush()
+                continue
+            buf.append(ch)
+            sys.stdout.write('*')
+            sys.stdout.flush()
+    else:
+        import termios
+        import tty
+        fd = sys.stdin.fileno()
+        old = termios.tcgetattr(fd)
+        try:
+            tty.setcbreak(fd)
+            while True:
+                ch = sys.stdin.read(1)
+                if ch in ('\r', '\n'):
+                    sys.stdout.write('\n')
+                    sys.stdout.flush()
+                    break
+                if ch == '\x03':
+                    raise KeyboardInterrupt
+                if ch in ('\b', '\x7f'):
+                    if buf:
+                        buf.pop()
+                        sys.stdout.write('\b \b')
+                        sys.stdout.flush()
+                    continue
+                buf.append(ch)
+                sys.stdout.write('*')
+                sys.stdout.flush()
+        finally:
+            termios.tcsetattr(fd, termios.TCSADRAIN, old)
+
+    return ''.join(buf)
+
+
+LOGIN_METHODS = {"browser": "1", "device": "2", "api-key": "3"}
+
+
+def _interactive() -> bool:
+    """Is a person at a terminal — i.e. may we ask a question or open a browser
+    window? Output goes to stderr, so that is the stream that matters; stdout
+    may well be a file or a pipe in a perfectly interactive session."""
+    return sys.stdin.isatty() and sys.stderr.isatty()
+
+
+@app.command("login", help="Log in to ThoughtLeaders.")
+def login_cmd(
+    method: str | None = typer.Option(
+        None,
+        "--method",
+        "-m",
+        help="Skip the menu: browser (OAuth2 on this machine), device (code for another "
+        "device), or api-key. Required when there is no terminal to answer the menu.",
+    ),
+    no_browser: bool = typer.Option(
+        False,
+        "--no-browser",
+        help="Browser method only: print the login URL instead of opening a browser, then wait "
+        "up to two minutes for it to be opened on this machine. Implied when there is no "
+        "terminal, so a window never pops up at an agent.",
+    ),
+) -> None:
+    """Log in to ThoughtLeaders.
+
+    The default flow opens a browser on this machine for OAuth2 (Auth0). If
+    you are already signed in to the web platform in that browser, it
+    completes without a password; either way it leaves the browser signed in
+    to the platform too, and the Chrome extension follows. A device-code flow
+    is available for headless environments, and a pre-issued API key can be
+    configured for CI/scripts.
+    """
+    if method is not None:
+        if method not in LOGIN_METHODS:
+            console.print(
+                f"[red]Unknown --method {method!r}.[/red] "
+                f"Choose one of: {', '.join(LOGIN_METHODS)}"
+            )
+            raise typer.Exit(1)
+        choice = LOGIN_METHODS[method]
+    elif not _interactive():
+        console.print(
+            "[red]No terminal to answer the login menu.[/red] "
+            "Pass --method browser, --method device or --method api-key."
+        )
+        raise typer.Exit(2)
+    else:
+        console.print("[bold]How would you like to authenticate?[/bold]")
+        console.print(
+            "  [cyan]1[/cyan] — OAuth2 in a browser on this machine "
+            "[dim](default — opens a URL in the local browser)[/dim]"
+        )
+        console.print("  [cyan]2[/cyan] — Device code (use a browser on another device)")
+        console.print("  [cyan]3[/cyan] — API key (paste a pre-issued key; for CI / non-interactive use)")
+        console.print()
+        choice = Prompt.ask("Choose", choices=["1", "2", "3"], default="1", console=console)
+
+    if choice == "3":
+        _login_api_key()
+        return
+
+    if choice == "2":
+        login_device_code()
+    else:
+        login_browser(open_browser=not no_browser and _interactive())
+
+
+def _login_api_key() -> None:
+    """Store a user-supplied API key as the active credential.
+
+    No browser, no finalize call — the server has already issued this key
+    against an existing user/organization. The stored record is tagged
+    `kind=api_key` so the HTTP client sends `X-TL-Auth: API-KEY` on every
+    request. We immediately call /whoami to (a) verify the key is valid and
+    (b) capture the owning user's email for `tl auth status` output.
+    """
+    key = _read_masked("Paste your API key: ").strip()
+    if not key:
+        console.print("[red]No key provided.[/red]")
+        raise typer.Exit(1)
+
+    save_tokens(
+        StoredTokens(
+            access_token=key,
+            refresh_token=None,
+            expires_at=time.time() + 10 * 365 * 24 * 3600,
+            email=None,
+            kind=KIND_API_KEY,
+        )
+    )
+
+    client = get_client()
+    try:
+        data = client.get("/whoami")
+    except ApiError as e:
+        clear_tokens()
+        console.print(f"[red]API key rejected:[/red] {escape(e.detail)}")
+        raise typer.Exit(1)
+    finally:
+        client.close()
+
+    email = (data.get("user") or {}).get("email")
+    if not email:
+        clear_tokens()
+        console.print(
+            "[red]API key accepted but the server returned no email for the owning user.[/red] "
+            "This usually means the user record is incomplete — contact support."
+        )
+        raise typer.Exit(1)
+
+    save_tokens(
+        StoredTokens(
+            access_token=key,
+            refresh_token=None,
+            expires_at=time.time() + 10 * 365 * 24 * 3600,
+            email=email,
+            kind=KIND_API_KEY,
+        )
+    )
+    console.print(f"[green]API key stored.[/green] Authenticated as: {email}")
+
+
+@app.command("logout")
+def logout_cmd() -> None:
+    """Sign out of ThoughtLeaders everywhere.
+
+    Every sign-out is global: ThoughtLeaders ends this session on every surface
+    and device — the web platform, the Chrome extension and any other machine
+    running `tl` — and this machine then revokes and clears its own stored
+    credentials.
+    """
+    tokens = load_tokens()
+    if tokens is None and get_config().api_key:
+        # An API key from the environment is not a session and is not ours to
+        # remove; with nothing stored there is nothing to clear either.
+        console.print(
+            "[yellow]TL_API_KEY is set in your environment; it is not a session and stays in effect. "
+            "Nothing is stored on this machine to clear.[/yellow]"
+        )
+        return
+    outcome = SIGNED_OUT
+    if tokens and tokens.is_api_key:
+        # An API key is not a session — it was issued in advance and nothing
+        # about it ends by signing out. Clearing it here is all there is to do.
+        console.print("[dim]An API key is not a session; clearing this machine's stored key.[/dim]")
+    elif tokens:
+        outcome = _sign_out_everywhere()
+        # That call may have refreshed the session (rotating the refresh token)
+        # or, finding it already ended, cleared the store: revoke what is there now.
+        tokens = load_tokens()
+    # Revoke the long-lived credential so a leaked/synced copy of the local
+    # token store can't keep minting access tokens. Best-effort — API-key auth
+    # has no refresh token, and an offline revoke must not block clearing the
+    # local credentials.
+    if tokens and not tokens.is_api_key and tokens.refresh_token:
+        if revoke_refresh_token(tokens.refresh_token):
+            console.print("[dim]Refresh token revoked at Auth0.[/dim]")
+        else:
+            console.print(
+                "[yellow]Could not reach Auth0 to revoke the refresh token; "
+                "clearing local credentials anyway.[/yellow]"
+            )
+    clear_tokens()
+    console.print("[green]Logged out successfully.[/green]")
+    if outcome == UNREACHABLE:
+        console.print(
+            "[yellow]Could not reach ThoughtLeaders to sign out everywhere. This machine's credentials "
+            "are cleared, but your other sessions stay signed in; sign out on the web platform once "
+            "you are online to end them.[/yellow]"
+        )
+    elif outcome == REFUSED:
+        console.print("[yellow]Your other sessions stay signed in; sign out on the web platform to end them.[/yellow]")
+
+
+# What telling ThoughtLeaders about a sign-out came to.
+SIGNED_OUT = "signed_out"  # recorded now, or already by another surface
+REFUSED = "refused"  # ThoughtLeaders answered, and said no
+UNREACHABLE = "unreachable"  # no answer at all
+
+
+def _sign_out_everywhere() -> str:
+    """Ask ThoughtLeaders to end this session everywhere. Best effort: nothing
+    here may stop the local logout — not an unreachable service, and not a token
+    refresh giving up (`SystemExit`). Speaks for the stored session even when
+    `TL_API_KEY` is set: that key is not the session being ended."""
+    client = None
+    try:
+        client = get_client(stored_session_only=True)
+        client.post("/auth/sign-out", json_body={})
+        console.print("[dim]Signed out everywhere.[/dim]")
+        return SIGNED_OUT
+    except ApiError as e:
+        if isinstance(e.raw, dict) and e.raw.get("code") == SIGNED_OUT_CODE:
+            # Someone got there first: this session was already ended
+            # elsewhere, which is exactly the state we were after.
+            console.print("[dim]Already signed out everywhere.[/dim]")
+            return SIGNED_OUT
+        console.print(f"[yellow]ThoughtLeaders did not sign you out everywhere: {escape(e.detail)}[/yellow]")
+        return REFUSED
+    except (Exception, SystemExit):  # noqa: BLE001 — declared best-effort: nothing may stop the local logout
+        return UNREACHABLE
+    finally:
+        if client is not None:
+            client.close()
+
+
+@app.command("status")
+def status_cmd(
+    quiet: bool = typer.Option(
+        False, "--quiet", "-q", help="Print nothing; exit 0 if logged in, 2 otherwise."
+    ),
+) -> None:
+    """Show current authentication status: exit 0 when the next command will
+    authenticate, 2 when it will not."""
+    if get_config().api_key:
+        # TL_API_KEY wins over anything stored (see the HTTP client), so this
+        # machine is authenticated whatever the keychain holds.
+        if not quiet:
+            console.print("[green]Authenticated[/green] via API key from TL_API_KEY.")
+        return
+
+    tokens = load_tokens()
+    if not tokens:
+        if not quiet:
+            console.print("[yellow]Not logged in.[/yellow] Run: tl auth login")
+        raise SystemExit(2)
+
+    # An expired access token with a refresh token is still a working session:
+    # the next command refreshes it on its own.
+    if tokens.is_expired and not tokens.refresh_token:
+        if not quiet:
+            console.print(f"[yellow]Token expired.[/yellow] Logged in as: {tokens.email or 'unknown'}")
+            console.print("Run: tl auth login")
+        raise SystemExit(2)
+
+    if quiet:
+        return
+    if tokens.is_api_key:
+        console.print("[green]Authenticated[/green] via API key.")
+    else:
+        console.print(f"[green]Authenticated[/green] as: {tokens.email or 'unknown'}")