pushmetrics-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{pushmetrics_cli-0.1.0/pushmetrics_cli.egg-info → pushmetrics_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pushmetrics-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Command-line interface for PushMetrics
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -28,18 +28,20 @@ The complete user guide is on the website: [PushMetrics CLI](https://pushmetrics
 
 ## Install
 
-> **PLACEHOLDER (D1).** The install command depends on the distribution channel and is filled in at release time.
+`pm` is published on PyPI as `pushmetrics-cli`. Install it with [pipx](https://pipx.pypa.io/):
 
 ```bash
-# PLACEHOLDER (D1): install command goes here
+pipx install pushmetrics-cli
 pm --version
 ```
 
-Requires Python 3.9 or newer. Runs on macOS, Linux and Windows.
+or with `uv tool install pushmetrics-cli` or `pip install --user pushmetrics-cli`. Requires Python 3.9 or newer and runs on macOS, Linux and Windows. Python from Homebrew and some Linux distributions refuses `pip install --user`; use pipx or uv there.
+
+`pm` needs an active PushMetrics subscription for your workspace's organization. Without one, PushMetrics refuses your personal access token: `pm` cannot log in, its commands stop working when the current session expires or sooner (within an hour at most), and no new tokens can be created.
 
 ## Quick start
 
-1. In the PushMetrics app, open **Settings → Access Tokens** (`/a/tokens`), click **New token**, and copy the `pmpat_...` value. It is shown once, and it is bound to the workspace that was active when you created it.
+1. In the PushMetrics app, open **Settings → CLI & API** (`/a/tokens`), click **New token**, and copy the `pmpat_...` value. It is shown once, and it is bound to the workspace that was active when you created it.
 2. Log in with the token. `pm` reads it from a hidden prompt, or from stdin when piped, and stores it in your OS credential store:
 
    ```bash
@@ -60,7 +62,7 @@ Requires Python 3.9 or newer. Runs on macOS, Linux and Windows.
 
 In CI, skip `pm login` and set `PM_API_TOKEN` instead.
 
-> **PLACEHOLDER (D2).** Browser login (`pm login` without `--token`, Auth0 device flow) is documented here only if it ships in the first release.
+`pm` logs in with personal access tokens only; `pm login` without `--token` tells you where to create one.
 
 ## Commands
 
@@ -158,7 +160,9 @@ pm --profile acme report list
 
 `pm` also caches the short-lived access token it exchanges from your personal access token, under the service name `pushmetrics-cli-jwt` or in `~/.pm/jwt_cache.json` with mode `0600`.
 
-`pm logout` removes both for the active profile. It does not revoke the token on the server; use `pm token revoke` or the Access Tokens page for that.
+`pm logout` removes both for the active profile. It does not revoke the token on the server; use `pm token revoke` or the CLI & API page for that.
+
+Profiles (api_url, auth0 settings) live in `$PM_CONFIG_HOME/config.toml` (default `~/.pm/config.toml`). `pm config set` writes it atomically (a temp file in the same directory is renamed into place), so an interrupted write never leaves a torn file. A config.toml created fresh by `pm` is mode `0600`; an existing file's mode is preserved. A symlinked config.toml keeps its link (the link target is updated).
 
 `pm` never takes a token on the command line and never prints one, in `-v` output or in errors. It only sends tokens over `https://`, except to `localhost`.
 
@@ -172,7 +176,7 @@ pm --profile acme report list
 
 **`Could not reach https://... (ConnectionError)…`** Network, or the wrong address: `pm config list` shows it.
 
-**`Unknown profile: 'acme'…`** or **`Profile 'acme' has no api_url…`** Each message ends with the `pm config set` command that fixes it; see also [Several workspaces](#several-workspaces).
+**`Unknown profile: 'acme'…`** or **`Profile 'acme' has no api_url…`** Each message names the `pm config set` command that fixes it; see also [Several workspaces](#several-workspaces).
 
 **`API ... failed: 403` / `404` with a `Hint:` line.** The hint names the next step: permissions in the token's workspace, or an id that is not visible there.
 

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.2.0}/README.md

@@ -8,18 +8,20 @@ The complete user guide is on the website: [PushMetrics CLI](https://pushmetrics
 
 ## Install
 
-> **PLACEHOLDER (D1).** The install command depends on the distribution channel and is filled in at release time.
+`pm` is published on PyPI as `pushmetrics-cli`. Install it with [pipx](https://pipx.pypa.io/):
 
 ```bash
-# PLACEHOLDER (D1): install command goes here
+pipx install pushmetrics-cli
 pm --version
 ```
 
-Requires Python 3.9 or newer. Runs on macOS, Linux and Windows.
+or with `uv tool install pushmetrics-cli` or `pip install --user pushmetrics-cli`. Requires Python 3.9 or newer and runs on macOS, Linux and Windows. Python from Homebrew and some Linux distributions refuses `pip install --user`; use pipx or uv there.
+
+`pm` needs an active PushMetrics subscription for your workspace's organization. Without one, PushMetrics refuses your personal access token: `pm` cannot log in, its commands stop working when the current session expires or sooner (within an hour at most), and no new tokens can be created.
 
 ## Quick start
 
-1. In the PushMetrics app, open **Settings → Access Tokens** (`/a/tokens`), click **New token**, and copy the `pmpat_...` value. It is shown once, and it is bound to the workspace that was active when you created it.
+1. In the PushMetrics app, open **Settings → CLI & API** (`/a/tokens`), click **New token**, and copy the `pmpat_...` value. It is shown once, and it is bound to the workspace that was active when you created it.
 2. Log in with the token. `pm` reads it from a hidden prompt, or from stdin when piped, and stores it in your OS credential store:
 
    ```bash
@@ -40,7 +42,7 @@ Requires Python 3.9 or newer. Runs on macOS, Linux and Windows.
 
 In CI, skip `pm login` and set `PM_API_TOKEN` instead.
 
-> **PLACEHOLDER (D2).** Browser login (`pm login` without `--token`, Auth0 device flow) is documented here only if it ships in the first release.
+`pm` logs in with personal access tokens only; `pm login` without `--token` tells you where to create one.
 
 ## Commands
 
@@ -138,7 +140,9 @@ pm --profile acme report list
 
 `pm` also caches the short-lived access token it exchanges from your personal access token, under the service name `pushmetrics-cli-jwt` or in `~/.pm/jwt_cache.json` with mode `0600`.
 
-`pm logout` removes both for the active profile. It does not revoke the token on the server; use `pm token revoke` or the Access Tokens page for that.
+`pm logout` removes both for the active profile. It does not revoke the token on the server; use `pm token revoke` or the CLI & API page for that.
+
+Profiles (api_url, auth0 settings) live in `$PM_CONFIG_HOME/config.toml` (default `~/.pm/config.toml`). `pm config set` writes it atomically (a temp file in the same directory is renamed into place), so an interrupted write never leaves a torn file. A config.toml created fresh by `pm` is mode `0600`; an existing file's mode is preserved. A symlinked config.toml keeps its link (the link target is updated).
 
 `pm` never takes a token on the command line and never prints one, in `-v` output or in errors. It only sends tokens over `https://`, except to `localhost`.
 
@@ -152,7 +156,7 @@ pm --profile acme report list
 
 **`Could not reach https://... (ConnectionError)…`** Network, or the wrong address: `pm config list` shows it.
 
-**`Unknown profile: 'acme'…`** or **`Profile 'acme' has no api_url…`** Each message ends with the `pm config set` command that fixes it; see also [Several workspaces](#several-workspaces).
+**`Unknown profile: 'acme'…`** or **`Profile 'acme' has no api_url…`** Each message names the `pm config set` command that fixes it; see also [Several workspaces](#several-workspaces).
 
 **`API ... failed: 403` / `404` with a `Hint:` line.** The hint names the next step: permissions in the token's workspace, or an id that is not visible there.
 

pushmetrics_cli-0.2.0/pm/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.2.0}/pm/auth/session.py

@@ -16,6 +16,7 @@ from pm.auth import device_flow, exchange, jwt_cache, store
 from pm.auth import token as token_auth
 from pm.config import Profile
 from pm.log import log_request, log_response
+from pm.user_agent import user_agent
 
 logger = logging.getLogger(__name__)
 
@@ -231,6 +232,11 @@ class PMSession:
         url = f"{self.profile.api_url}{path}"
         kwargs.setdefault("timeout", 60)
         headers = dict(kwargs.get("headers") or {})
+        # Declare the calling tool (PM_CLIENT) on every request, so the
+        # server can attribute usage to Claude Code / Copilot / raw CLI
+        # instead of a bare python-requests UA. setdefault: an explicit
+        # per-call User-Agent still wins.
+        headers.setdefault("User-Agent", user_agent())
         # Forward agent identity to the API for backend scope filters.
         if self._agent_uid:
             headers.setdefault(_AGENT_UID_HEADER, self._agent_uid)

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.2.0}/pm/auth/token.py

@@ -31,6 +31,7 @@ from pm.auth import jwt_cache
 from pm.auth.secret_files import read_private_json, write_private_json
 from pm.config import CONFIG_DIR, keyring_account
 from pm.log import log_request, log_response, redact_secrets, timed
+from pm.user_agent import user_agent
 
 try:
     import keyring
@@ -144,7 +145,12 @@ def exchange_pat_for_jwt(
     try:
         resp = session.post(
             url,
-            headers={"Authorization": f"Bearer {raw_token}"},
+            headers={
+                "Authorization": f"Bearer {raw_token}",
+                # Declares the calling tool (PM_CLIENT) so the server's
+                # pat_exchanged audit row names it; see pm.user_agent.
+                "User-Agent": user_agent(),
+            },
             timeout=30,
             # Never follow a redirect: ``requests`` would re-attach the
             # Authorization header (and thus the raw PAT) on a same-host 302.

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.2.0}/pm/cli.py

@@ -11,6 +11,8 @@ import click
 
 from pm._alias import AliasedGroup
 from pm import __version__
+from pm import config as pm_config
+from pm.auth.session import NotAuthenticatedError
 from pm.client.base import PMApiError
 from pm.commands._helpers import info, json_option
 from pm.config import (
@@ -22,6 +24,7 @@ from pm.config import (
 )
 from pm.errors import describe_api_error
 from pm.output import emit
+from pm.user_agent import CLIENT_ENV_VAR, client_name
 
 _cli_logger = logging.getLogger("pm.cli")
 
@@ -56,6 +59,15 @@ class RootGroup(AliasedGroup):
     def invoke(self, ctx: click.Context):
         try:
             return super().invoke(ctx)
+        except NotAuthenticatedError as exc:
+            # A login made under another config home lives in another keyring
+            # slot (security S9); say which home this command used, so the
+            # mismatch is diagnosable. The default home needs no explanation.
+            if exc.message.startswith("Not logged in.") and not pm_config.is_default_config_home():
+                raise click.ClickException(
+                    f"{exc.message}\nConfig home: {pm_config.describe_config_home()}."
+                )
+            raise
         except PMApiError as exc:
             raise click.ClickException(
                 describe_api_error(exc, group=ctx.invoked_subcommand)
@@ -64,7 +76,7 @@ class RootGroup(AliasedGroup):
 
 _GETTING_STARTED = """\b
 Get started with a personal access token:
-  1. Create a token in the PushMetrics web app under Access Tokens.
+  1. Create a token in the web app under Settings > CLI & API.
   2. pm login --token     paste the token at the prompt (stored securely)
   3. pm whoami            then: pm report list, pm run list, pm report run <uid>
 """
@@ -182,13 +194,21 @@ def config_list(ctx: click.Context) -> None:
             ("PM_API_URL", os.environ.get("PM_API_URL")),
             ("PM_AUTH0_DOMAIN", os.environ.get("PM_AUTH0_DOMAIN")),
             ("PM_AUTH0_CLIENT_ID", os.environ.get("PM_AUTH0_CLIENT_ID")),
+            ("PM_CONFIG_HOME", os.environ.get("PM_CONFIG_HOME")),
+            # Not a profile setting, but it changes what pm sends: the
+            # User-Agent's client= names the calling tool.
+            (CLIENT_ENV_VAR, os.environ.get(CLIENT_ENV_VAR)),
         )
         if value
     }
 
     if ctx.obj["json"]:
         emit(
-            {"profiles": rows, "env_overrides": env_overrides},
+            {
+                "profiles": rows,
+                "env_overrides": env_overrides,
+                "config_home": str(pm_config.CONFIG_DIR),
+            },
             json_output=True,
         )
         return
@@ -205,11 +225,20 @@ def config_list(ctx: click.Context) -> None:
         ],
     )
 
+    # Which config home is active decides which stored credentials (keyring
+    # slot) commands can see (security S9).
+    click.echo("")
+    click.echo(f"Config home: {pm_config.describe_config_home()}")
+
     if env_overrides:
         click.echo("")
         click.echo("Active env-var overrides (apply to all profiles):")
         for var, value in env_overrides.items():
-            click.echo(f"  {var}={value}")
+            line = f"  {var}={value}"
+            if var == CLIENT_ENV_VAR and client_name() != value:
+                # pm normalises the value; show what the server receives.
+                line += f" (sent as client={client_name()})"
+            click.echo(line)
 
 
 from pm.commands.auth import login, logout, whoami
@@ -225,6 +254,8 @@ from pm.commands.integrations import integrations as integrations_group
 from pm.commands.metrics_view import metrics_view as metrics_view_group
 from pm.commands.organizations import organizations as organizations_group
 from pm.commands.recipient import recipient as recipient_group
+from pm.commands.deliverability import deliverability as deliverability_group
+from pm.commands.schedule import schedule as schedule_group
 from pm.commands.reports import reports as reports_group
 from pm.commands.roles import roles as roles_group
 from pm.commands.runs import runs as runs_group
@@ -263,6 +294,8 @@ cli.add_command(webhooks_group, name="webhook")
 cli.add_command(favorites_group, name="favorite")
 cli.add_command(organizations_group, name="organization")
 cli.add_command(recipient_group)
+cli.add_command(deliverability_group)
+cli.add_command(schedule_group)
 cli.add_command(roles_group, name="role")
 cli.add_command(saved_blocks_group, name="saved-block")
 

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.2.0}/pm/client/__init__.py

@@ -14,6 +14,7 @@ from pm.auth.session import PMSession
 from pm.client.access_tokens import AccessTokensClient
 from pm.client.blocks import BlocksClient
 from pm.client.databases import DatabasesClient
+from pm.client.deliverability import DeliverabilityClient
 from pm.client.favorites import FavoritesClient
 from pm.client.folders import FoldersClient
 from pm.client.integrations import IntegrationsClient
@@ -23,6 +24,7 @@ from pm.client.reports import ReportsClient
 from pm.client.roles import RolesClient
 from pm.client.runs import RunsClient
 from pm.client.saved_blocks import SavedBlocksClient
+from pm.client.schedules import SchedulesClient
 from pm.client.tableau import TableauClient
 from pm.client.users import UsersClient
 from pm.client.webhooks import WebhooksClient
@@ -50,8 +52,10 @@ class PMClient:
         self.favorites = FavoritesClient(session)
         self.organizations = OrganizationsClient(session)
         self.recipients = RecipientsClient(session)
+        self.deliverability = DeliverabilityClient(session)
         self.roles = RolesClient(session)
         self.saved_blocks = SavedBlocksClient(session)
+        self.schedules = SchedulesClient(session)
         self.blocks = BlocksClient(session)
         self.tableau = TableauClient(session)
         self.access_tokens = AccessTokensClient(session)

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.2.0}/pm/client/blocks.py

@@ -56,6 +56,7 @@ SCRATCH_ROUTING_FIELD: Dict[str, str] = {
     "slack": "integration_id",
     "sftp": "integration_id",
     "tableau": "integration_id",
+    "power_bi": "integration_id",
     "webhook": "integration_id",
     "google_slides": "integration_id",
 }

pushmetrics_cli-0.2.0/pm/client/deliverability.py

@@ -0,0 +1,37 @@
+"""Email deliverability API client: wraps ``/api/v1/recipient/deliverability*``.
+
+Amazon SES keeps one suppression list per sending account; the server scopes
+it to this workspace by matching only the workspace's own recipients, users
+and email blocks (``superset/pushmetrics/views/recipient/api.py``). The client
+returns the response bodies as they are; the command layer renders them.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from pm.client.base import raise_for_status
+
+
+class DeliverabilityClient:
+    base_path = "/api/v1/recipient/deliverability"
+
+    def __init__(self, session):
+        self.session = session
+
+    def list(self) -> Dict[str, Any]:
+        """``{result: [blocked rows], count, enabled}``."""
+        resp = self.session.get(self.base_path)
+        raise_for_status(resp)
+        return resp.json() if resp.content else {}
+
+    def events(self, email: str) -> Dict[str, Any]:
+        """``{result: [events, newest first], state}`` for one address."""
+        resp = self.session.get(f"{self.base_path}/events", params={"email": email})
+        raise_for_status(resp)
+        return resp.json() if resp.content else {}
+
+    def unblock(self, email: str) -> Dict[str, Any]:
+        """``{result: state}``. Admin-only, enforced by the server."""
+        resp = self.session.post(f"{self.base_path}/unblock", json={"email": email})
+        raise_for_status(resp)
+        return resp.json() if resp.content else {}

pushmetrics_cli-0.2.0/pm/client/schedules.py

@@ -0,0 +1,49 @@
+"""Schedules API client: wraps ``/api/v1/workflow`` (a "workflow" in the API,
+a "schedule" everywhere a person reads it).
+
+``superset/pushmetrics/views/workflow/api.py``: list/get return the same
+record (``show_columns = list_columns``, report name and uid nested under
+``report``); POST takes ``report_id`` (the integer id, which the command layer
+resolves from a report uid); PUT takes ``rrule`` and ``active``; ``POST
+/<uid>/run`` dispatches the run as a background task and returns no run uid.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pm.client.base import _unwrap_result, raise_for_status
+
+
+class SchedulesClient:
+    base_path = "/api/v1/workflow"
+
+    def __init__(self, session):
+        self.session = session
+
+    def list(self, report_id: Optional[int] = None) -> List[Dict[str, Any]]:
+        params = {"q": "(page_size:-1)"}
+        if report_id is not None:
+            params["q"] = f"(filters:!((col:report_id,opr:eq,value:{int(report_id)})),page_size:-1)"
+        resp = self.session.get(f"{self.base_path}/", params=params)
+        raise_for_status(resp)
+        raw = _unwrap_result(resp.json(), default=[])
+        return raw if isinstance(raw, list) else [raw]
+
+    def get(self, uid: str) -> Dict[str, Any]:
+        resp = self.session.get(f"{self.base_path}/{uid}")
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default={}) or {}
+
+    def create(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """The add response carries only add_columns; callers re-read with get."""
+        resp = self.session.post(f"{self.base_path}/", json=data)
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default={}) or {}
+
+    def update(self, uid: str, data: Dict[str, Any]) -> None:
+        resp = self.session.put(f"{self.base_path}/{uid}", json=data)
+        raise_for_status(resp)
+
+    def run(self, uid: str) -> None:
+        resp = self.session.post(f"{self.base_path}/{uid}/run")
+        raise_for_status(resp)

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.2.0}/pm/commands/_helpers.py

@@ -2,14 +2,30 @@
 from __future__ import annotations
 
 import json
+import re
+import sys
 from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Union
 
 import click
 
 from pm.client.base import PMApiError
+from pm.output import _safe_text
 
 YES_HELP = "Skip the confirmation prompt. Required when stdin is not a terminal."
 
+_FRACTION = re.compile(r"\.\d+(?=([+-]\d{2}:?\d{2}|Z)?$)")
+
+
+def iso_seconds(value: Optional[str]) -> str:
+    """An ISO timestamp without microseconds; blank when empty."""
+    return _FRACTION.sub("", value) if value else ""
+
+
+def stdin_is_terminal() -> bool:
+    """Whether a person can answer a prompt. Commands that need --yes off a
+    terminal check this BEFORE prompting, so a piped "y" cannot pass."""
+    return sys.stdin.isatty()
+
 
 def json_option(f):
     """Per-command ``--json`` so both ``pm --json report list`` and
@@ -123,7 +139,7 @@ def peek_name(fetch: Callable[[], Any], *fields: str) -> Optional[str]:
 
 def confirm_delete(noun: str, uid: str, name: Optional[str] = None, *, note: str = "") -> None:
     """``Delete <noun> 'name' (uid)? [y/N]`` — abort on anything but yes."""
-    label = f"{name!r} ({uid})" if name else uid
+    label = f"{_safe_text(name)!r} ({uid})" if name else uid
     tail = f" {note}" if note else ""
     click.confirm(f"Delete {noun} {label}?{tail}", abort=True)
 

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.2.0}/pm/commands/auth.py

@@ -13,7 +13,7 @@ from pm.auth.session import PMSession
 from pm.client import PMClient
 from pm.client.base import PMApiError
 from pm.commands._helpers import info, json_option
-from pm.output import emit
+from pm.output import _safe_text, emit
 
 
 def _read_token(ctx: click.Context) -> str:
@@ -29,7 +29,7 @@ def _read_token(ctx: click.Context) -> str:
 
 def tokens_page_url(api_url: str) -> str:
     """The web app page where personal access tokens are created and revoked
-    (frontend route ``/a/tokens``, menu label "Access Tokens")."""
+    (frontend route ``/a/tokens``, menu label "CLI & API")."""
     return f"{api_url}/a/tokens"
 
 
@@ -41,9 +41,9 @@ def _token_login_failure(exc: token_auth.TokenExchangeError, api_url: str) -> st
             "Too many login attempts from this network address "
             "(10 per minute). Wait a minute and run `pm login --token` again."
         )
