querit-cli 0.1.0__tar.gz

querit_cli-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: querit-cli
+Version: 0.1.0
+Summary: CLI tool for the Querit API — search from the command line.
+License-Expression: MIT
+Keywords: agents,ai,cli,querit,web-search
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: querit>=0.1.5
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'

querit_cli-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "querit-cli"
+version = "0.1.0"
+description = "CLI tool for the Querit API — search from the command line."
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["ai", "querit", "web-search", "cli", "agents"]
+
+dependencies = [
+    "querit>=0.1.5",
+    "click>=8.1.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+querit = "querit_cli.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.4.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["querit_cli"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP"]
+ignore = ["E501"]

querit_cli-0.1.0/querit_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Querit CLI — search the web from the command line."""
+
+__version__ = "0.1.0"

querit_cli-0.1.0/querit_cli/cli.py

@@ -0,0 +1,85 @@
+"""Main CLI entry point — wires all commands into the `querit` group."""
+
+from __future__ import annotations
+
+import click
+
+from querit_cli import __version__
+from querit_cli.commands.auth import auth_status, login, logout
+from querit_cli.commands.search import search
+
+
+@click.group(invoke_without_command=True)
+@click.option("--version", is_flag=True, default=False, help="Show version and exit.")
+@click.option("--status", "show_status", is_flag=True, default=False, help="Show version and auth status.")
+@click.option("--json", "json_output", is_flag=True, default=False, help="Output as JSON (for agents and scripts).")
+@click.pass_context
+def cli(ctx: click.Context, version: bool, show_status: bool, json_output: bool) -> None:
+    """Querit CLI — search the web from the command line.
+
+    Authenticate with: querit login --api-key YOUR_KEY
+    Or set the QUERIT_API_KEY environment variable.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["json_output"] = json_output
+
+    if version:
+        if json_output:
+            import json
+            click.echo(json.dumps({"version": __version__}))
+        else:
+            click.echo(f"querit-cli {__version__}")
+        ctx.exit(0)
+        return
+
+    if show_status:
+        _print_status(json_output)
+        ctx.exit(0)
+        return
+
+    if ctx.invoked_subcommand is None:
+        from querit_cli.repl import run_repl
+        run_repl()
+        ctx.exit(0)
+
+
+def _print_status(json_output: bool) -> None:
+    """Show version + auth status."""
+    import json as _json
+    import os
+
+    from querit_cli.config import get_api_key
+
+    key = get_api_key()
+    authenticated = key is not None
+
+    if json_output:
+        click.echo(_json.dumps({
+            "version": __version__,
+            "authenticated": authenticated,
+        }))
+    else:
+        from rich.console import Console
+        console = Console()
+        console.print(f"  [bold #00C2C2]querit[/bold #00C2C2] v{__version__}")
+        console.print()
+        if authenticated:
+            source = "QUERIT_API_KEY env var" if os.environ.get("QUERIT_API_KEY") else "~/.querit/config.json"
+            console.print(f"  [#9BC0AE]>[/#9BC0AE] Authenticated via {source}")
+        else:
+            console.print("  [#FAA2FB]>[/#FAA2FB] Not authenticated")
+            console.print("    Run: querit login --api-key YOUR_KEY")
+
+
+cli.add_command(login)
+cli.add_command(logout)
+cli.add_command(auth_status)
+cli.add_command(search)
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

querit_cli-0.1.0/querit_cli/client.py

@@ -0,0 +1,79 @@
+"""Querit API client — wraps the official querit Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from querit import QueritClient as _SDKClient
+from querit.models.request import SearchRequest, SearchFilters, SiteFilter, GeoFilter
+from querit.errors import QueritError
+
+from querit_cli.common import QueritAPIError
+
+
+class QueritClient:
+    """Thin wrapper around the official Querit Python SDK."""
+
+    def __init__(self, api_key: str, timeout: int = 30) -> None:
+        # SDK internally sets: Authorization: Bearer {api_key}
+        # so pass the raw key only — do NOT prepend "Bearer " here
+        self._sdk = _SDKClient(api_key=api_key, timeout=timeout)
+
+    def search(
+        self,
+        query: str,
+        *,
+        count: int | None = None,
+        sites_include: list[str] | None = None,
+        sites_exclude: list[str] | None = None,
+        time_range: str | None = None,
+        countries: list[str] | None = None,
+        languages: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Call the Querit search API via the official SDK."""
+        search_filters = None
+        if any([sites_include, sites_exclude, time_range, countries, languages]):
+            search_filters = SearchFilters(
+                sites=SiteFilter(
+                    include=sites_include or [],
+                    exclude=sites_exclude or [],
+                ) if (sites_include or sites_exclude) else None,
+                geo=GeoFilter(
+                    countries=countries,
+                ) if countries else None,
+                time_range=time_range,
+                languages=languages,
+            )
+
+        request = SearchRequest(
+            query=query,
+            **({} if count is None else {"count": count}),
+            **({"filters": search_filters} if search_filters else {}),
+        )
+
+        try:
+            response = self._sdk.search(request)
+        except QueritError as e:
+            raise QueritAPIError(str(e)) from e
+        except Exception as e:
+            raise QueritAPIError(f"Unexpected error: {e}") from e
+
+        # Normalise SDK response object → dict so output.py stays unchanged
+        results = [
+            {
+                "url":       getattr(item, "url", ""),
+                "title":     getattr(item, "title", ""),
+                "snippet":   getattr(item, "snippet", "") or getattr(item, "description", ""),
+                "site_name": getattr(item, "site_name", ""),
+                "page_age":  getattr(item, "page_age", ""),
+                "site_icon": getattr(item, "site_icon", ""),
+            }
+            for item in (response.results or [])
+        ]
+
+        return {
+            "took":          getattr(response, "took", ""),
+            "search_id":     getattr(response, "search_id", None),
+            "query_context": {"query": query},
+            "results":       {"result": results},
+        }

querit_cli-0.1.0/querit_cli/commands/auth.py

@@ -0,0 +1,54 @@
+"""querit login / logout / auth — credential management."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command()
+@click.option("--api-key", default=None, help="Your Querit API key.")
+def login(api_key: str | None) -> None:
+    """Save your Querit API key locally."""
+    from rich.console import Console
+    from querit_cli.config import save_api_key
+
+    console = Console(stderr=True)
+    if not api_key:
+        api_key = click.prompt("  Enter your Querit API key", hide_input=True)
+
+    save_api_key(api_key.strip())
+    console.print("  [#9BC0AE]>[/#9BC0AE] API key saved.")
+    console.print("  [dim]Stored in ~/.querit/config.json[/dim]")
+
+
+@click.command()
+def logout() -> None:
+    """Remove your saved Querit API key."""
+    from rich.console import Console
+    from querit_cli.config import clear_credentials
+
+    console = Console(stderr=True)
+    clear_credentials()
+    console.print("  [#9BC0AE]>[/#9BC0AE] Credentials cleared.")
+
+
+@click.command("auth")
+def auth_status() -> None:
+    """Show current authentication status."""
+    import os
+    from rich.console import Console
+    from querit_cli.config import get_api_key
+
+    console = Console(stderr=True)
+    key = get_api_key()
+
+    console.print()
+    if key:
+        masked = key[:8] + "..." if len(key) > 8 else key
+        source = "QUERIT_API_KEY env var" if os.environ.get("QUERIT_API_KEY") else "~/.querit/config.json"
+        console.print(f"  [#9BC0AE]>[/#9BC0AE] Authenticated via {source}")
+        console.print(f"  [dim]Key: {masked}[/dim]")
+    else:
+        console.print("  [#FAA2FB]>[/#FAA2FB] Not authenticated")
+        console.print("    Run: [#00C2C2]querit login --api-key YOUR_KEY[/#00C2C2]")
+    console.print()

querit_cli-0.1.0/querit_cli/commands/search.py

@@ -0,0 +1,86 @@
+"""querit search — web search via the Querit API."""
+
+from __future__ import annotations
+
+import click
+
+from querit_cli.common import handle_api_error
+
+
+@click.command()
+@click.argument("query", required=False)
+@click.option("--count", type=int, default=None,
+              help="Maximum number of results to return.")
+@click.option("--sites-include", multiple=True, metavar="SITE",
+              help="Only include results from this site (repeatable). E.g. --sites-include bbc.com")
+@click.option("--sites-exclude", multiple=True, metavar="SITE",
+              help="Exclude results from this site (repeatable). E.g. --sites-exclude reddit.com")
+@click.option("--time-range", default=None, metavar="RANGE",
+              help=(
+                  "Time range filter. Examples: "
+                  "d7 (past 7 days), w2 (past 2 weeks), m3 (past 3 months), "
+                  "y1 (past 1 year), 2024-01-01to2024-06-30 (date range)."
+              ))
+@click.option("--countries", multiple=True, metavar="CC",
+              help="Limit results to these countries (repeatable). E.g. --countries france --countries germany")
+@click.option("--languages", multiple=True, metavar="LANG",
+              help="Limit results to these languages (repeatable). E.g. --languages en --languages zh")
+@click.option("--output", "-o", "output_file", default=None,
+              help="Save full JSON response to this file.")
+@click.option("--json", "json_flag", is_flag=True, default=False,
+              help="Output as JSON (for scripts and agents).")
+@click.pass_context
+def search(
+    ctx: click.Context,
+    query: str | None,
+    count: int | None,
+    sites_include: tuple[str, ...],
+    sites_exclude: tuple[str, ...],
+    time_range: str | None,
+    countries: tuple[str, ...],
+    languages: tuple[str, ...],
+    output_file: str | None,
+    json_flag: bool,
+) -> None:
+    """Search the web using the Querit API.
+
+    QUERY is your search term.
+
+    Examples:
+
+      querit search "climate change"
+
+      querit search "python tutorial" --count 5
+
+      querit search "news" --time-range d7 --countries US
+
+      querit search "site news" --sites-include bbc.com --sites-include reuters.com
+    """
+    from querit_cli.config import get_client
+    from querit_cli.output import print_search_results
+    from querit_cli.theme import spinner
+
+    # Inherit --json from parent context (the global `querit --json` flag)
+    json_mode = json_flag or bool(ctx.obj and ctx.obj.get("json_output"))
+
+    if not query:
+        raise click.UsageError('QUERY is required. Example: querit search "your query"')
+
+    client = get_client()
+
+    try:
+        with spinner("Searching...", json_mode=json_mode):
+            response = client.search(
+                query,
+                count=count,
+                sites_include=list(sites_include) or None,
+                sites_exclude=list(sites_exclude) or None,
+                time_range=time_range,
+                countries=list(countries) or None,
+                languages=list(languages) or None,
+            )
+    except Exception as e:
+        handle_api_error(e, json_mode)
+        return
+
+    print_search_results(response, json_mode=json_mode, output_file=output_file)

querit_cli-0.1.0/querit_cli/common.py

@@ -0,0 +1,30 @@
+"""Shared utilities: custom exception, error handler."""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from querit_cli.theme import err_console
+
+
+class QueritAPIError(Exception):
+    """Structured error from the Querit API."""
+
+    def __init__(self, message: str, *, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+def handle_api_error(e: Exception, json_mode: bool) -> None:
+    """Print a formatted error message and exit."""
+    if json_mode:
+        click.echo(json.dumps({"error": str(e)}))
+        raise SystemExit(4)
+    if isinstance(e, QueritAPIError) and e.status == 429:
+        err_console.print(f"  [#FFC769]>[/#FFC769] Rate limit exceeded: {e}")
+        err_console.print("  [dim]Check your plan at[/dim] [#00C2C2 link=https://www.querit.ai]querit.ai[/#00C2C2 link=https://www.querit.ai]")
+        raise SystemExit(3)
+    err_console.print(f"  [#FAA2FB]> Error:[/#FAA2FB] {e}")
+    raise SystemExit(4)

querit_cli-0.1.0/querit_cli/config.py

@@ -0,0 +1,77 @@
+"""API key storage and retrieval for the Querit CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+CONFIG_DIR  = Path.home() / ".querit"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+# Override base URL via environment variable if needed
+BASE_URL = os.environ.get("QUERIT_BASE_URL", "https://api.querit.ai")
+
+
+def _read_config() -> dict:
+    if CONFIG_FILE.exists():
+        try:
+            return json.loads(CONFIG_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            return {}
+    return {}
+
+
+def _write_config(data: dict) -> None:
+    old_umask = os.umask(0o077)
+    try:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        CONFIG_DIR.chmod(0o700)
+        CONFIG_FILE.write_text(json.dumps(data, indent=2) + "\n")
+        CONFIG_FILE.chmod(0o600)
+    finally:
+        os.umask(old_umask)
+
+
+def save_api_key(api_key: str) -> None:
+    config = _read_config()
+    config["api_key"] = api_key
+    _write_config(config)
+
+
+def clear_credentials() -> None:
+    if CONFIG_FILE.exists():
+        CONFIG_FILE.unlink()
+
+
+def get_api_key() -> str | None:
+    """Resolve the API key with precedence: env var > config file."""
+    key = os.environ.get("QUERIT_API_KEY")
+    if key:
+        return key
+    return _read_config().get("api_key")
+
+
+def get_api_key_or_exit() -> str:
+    """Get the API key or print an error and exit."""
+    import sys
+
+    key = get_api_key()
+    if not key:
+        from rich.console import Console
+        console = Console(stderr=True)
+        console.print("  [#FAA2FB]> Error:[/#FAA2FB] No Querit API key found.")
+        console.print()
+        console.print("  Set your API key using one of:")
+        console.print("    [#00C2C2]querit login --api-key YOUR_KEY[/#00C2C2]")
+        console.print("    [dim]export QUERIT_API_KEY=YOUR_KEY[/dim]")
+        console.print()
+        console.print("  Get a key at [link=https://www.querit.ai]querit.ai[/link]")
+        sys.exit(3)
+    return key
+
+
+def get_client():
+    """Return an authenticated QueritClient."""
+    from querit_cli.client import QueritClient
+    return QueritClient(api_key=get_api_key_or_exit())

querit_cli-0.1.0/querit_cli/output.py

@@ -0,0 +1,94 @@
+"""Formatted output for Querit CLI search results."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.rule import Rule
+from rich.text import Text
+from rich.theme import Theme
+
+_theme = Theme({
+    "markdown.h1": "bold #00C2C2",
+    "markdown.h2": "bold #00C2C2",
+    "markdown.h3": "bold #00C2C2",
+})
+
+console     = Console(theme=_theme)
+err_console = Console(stderr=True)
+
+
+def emit(data: Any, *, json_mode: bool, output_file: str | None = None) -> None:
+    """Serialise data as JSON to stdout or a file."""
+    text = json.dumps(data, indent=2, ensure_ascii=False)
+    if output_file:
+        with open(output_file, "w", encoding="utf-8") as f:
+            f.write(text + "\n")
+    else:
+        click.echo(text)
+
+
+def print_search_results(
+    response: dict,
+    *,
+    json_mode: bool,
+    output_file: str | None = None,
+) -> None:
+    """Render Querit search results in human-readable or JSON format."""
+    if json_mode:
+        emit(response, json_mode=True, output_file=output_file)
+        return
+
+    results = response.get("results", {}).get("result", [])
+    took    = response.get("took", "")
+
+    if not results:
+        console.print()
+        console.print("  [dim]No results found.[/dim]")
+        console.print()
+        return
+
+    console.print()
+    for i, r in enumerate(results, 1):
+        title    = r.get("title") or r.get("url", "Untitled")
+        url      = r.get("url", "")
+        snippet  = r.get("snippet", "")
+        site     = r.get("site_name", "")
+        page_age = r.get("page_age", "")
+
+        # Title
+        title_text = Text()
+        title_text.append(f"  {i}. ", style="dim")
+        title_text.append(title, style="bold #00C2C2")
+        console.print(title_text)
+
+        # Meta: site name + age + url
+        meta = Text("     ")
+        if site:
+            meta.append(site, style="#9BC0AE")
+        if page_age:
+            meta.append(f"  {page_age}", style="dim")
+        if url:
+            meta.append(f"  {url}", style="dim underline")
+        console.print(meta)
+
+        # Snippet
+        if snippet:
+            short = snippet[:300] + ("…" if len(snippet) > 300 else "")
+            console.print(f"     [dim]{short}[/dim]")
+
+        console.print()
+
+    # Footer: result count + server response time
+    footer_parts = [f"{len(results)} results"]
+    if took:
+        footer_parts.append(took)
+    console.print(Rule(f"[dim]{' | '.join(footer_parts)}[/dim]", style="dim"))
+    console.print()
+
+    if output_file:
+        emit(response, json_mode=True, output_file=output_file)
+        err_console.print(f"  [dim]Saved to {output_file}[/dim]")

querit_cli-0.1.0/querit_cli/repl.py

@@ -0,0 +1,143 @@
+"""Interactive REPL — gives querit a clean, chat-like shell."""
+
+from __future__ import annotations
+
+import readline  # noqa: F401 — enables arrow-key history in input()
+import shlex
+
+import click
+from rich.console import Console
+from rich.rule import Rule
+from rich.text import Text
+
+from querit_cli import __version__
+from querit_cli.config import get_api_key
+from querit_cli.theme import LOGO
+
+err_console = Console(stderr=True)
+
+_REPL_COMMANDS = {"search", "login", "logout", "auth"}
+
+
+def _print_banner() -> None:
+    """Print the welcome banner inside the REPL."""
+    key = get_api_key()
+
+    err_console.print(LOGO)
+    err_console.print(f"  [dim]v{__version__}[/dim]")
+    err_console.print()
+
+    if key:
+        err_console.print("  [#9BC0AE]>[/#9BC0AE] Authenticated")
+    else:
+        err_console.print("  [#FAA2FB]>[/#FAA2FB] Not authenticated")
+        err_console.print("    Type [#00C2C2]login[/#00C2C2] to set your API key.")
+
+    err_console.print()
+
+    tips = Text()
+    tips.append("  Tips: ", style="bold")
+    tips.append("search ", style="#00C2C2")
+    tips.append('"query"', style="dim")
+    tips.append("  |  ", style="dim")
+    tips.append("search ", style="#00C2C2")
+    tips.append('"query" --count 5', style="dim")
+    tips.append("  |  ", style="dim")
+    tips.append("help", style="#00C2C2")
+    tips.append("  |  ", style="dim")
+    tips.append("exit", style="#00C2C2")
+    err_console.print(tips)
+    err_console.print()
+
+
+def _print_help() -> None:
+    """Print REPL help."""
+    err_console.print()
+    cmds = Text()
+    cmds.append("  Commands\n\n", style="bold")
+    cmds.append('    search "your query"', style="#00C2C2")
+    cmds.append("                     Web search\n")
+    cmds.append('    search "query" --count N', style="#00C2C2")
+    cmds.append("            Limit result count\n")
+    cmds.append('    search "query" --time-range d7', style="#00C2C2")
+    cmds.append("      Past 7 days\n")
+    cmds.append('    search "query" --sites-include bbc.com', style="#00C2C2")
+    cmds.append("  Site filter\n")
+    cmds.append('    search "query" --countries US --languages en', style="#00C2C2")
+    cmds.append("  Geo/lang filter\n")
+    cmds.append("    login", style="#00C2C2")
+    cmds.append("                              Authenticate\n")
+    cmds.append("    logout", style="#00C2C2")
+    cmds.append("                             Clear credentials\n")
+    cmds.append("    auth", style="#00C2C2")
+    cmds.append("                               Auth status\n")
+    cmds.append("    exit / quit / Ctrl+C", style="#00C2C2")
+    cmds.append("               Leave\n")
+    err_console.print(cmds)
+
+
+def _prompt() -> str:
+    """Print the separator + prompt and read a line of input."""
+    err_console.print(Rule(style="dim"))
+    try:
+        return input("\001\033[38;2;0;194;194m\002\u276f\001\033[0m\002  ")
+    except EOFError:
+        return "exit"
+
+
+def run_repl() -> None:
+    """Enter the interactive REPL loop."""
+    err_console.print()
+    _print_banner()
+
+    while True:
+        try:
+            line = _prompt()
+        except KeyboardInterrupt:
+            err_console.print()
+            err_console.print("  [dim]Farewell, hope to see you again![/dim]")
+            err_console.print()
+            break
+
+        line = line.strip()
+        if not line:
+            continue
+
+        if line in ("exit", "quit", "q"):
+            err_console.print()
+            err_console.print("  [dim]Farewell, hope to see you again![/dim]")
+            err_console.print()
+            break
+
+        if line in ("help", "?"):
+            _print_help()
+            continue
+
+        try:
+            args = shlex.split(line)
+        except ValueError as e:
+            err_console.print(f"  [#FAA2FB]Parse error:[/#FAA2FB] {e}")
+            continue
+
+        # Allow "querit search ..." as well as plain "search ..."
+        if args and args[0] == "querit":
+            args = args[1:]
+
+        if not args:
+            continue
+
+        from querit_cli.cli import cli
+        err_console.print()
+        try:
+            cli(args, standalone_mode=False)
+        except SystemExit:
+            pass
+        except KeyboardInterrupt:
+            err_console.print()
+            err_console.print("  [dim]Cancelled.[/dim]")
+        except click.exceptions.UsageError as e:
+            err_console.print(f"  [#FAA2FB]>[/#FAA2FB] {e.format_message()}")
+        except Exception as e:
+            err_console.print(f"  [#FAA2FB]> Error:[/#FAA2FB] {e}")
+
+        err_console.print()

querit_cli-0.1.0/querit_cli/theme.py

@@ -0,0 +1,43 @@
+"""Brand colours, Rich console instances, and the spinner helper."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Generator
+
+from rich.console import Console
+
+# Brand colours
+TEAL   = "#00C2C2"
+PINK   = "#FAA2FB"
+YELLOW = "#FFC769"
+BLUE   = "#5B8AF9"
+GREEN  = "#9BC0AE"
+
+BRAND   = TEAL
+ACCENT  = BLUE
+SUCCESS = GREEN
+WARN    = YELLOW
+ERROR   = PINK
+
+console     = Console()
+err_console = Console(stderr=True)
+
+LOGO = """\
+[#00C2C2]   ___  _   _  ___  ____  _  _____ [/#00C2C2]
+[#5B8AF9]  / _ \\| | | |/ _ \\|  _ \\| ||_   _|[/#5B8AF9]
+[#9BC0AE] | | | | | | | | | | |_) | |  | |  [/#9BC0AE]
+[#FFC769] | |_| | |_| | |_| |  _ <| |__| |  [/#FFC769]
+[#FAA2FB]  \\__\\_\\\\___/ \\___/|_| \\_\\_____|_|  [/#FAA2FB]"""
+
+LOGO_COMPACT = "[#00C2C2 bold]querit[/#00C2C2 bold]"
+
+
+@contextmanager
+def spinner(message: str, *, json_mode: bool = False) -> Generator[None, None, None]:
+    """Show a live spinner on stderr; silent in JSON mode."""
+    if json_mode:
+        yield
+        return
+    with err_console.status(f"[{TEAL}]{message}[/{TEAL}]", spinner="dots"):
+        yield