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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pushmetrics-cli
-Version: 0.1.0
+Version: 0.1.1
 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.1.1}/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.1.1/pm/__init__.py

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

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.1.1}/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.1.1}/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.1.1}/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 (
@@ -56,6 +58,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 +75,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 +193,18 @@ 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")),
         )
         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,6 +221,11 @@ 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):")

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

@@ -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"]
 

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.1.1}/pm/commands/help.py

@@ -187,7 +187,7 @@ _GROUP_PAGES: Dict[str, Dict] = {
             "schema":  "Available measures/dimensions. <uid>.",
         },
         "body_fields": (
-            "  --measure NAME    repeatable, ≥1 required\n"
+            "  --measure NAME    repeatable, 1 or more required\n"
             "  --dimension NAME  repeatable\n"
             "  --time-range last_30d | 2026-01-01:2026-04-01\n"
             "  --limit N, --offset N, --no-cache\n"
@@ -460,7 +460,7 @@ _PLAIN_PAGES: Dict[str, str] = {
         "  pm login --token        paste the token at the hidden prompt\n"
         "  <secrets-cmd> | pm login --token   pipe it from a secrets manager\n"
         "  PM_API_TOKEN=...        use it without storing (CI, scripts)\n\n"
-        "Tokens are created in the web app under Access Tokens."
+        "Tokens are created in the web app under Settings > CLI & API."
     ),
     "logout": (
         "pm logout — Forget the stored token or session for the profile.\n\n"

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.1.1}/pm/config.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 import hashlib
 import os
 import sys
+import tempfile
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, Optional
@@ -109,6 +110,51 @@ def _ensure_dir() -> None:
     CONFIG_DIR.mkdir(parents=True, exist_ok=True)
 
 
+def _atomic_write_text(path: Path, text: str) -> None:
+    """Write ``text`` to ``path`` atomically.
+
+    A direct ``path.write_text`` truncates the file first, so an interrupted
+    write (crash, Ctrl-C, full disk) or two concurrent ``pm config set`` runs
+    leaves a torn config.toml that the next command cannot parse. Instead
+    write a temp file in the same directory, flush+fsync it, then
+    ``os.replace`` it over the target -- an atomic rename on the same
+    filesystem -- so a reader sees either the old file or the whole new one,
+    never a half-written one. The existing file's mode is preserved (the
+    fresh temp file is created 0600 by mkstemp regardless, so a brand-new
+    config.toml is 0600).
+
+    If ``path`` is a symlink (dotfiles setups often link ~/.pm/config.toml
+    into a tracked dir), ``os.replace`` would otherwise swap the link itself
+    for a regular file. Resolve to the link target first and write there, so
+    the link is kept and its destination filesystem is the one the temp file
+    lands on.
+    """
+    target = path.resolve()
+    directory = target.parent
+    mode: Optional[int] = None
+    try:
+        mode = os.stat(target).st_mode & 0o777
+    except FileNotFoundError:
+        mode = None
+
+    fd, tmp_name = tempfile.mkstemp(dir=directory, prefix=".config.", suffix=".toml.tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(text)
+            f.flush()
+            os.fsync(f.fileno())
+        if mode is not None:
+            os.chmod(tmp_name, mode)
+        os.replace(tmp_name, target)
+    except BaseException:
+        # Leave the existing config.toml untouched and clean up the temp file.
+        try:
+            os.unlink(tmp_name)
+        except FileNotFoundError:
+            pass
+        raise
+
+
 def _serialize_toml(data: Dict[str, Dict[str, Any]]) -> str:
     """Tiny TOML writer for our flat profile schema. Avoids pulling in tomli_w."""
     lines = []
@@ -132,12 +178,26 @@ def load_all() -> Dict[str, Dict[str, Any]]:
     if not CONFIG_FILE.exists():
         return {}
     with CONFIG_FILE.open("rb") as f:
-        return tomllib.load(f)
+        raw = f.read()
+    try:
+        return tomllib.loads(raw.decode("utf-8"))
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        # A partially-written or corrupted config.toml must not take down
+        # every `pm` command with a raw traceback. load_all() runs at the
+        # start of almost all commands (get_profile -> load_all), so name the
+        # file and the one-line recovery (built-in profiles still work) in a
+        # clean error instead. save_all writes atomically, so an unparsable
+        # file now only comes from an external edit or a pre-fix torn write.
+        raise click.ClickException(
+            f"Config file {CONFIG_FILE} is not valid TOML ({exc}). "
+            f"Fix or remove it (e.g. `rm {CONFIG_FILE}`) and re-run; "
+            f"built-in profiles work without it."
+        ) from exc
 
 
 def save_all(data: Dict[str, Dict[str, Any]]) -> None:
     _ensure_dir()
-    CONFIG_FILE.write_text(_serialize_toml(data), encoding="utf-8")
+    _atomic_write_text(CONFIG_FILE, _serialize_toml(data))
 
 
 def get_profile(name: str) -> Profile:

{pushmetrics_cli-0.1.0 → pushmetrics_cli-0.1.1}/pm/errors.py

@@ -148,6 +148,11 @@ def _hint_for_status(status: int, group: str | None) -> str | None:
             f"Nothing with that id is visible in the active workspace. "
             f"{listing} shows what exists."
         )
+    if status == 402:
+        return (
+            "pm needs an active PushMetrics subscription for this workspace's "
+            "organization. Start a trial or upgrade in the web app."
+        )
     if status == 429:
         return "Too many requests. Wait a minute and retry."
     if status >= 500:
@@ -166,6 +171,9 @@ _BARE_STATUS_MESSAGES = frozenset({
     # The one textual 403 reachable from pm (non-member workspace switch):
     # a fact with no next action, so the hint follows it.
     "you don't belong to this workspace",
+    # The legacy 402 from subscription-gated endpoints (kept server-side for
+    # old clients): states the fact, names no action.
+    "no subscription found for this organization",
 })
 
 
@@ -224,5 +232,6 @@ def describe_api_error(exc: Exception, *, group: str | None = None) -> str:
     else:
         first_line = str(exc)
     explained = bool(message) and not _is_bare_status_message(message)
-    hint = None if (explained and status == 403) else _hint_for_status(status, group)
+    # A 402/403 whose server sentence explains itself needs no generic hint.
+    hint = None if (explained and status in (402, 403)) else _hint_for_status(status, group)
     return f"{first_line}\nHint: {hint}" if hint else first_line

pushmetrics_cli-0.1.1/pm/user_agent.py

@@ -0,0 +1,67 @@
+"""The ``User-Agent`` the pm CLI sends on every request.
+
+Why this exists: the server records the HTTP User-Agent on each
+``pat_exchanged`` audit row (``security_event.user_agent``), and the ops
+Access Tokens page shows it. A bare ``requests.Session`` sends
+``python-requests/<ver>``, which cannot tell the pm CLI apart from any
+other Python client, nor say WHICH tool is driving pm — Claude Code,
+Copilot, Cursor, CI, or a human at a shell.
+
+pm is driven *by* an AI coding agent as shell commands; the agent is
+upstream of the process and leaves no wire signal of its own. So the only
+way the server can learn the calling tool is for pm to declare it. The
+tool sets ``PM_CLIENT`` (e.g. ``claude-code``, ``copilot``, ``cursor``,
+``ci``); unset means a plain CLI invocation.
+
+Shape (stable, parseable, no PII):
+
+    pm/0.1.0 (client=claude-code; py/3.11.6)
+
+``client`` is sanitised to ``[a-z0-9._-]`` and capped, so a hostile or
+accidental value can neither inject into the header nor blow the server's
+512-char column. The value carries no secret — it is a tool name only.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import re
+
+from pm import __version__
+
+CLIENT_ENV_VAR = "PM_CLIENT"
+
+# Header-safe, low-cardinality, no PII. Anything else is dropped to "cli".
+_CLIENT_RE = re.compile(r"[^a-z0-9._-]+")
+_MAX_CLIENT_LEN = 40
+_DEFAULT_CLIENT = "cli"
+
+
+def client_name() -> str:
+    """The calling tool, from ``PM_CLIENT``, normalised. ``"cli"`` when unset.
+
+    Lowercased, non-``[a-z0-9._-]`` runs collapsed to ``-``, trimmed and
+    capped. An empty or all-invalid value falls back to ``"cli"`` rather
+    than emitting a blank ``client=``.
+    """
+    raw = (os.environ.get(CLIENT_ENV_VAR) or "").strip().lower()
+    if not raw:
+        return _DEFAULT_CLIENT
+    cleaned = _CLIENT_RE.sub("-", raw).strip("-")[:_MAX_CLIENT_LEN]
+    return cleaned or _DEFAULT_CLIENT
+
+
+def _python_version() -> str:
+    try:
+        return platform.python_version()
+    except Exception:  # noqa: BLE001 - never let UA construction fail a request
+        return "unknown"
+
+
+def user_agent() -> str:
+    """The full ``User-Agent`` value for this process.
+
+    e.g. ``pm/0.1.0 (client=claude-code; py/3.11.6)``. Pure function of the
+    version and ``PM_CLIENT``; safe to call per request.
+    """
+    return f"pm/{__version__} (client={client_name()}; py/{_python_version()})"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pushmetrics-cli
-Version: 0.1.0
+Version: 0.1.1
 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.1.1}/pushmetrics_cli.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ pm/errors.py
 pm/log.py
 pm/output.py
 pm/types.py
+pm/user_agent.py
 pm/validators.py
 pm/auth/__init__.py
 pm/auth/device_flow.py
@@ -107,14 +108,17 @@ tests/test_client_saved_blocks.py
 tests/test_client_tableau.py
 tests/test_client_users.py
 tests/test_client_webhooks.py
+tests/test_config_atomic.py
 tests/test_credential_safety.py
 tests/test_device_flow.py
 tests/test_did_you_mean.py
 tests/test_domain_groups.py
+tests/test_e2_no_domain.py
 tests/test_errors.py
 tests/test_first_run.py
 tests/test_hardening.py
 tests/test_help_command.py
+tests/test_help_encoding.py
 tests/test_integration_commands.py
 tests/test_jwt_cache.py
 tests/test_keyring_namespace.py
@@ -135,4 +139,5 @@ tests/test_tableau_commands.py
 tests/test_token_auth.py
 tests/test_token_commands.py
 tests/test_types.py
+tests/test_user_agent.py
 tests/test_validators.py