-    if exc.status is None:
-        # Raised before any HTTP (malformed token, unreachable host): the
-        # message already names the next action.
+    if exc.status is None or exc.status == 402:
+        # Raised before any HTTP (malformed token, unreachable host), or the
+        # subscription gate: the message already names the next action.
         return str(exc)
     return f"{exc}\nHint: tokens are created and revoked at {tokens_page_url(api_url)}"
 
@@ -91,8 +91,9 @@ def _login_with_token(ctx: click.Context, profile) -> None:
 def login(ctx: click.Context, no_browser: bool, use_token: bool) -> None:
     """Log in with a personal access token.
 
-    pm login --token stores the token for this profile. Without --token the
-    browser login is used, which needs an Auth0 client id on the profile.
+    Run pm login --token and paste the token when asked, or pipe it in from
+    your secrets manager. It is stored for this profile. Without --token,
+    pm login prints where to create a token.
     """
     profile = ctx.obj["profile"]
 
@@ -121,9 +122,9 @@ def login(ctx: click.Context, no_browser: bool, use_token: bool) -> None:
     info(ctx, "")
     info(
         ctx,
-        f"Open this URL on any device:    {device_payload.verification_uri_complete}",
+        _safe_text(f"Open this URL on any device:    {device_payload.verification_uri_complete}"),
     )
-    info(ctx, f"Verify it shows the user code:  {device_payload.user_code}")
+    info(ctx, _safe_text(f"Verify it shows the user code:  {device_payload.user_code}"))
     info(ctx, "Waiting for authorization...")
 
     try:

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.2.0}/pm/commands/db.py

@@ -8,7 +8,7 @@ import click
 from pm._alias import AliasedGroup
 from pm.client import PMClient
 from pm.commands._helpers import json_option, limit_option, name_filter_option, select_rows
-from pm.output import emit
+from pm.output import _safe_lines, _safe_text, emit
 
 
 @click.group(name="db", cls=AliasedGroup, aliases={"ls": "list"})
@@ -120,7 +120,7 @@ def describe(ctx: click.Context, db_ref: str, schema: str, table: str) -> None:
 
     click.echo(f"Table: {schema}.{table}")
     if meta.get("comment"):
-        click.echo(f"Comment: {meta['comment']}")
+        click.echo(_safe_lines(f"Comment: {meta['comment']}"))
 
     cols = meta.get("columns") or []
     if cols:
@@ -148,7 +148,7 @@ def describe(ctx: click.Context, db_ref: str, schema: str, table: str) -> None:
             ref_cols = ", ".join(fk.get("referred_columns") or [])
             ref_schema = fk.get("referred_schema") or ""
             ref_full = f"{ref_schema}.{ref_table}" if ref_schema else ref_table
-            click.echo(f"  ({src}) -> {ref_full}({ref_cols})")
+            click.echo(_safe_text(f"  ({src}) -> {ref_full}({ref_cols})"))
 
 
 @db.command(name="select-star")
@@ -178,7 +178,7 @@ def select_star(
     if json_output:
         emit({"sql": sql}, json_output=True)
         return
-    click.echo(sql)
+    click.echo(_safe_lines(sql))
 
 
 @db.command(name="exists")
@@ -209,7 +209,7 @@ def exists(ctx: click.Context, db_ref: str, schema: str, table: str) -> None:
         return
     kind = info.get("type") or "-"
     resolved = info.get("resolved_name") or "-"
-    click.echo(f"exists={info.get('exists')} type={kind} resolved={resolved}")
+    click.echo(_safe_text(f"exists={info.get('exists')} type={kind} resolved={resolved}"))
     if not info.get("exists"):
         ctx.exit(1)
 
@@ -246,11 +246,11 @@ def functions(ctx: click.Context, db_ref: str, filter_: str, limit: int) -> None
 
     note = result.get("note")
     if note:
-        click.echo(f"Note: {note}")
+        click.echo(_safe_lines(f"Note: {note}"))
         return
 
     for name in result.get("functions") or []:
-        click.echo(name)
+        click.echo(_safe_text(str(name)))
     total = result.get("total", 0)
     count = result.get("count", 0)
     if total and count < total: