bt-cli 0.4.56__tar.gz → 0.4.57__tar.gz

{bt_cli-0.4.56 → bt_cli-0.4.57}/CLAUDE.md

@@ -1,6 +1,6 @@
 # BT-CLI
 
-BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.56**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.57**
 
 ## Setup
 
@@ -45,7 +45,7 @@ Use these slash commands for detailed product guidance:
 | EPM Windows | `bt epmw` | `computers`, `groups`, `policies`, `requests`, `quick` |
 | EPM Linux | `bt epml` | `rbp` (cmdgrps/hostgrps/usergrps/tmdategrps/roles/policy/tests/tx), `settings`, `users`, `audit`, `siems`, `quick` |
 | Secrets API | `bt secrets` | `folders`, `static`, `dynamic` (incl. `generate`), `leases`, `integrations` |
-| Pathfinder | `bt pf` | `whoami`, `access`, `pats`, `mcp-tokens`, `machines` |
+| Pathfinder | `bt pf` | `whoami`, `access`, `pats`, `mcp-tokens`, `machines`, `users` (invite/grant/revoke/site membership) |
 
 ## Common Patterns
 
@@ -91,7 +91,7 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - **EPML role banner format**: `bt epml rbp roles create --banner-text "Title"` builds a `############`-framed message using `%rbprole%`/`%event%` server substitutions, mirroring the appliance's existing roles. See the worked role example in the EPM-L SKILL.md.
 - **Secrets dynamic path is `/dynamic`** (NOT `/dynamic-secrets` as the doc claims); version header is `2026-04-28` (NOT 2026-01-02; server also rejects every earlier dated header — bumps are mandatory, not optional); `dynamic/{name}/generate` returns 201; `/leases/revoke` is scope-gated and 403 is the expected lab response — `bt secrets leases revoke` exits 3 with a clean warning, not generic failure. Documented in `src/bt_cli/data/skills/secrets/SKILL.md`.
 - **Secrets `generate` mints real AWS STS credentials and is audited** — don't loop it in dev. Use `dynamic list`/`get` + `leases list` for browsing.
-- **PF URL mapping**: Nomine swagger paths `/api/auth/X` → gateway `https://api.beyondtrust.io/site/<site-id>/platform/auth/X`. **PATs are site-bound** (minted on the active portal site; other sites → `401 Access denied for this site`). Org-level endpoints (`auth/Users`, `auth/Auditing`, `auth/SAMLProviders`) are 403 for PAT principals; user onboarding & token create/revoke need cookie auth on app.beyondtrust.io. Details in `src/bt_cli/data/skills/pf/SKILL.md`.
+- **PF URL mapping**: Nomine swagger paths `/api/auth/X` → gateway `https://api.beyondtrust.io/site/<site-id>/platform/auth/X`. **PATs are site-bound** (minted on the active portal site; other sites → `401 Access denied for this site`). Org-level GETs (`auth/Users`, `auth/Auditing`, `auth/SAMLProviders`, `auth/*access/org`) are 403 for PAT principals; token create/revoke still needs cookie auth on app.beyondtrust.io. Onboarding/access writes (`UserInvitation*`, `Users/delete`, `productaccess`/`siteaccess` grant/revoke) are deployed on the PAT gateway (`bt pf users ...`) but PAT principals get the same org-level 403 on POST (live-verified 2026-06-11) — commands exit 3 with a cookie-auth hint until the gateway opens up. Details in `src/bt_cli/data/skills/pf/SKILL.md`.
 
 ## Functional vs Managed Accounts
 

{bt_cli-0.4.56 → bt_cli-0.4.57}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bt-cli
-Version: 0.4.56
+Version: 0.4.57
 Summary: BeyondTrust Platform CLI (unofficial) - Password Safe, Entitle, PRA, EPM
 Author-email: Dave Grendysz <dgrendysz@beyondtrust.com>
 License: MIT

{bt_cli-0.4.56 → bt_cli-0.4.57}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bt-cli"
-version = "0.4.56"
+version = "0.4.57"
 description = "BeyondTrust Platform CLI (unofficial) - Password Safe, Entitle, PRA, EPM"
 readme = "README.md"
 requires-python = ">=3.9"

{bt_cli-0.4.56 → bt_cli-0.4.57}/src/bt_cli/__init__.py

@@ -1,3 +1,3 @@
 """BeyondTrust Unified Admin CLI."""
 
-__version__ = "0.4.56"
+__version__ = "0.4.57"

{bt_cli-0.4.56 → bt_cli-0.4.57}/src/bt_cli/data/skills/pf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pf
-description: Pathfinder platform commands — whoami, site/product access, PAT/MCP token listing, machine registry. Use when working with the Pathfinder portal API (Nomine), platform PATs, site IDs, or registered machine identities.
+description: Pathfinder platform commands — whoami, site/product access, PAT/MCP token listing, machine registry, user invites and product/site access grants. Use when working with the Pathfinder portal API (Nomine), platform PATs, site IDs, user onboarding, or registered machine identities.
 ---
 
 # Pathfinder Platform (`bt pf`)
@@ -45,6 +45,37 @@ bt pf machines list        # registered machine IDs
 bt pf machines get <uuid>  # one machine's record (secret hash never shown)
 ```
 
+## User onboarding & access assignment (`bt pf users`)
+
+```bash
+# Invite a user to the org (sends a real email; confirms unless --yes).
+# Default site = BT_PF_SITE_ID; -p grants products on that site at invite time.
+bt pf users invite -e new.user@corp.com --first-name New --last-name User \
+    -p pra -p epml
+
+bt pf users cancel-invite new.user@corp.com   # cancel a pending invite
+
+# Per-user product access on a site (product slugs are lowercase:
+# epmwm, pra, psc, rs, entitle, epml, insights, secrets)
+bt pf users grant  -u <user-uuid> -p epml          # default site
+bt pf users revoke -u <user-uuid> -p epml -s <site-uuid>
+
+# Site membership (optionally granting products in the same call)
+bt pf users add-to-site      -u <user-uuid> -s <site-uuid> -p pra -p psc
+bt pf users remove-from-site -u <user-uuid> -s <site-uuid>
+
+bt pf users delete <user-uuid> [...]   # bulk delete (org admin; confirms)
+bt pf users list                       # org-level — 403 over PAT, exits 3 with hint
+```
+
+**Write-path caveat (verified 2026-06-11):** all of these routes are
+*deployed* on the PAT gateway (GET returns 405 = POST/DELETE exist), but PAT
+principals are **not authorized** — a live productaccess grant POST returned
+the same empty-body 403 as the org-level GETs. Every `bt pf users` write
+currently exits 3 with the cookie-auth hint. The commands are correct and
+will start working the moment the gateway grants PATs the org-level
+permission (or a cookie-auth mode lands).
+
 ## What works over PAT vs what doesn't (verified 2026-06-11)
 
 | Endpoint | PAT result |
@@ -52,7 +83,10 @@ bt pf machines get <uuid>  # one machine's record (secret hash never shown)
 | `auth/UserInfo`, `auth/User/Access`, `auth/User/Token`, `auth/User/McpToken` | 200 — any valid PAT |
 | `auth/Machine`, `auth/Machine/{id}` | 200 — only with a PAT from a product-bearing site (Administration-site PATs get 403) |
 | `auth/Users`, `auth/SAMLProviders`, `auth/Auditing` | 403 — org-level, blocked for PAT principals regardless of scopes seen so far |
-| `auth/UserInvitation` | 405 on GET (POST-only; reachable — onboarding over PAT untested) |
+| `auth/productaccess/org`, `auth/access/org`, `auth/siteaccess/org` | 403 — same org-level block |
+| `auth/productaccess` (collection GET) | 404 — not deployed on the gateway (also 404 on the app host) |
+| `auth/UserInvitation`, `auth/UserInvitation/Product`, `auth/UserInvitation/Cancel`, `auth/Users/delete` | 405 on GET — POST routes deployed, but PAT writes hit the org-level 403 (see below) |
+| `auth/productaccess/{p}/site/{s}/user/{u}`, `auth/siteaccess/{s}/user/{u}` | 405 on GET — routes deployed; live grant POST → empty-body 403 (org-level block applies to writes too) |
 
 PAT `access` scopes are the lowercase product IDs of the mint site (visible in
 `bt pf pats list`). The org-level 403s may require a scope no UI-minted PAT
@@ -70,7 +104,13 @@ but never activated.
 
 ## Not exposed via PAT (cookie-auth only, app.beyondtrust.io/api/auth/*)
 
-User onboarding (UserInvitation POST + Accept), PAT/MCP token creation and
-revocation, user listing, auditing, SAML providers. These need the `access`
-session cookie (browser JWT ~5min TTL, or the programmatic
-SignIn → /session/login flow — password-auth users only, not federated).
+Confirmed PAT-blocked (403): user listing, auditing, SAML providers, the
+org-default access-rule reads. Still cookie-only: PAT/MCP token creation and
+revocation, invitation Accept. These need the `access` session cookie
+(browser JWT ~5min TTL, or the programmatic SignIn → /session/login flow —
+password-auth users only, not federated).
+
+Invite body shape (spec `InviteOrganizationUserInput`): `{email, firstName,
+lastName, siteMetaData: [{siteId, name, residency}], productMetaData:
+[{name, siteId, siteName}]}` — `bt pf users invite` builds this, defaulting
+the site to `BT_PF_SITE_ID` and omitting name/residency unless given.

bt_cli-0.4.57/src/bt_cli/pf/client/base.py

@@ -0,0 +1,225 @@
+"""Pathfinder platform API client (PAT bearer auth, /site/<id>/platform/auth/... URLs)."""
+
+import logging
+from typing import Any, Dict, Optional
+from urllib.parse import quote as _urlquote
+
+import httpx
+
+from bt_cli.core.client import _warn_ssl_disabled
+from bt_cli.core.config import PFConfig, load_pf_config
+from bt_cli.core.rest_debug import get_event_hooks
+
+logger = logging.getLogger(__name__)
+
+
+class PFClient:
+    """Client for the Pathfinder platform API (internal name: Nomine).
+
+    URL composition:
+
+        {api_url}/site/{site_id}/platform/auth/<path>
+
+    The Nomine swagger writes paths as `/api/auth/X`; on the gateway the
+    product segment is `platform` and the path keeps the `auth/` prefix —
+    so spec `/api/auth/UserInfo` is gateway `/site/<id>/platform/auth/UserInfo`.
+
+    Auth: `Authorization: Bearer <PAT>`. PATs are site-bound — minted while
+    a site is active in the portal, valid only for that site's paths
+    (`401 Access denied for this site` elsewhere). A just-minted PAT can
+    take ~1s to propagate to the edge validator (transient
+    `401 Personal access token not found`).
+
+    Gateway-blocked for PAT principals (verified 2026-06-11): the entire
+    org-admin surface — reads (`auth/Users`, `auth/SAMLProviders`,
+    `auth/Auditing`, `auth/*access/org`) AND writes (`auth/UserInvitation*`,
+    `auth/Users/delete`, the productaccess/siteaccess grant/revoke routes).
+    The block's signature is an empty-body 403; the routes themselves are
+    deployed (GET returns 405). `auth/Machine` works only with a PAT for a
+    product-bearing site (not the Administration site).
+    """
+
+    def __init__(self, config: PFConfig):
+        self.config = config
+        self.base_url = config.api_url.rstrip("/")
+        self.site_id = config.site_id
+        self._base = f"{self.base_url}/site/{self.site_id}/platform"
+
+        if not config.verify_ssl:
+            _warn_ssl_disabled()
+
+        self._client = httpx.Client(
+            verify=config.verify_ssl,
+            timeout=config.timeout,
+            event_hooks=get_event_hooks(),
+        )
+
+    # ---- lifecycle ------------------------------------------------------
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "PFClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ---- low-level ------------------------------------------------------
+
+    @staticmethod
+    def _q(value: Any) -> str:
+        """URL-quote a path segment to prevent traversal / query injection."""
+        return _urlquote(str(value), safe="")
+
+    def _url(self, path: str) -> str:
+        if not path.startswith("/"):
+            path = "/" + path
+        return f"{self._base}{path}"
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.config.pat}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        """GET a platform path. Returns parsed JSON (None for empty bodies)."""
+        response = self._client.get(self._url(path), headers=self._headers(), params=params)
+        response.raise_for_status()
+        return self._parse(response)
+
+    def post(self, path: str, json: Any = None) -> Any:
+        """POST a platform path. Returns parsed JSON (None for empty bodies)."""
+        response = self._client.post(self._url(path), headers=self._headers(), json=json)
+        response.raise_for_status()
+        return self._parse(response)
+
+    def delete(self, path: str) -> Any:
+        """DELETE a platform path. Returns parsed JSON (None for empty bodies)."""
+        response = self._client.delete(self._url(path), headers=self._headers())
+        response.raise_for_status()
+        return self._parse(response)
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> Any:
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+
+    # ---- verified endpoints ----------------------------------------------
+
+    def get_user_info(self) -> Dict[str, Any]:
+        """GET /auth/UserInfo — the PAT owner's profile.
+
+        Returns `{sub, given_name, family_name, email, role, groups,
+        isFederated, mfaEnabled}`.
+        """
+        return self.get("/auth/UserInfo")
+
+    def get_user_access(self) -> Dict[str, Any]:
+        """GET /auth/User/Access — `{siteAccessRules: [...], productAccessRules: [...]}`."""
+        return self.get("/auth/User/Access")
+
+    def list_pats(self) -> Dict[str, Any]:
+        """GET /auth/User/Token — `{personalAccessTokens: [...], success, ...}`."""
+        return self.get("/auth/User/Token")
+
+    def list_mcp_tokens(self) -> Dict[str, Any]:
+        """GET /auth/User/McpToken — `{mcpTokens: [...], success, ...}`."""
+        return self.get("/auth/User/McpToken")
+
+    def list_machines(self) -> Dict[str, Any]:
+        """GET /auth/Machine — `{machines: [uuid, ...], success, ...}`.
+
+        Only reachable with a PAT minted on a product-bearing site; an
+        Administration-site PAT gets 403.
+        """
+        return self.get("/auth/Machine")
+
+    def get_machine(self, machine_id: str) -> Dict[str, Any]:
+        """GET /auth/Machine/{id} — details for one registered machine."""
+        return self.get(f"/auth/Machine/{self._q(machine_id)}")
+
+    # ---- users & onboarding ----------------------------------------------
+    #
+    # Route status over PAT (probed 2026-06-11): the invitation POSTs,
+    # Users/delete POST, and the productaccess/siteaccess grant/revoke
+    # routes all exist (GET returns 405), but PAT principals are NOT
+    # authorized — a live productaccess grant POST returned the same
+    # empty-body 403 as the org-level GETs (`auth/Users`,
+    # `auth/productaccess/org`, `auth/access/org`, `auth/siteaccess/org`).
+    # The bare `auth/productaccess` collection GET is 404 (not deployed).
+    # These methods stay wired for cookie-auth support or a future gateway
+    # policy change; commands surface the 403 as exit 3 with a hint.
+
+    def list_users(self, params: Optional[Dict[str, Any]] = None) -> Any:
+        """GET /auth/Users — org user list (plain array).
+
+        Filters: email, firstName, lastName, active, siteId, userId,
+        mfaEnabled, page (1-based), pageSize. 403 for PAT principals as of
+        2026-06-11 — works over cookie auth on app.beyondtrust.io.
+        """
+        return self.get("/auth/Users", params=params)
+
+    def invite_user(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """POST /auth/UserInvitation — invite a user to the organization.
+
+        Payload: `{email, firstName, lastName, siteMetaData: [{siteId,
+        name, residency}], productMetaData: [{name, siteId, siteName}]}`.
+        Sends a real invitation email.
+        """
+        return self.post("/auth/UserInvitation", json=payload)
+
+    def cancel_invitation(self, email: str) -> Dict[str, Any]:
+        """POST /auth/UserInvitation/Cancel — cancel a pending invite."""
+        return self.post("/auth/UserInvitation/Cancel", json={"email": email})
+
+    def delete_users(self, user_ids: list) -> Dict[str, Any]:
+        """POST /auth/Users/delete — bulk-delete platform users (org admin)."""
+        return self.post("/auth/Users/delete", json={"userIds": list(user_ids)})
+
+    def grant_product_access(self, product_id: str, site_id: str, user_id: str) -> Dict[str, Any]:
+        """POST /auth/productaccess/{productId}/site/{siteId}/user/{userId}.
+
+        Product IDs are lowercase slugs (epmwm, pra, psc, rs, entitle,
+        epml, insights, secrets); normalized here so the contract holds
+        for every caller.
+        """
+        return self.post(
+            f"/auth/productaccess/{self._q(str(product_id).lower())}/site/{self._q(site_id)}"
+            f"/user/{self._q(user_id)}"
+        )
+
+    def revoke_product_access(self, product_id: str, site_id: str, user_id: str) -> Dict[str, Any]:
+        """DELETE /auth/productaccess/{productId}/site/{siteId}/user/{userId}."""
+        return self.delete(
+            f"/auth/productaccess/{self._q(str(product_id).lower())}/site/{self._q(site_id)}"
+            f"/user/{self._q(user_id)}"
+        )
+
+    def grant_site_access(self, site_id: str, user_id: str,
+                          product_ids: Optional[list] = None) -> Dict[str, Any]:
+        """POST /auth/siteaccess/{siteId}/user/{userId} — add a user to a site.
+
+        Optional body: array of lowercase product slugs to grant on that
+        site too (the spec marks the body itself optional).
+        """
+        return self.post(
+            f"/auth/siteaccess/{self._q(site_id)}/user/{self._q(user_id)}",
+            json=[str(p).lower() for p in product_ids] if product_ids else None,
+        )
+
+    def revoke_site_access(self, site_id: str, user_id: str) -> Dict[str, Any]:
+        """DELETE /auth/siteaccess/{siteId}/user/{userId} — remove a user from a site."""
+        return self.delete(f"/auth/siteaccess/{self._q(site_id)}/user/{self._q(user_id)}")
+
+
+def get_client() -> PFClient:
+    """Get a Pathfinder client with configuration from environment / config file."""
+    config = load_pf_config()
+    return PFClient(config)

{bt_cli-0.4.56 → bt_cli-0.4.57}/src/bt_cli/pf/commands/__init__.py

@@ -7,6 +7,7 @@ from .machines import app as machines_app
 from .tokens import mcp_tokens_app, pats_app
 from .user import access as access_command
 from .user import whoami as whoami_command
+from .users import users_app
 
 app = typer.Typer(
     name="pf",
@@ -18,6 +19,7 @@ app.add_typer(auth_app, name="auth")
 app.add_typer(pats_app, name="pats")
 app.add_typer(mcp_tokens_app, name="mcp-tokens")
 app.add_typer(machines_app, name="machines")
+app.add_typer(users_app, name="users")
 
 app.command("whoami")(whoami_command)
 app.command("access")(access_command)

bt_cli-0.4.57/src/bt_cli/pf/commands/users.py

@@ -0,0 +1,298 @@
+"""Pathfinder user onboarding and access-assignment commands.
+
+Route status over the PAT gateway (probed 2026-06-11): invitation POSTs,
+Users/delete, and the productaccess/siteaccess grant/revoke routes are all
+deployed, but PAT principals are NOT authorized — a live productaccess
+grant POST returned the same empty-body 403 as the org-level GETs. These
+operations currently require cookie auth on app.beyondtrust.io; the
+commands stay wired for when the gateway opens up and exit 3 with a hint
+in the meantime.
+"""
+
+from contextlib import contextmanager
+from typing import Iterator, List, Optional
+
+import httpx
+import typer
+
+from bt_cli.core.output import (
+    OutputFormat,
+    confirm_action,
+    print_api_error,
+    print_detail,
+    print_error,
+    print_json,
+    print_success,
+    print_table,
+    print_warning,
+)
+
+users_app = typer.Typer(no_args_is_help=True, help="Platform users (invite, access, delete)")
+
+PRODUCTS = ("epmwm", "pra", "psc", "rs", "entitle", "epml", "insights", "secrets")
+PRODUCT_SLUGS = ", ".join(PRODUCTS)
+
+
+def _slug(value: str) -> str:
+    """Normalize a product slug, rejecting unknown ones before any API call.
+
+    A typo'd slug would otherwise surface as a bare 403 from the gateway.
+    """
+    slug = value.lower()
+    if slug not in PRODUCTS:
+        print_error(f"Unknown product '{value}' — valid slugs: {PRODUCT_SLUGS}")
+        raise typer.Exit(2)
+    return slug
+
+
+def _confirm(message: str, yes: bool) -> None:
+    """Confirm or exit. EOF (non-interactive stdin without --yes) exits cleanly."""
+    if yes:
+        return
+    try:
+        confirmed = confirm_action(message)
+    except EOFError:
+        print_error("Confirmation required — pass --yes/-y for non-interactive use")
+        raise typer.Exit(2)
+    if not confirmed:
+        raise typer.Exit(0)
+
+
+@contextmanager
+def _pf_call(operation: str) -> Iterator["PFClient"]:  # noqa: F821
+    """Open a PF client and translate failures into CLI output and exit codes.
+
+    An empty-body 403 is the PAT gateway's org-level block signature
+    (verified 2026-06-11) → exit 3 with the cookie-auth hint. A 403 with a
+    body is a real authorization error and falls through to the generic
+    handler, as do config errors from get_client() (e.g. missing
+    BT_PF_SITE_ID) → exit 1.
+    """
+    from bt_cli.pf.client import get_client
+
+    try:
+        with get_client() as client:
+            yield client
+    except typer.Exit:
+        raise
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 403 and not e.response.content:
+            print_warning(
+                "403 Forbidden — this is an org-level operation the PAT gateway "
+                "blocks for PAT principals; it currently requires cookie auth "
+                "on app.beyondtrust.io."
+            )
+            raise typer.Exit(3)
+        print_api_error(e, operation)
+        raise typer.Exit(1)
+    except Exception as e:
+        print_api_error(e, operation)
+        raise typer.Exit(1)
+
+
+@users_app.command("list")
+def list_users(
+    email: Optional[str] = typer.Option(None, "--email", help="Filter by email"),
+    first_name: Optional[str] = typer.Option(None, "--first-name", help="Filter by first name"),
+    last_name: Optional[str] = typer.Option(None, "--last-name", help="Filter by last name"),
+    active: Optional[str] = typer.Option(None, "--active", help="Filter by status"),
+    site_id: Optional[str] = typer.Option(None, "--site-id", "-s", help="Filter by site ID"),
+    user_id: Optional[str] = typer.Option(None, "--user-id", "-u", help="Filter by user ID"),
+    page: Optional[int] = typer.Option(None, "--page", help="Page number (1-based)"),
+    page_size: Optional[int] = typer.Option(None, "--page-size", help="Page size"),
+    output: OutputFormat = typer.Option(
+        OutputFormat.TABLE, "--output", "-o", help="Output format"
+    ),
+):
+    """List organization users (org-level — 403 over PAT as of 2026-06-11)."""
+    params = {
+        k: v
+        for k, v in {
+            "email": email,
+            "firstName": first_name,
+            "lastName": last_name,
+            "active": active,
+            "siteId": site_id,
+            "userId": user_id,
+            "page": page,
+            "pageSize": page_size,
+        }.items()
+        if v is not None
+    }
+    with _pf_call("list users") as client:
+        users = client.list_users(params or None) or []
+
+    if output == OutputFormat.JSON:
+        print_json(users)
+        return
+
+    rows = [
+        {
+            "id": u.get("id") or u.get("userId"),
+            "email": u.get("email"),
+            "name": f"{u.get('firstName') or ''} {u.get('lastName') or ''}".strip(),
+            "active": u.get("active"),
+            "mfa": u.get("mfaEnabled"),
+        }
+        for u in users
+    ]
+    print_table(rows, [
+        ("ID", "id"),
+        ("Email", "email"),
+        ("Name", "name"),
+        ("Active", "active"),
+        ("MFA", "mfa"),
+    ], title=f"Platform users ({len(rows)})")
+
+
+@users_app.command("invite")
+def invite_user(
+    email: str = typer.Option(..., "--email", "-e", help="Email address to invite"),
+    first_name: Optional[str] = typer.Option(None, "--first-name", help="First name"),
+    last_name: Optional[str] = typer.Option(None, "--last-name", help="Last name"),
+    site_id: Optional[str] = typer.Option(
+        None, "--site-id", "-s", help="Site to grant (default: configured BT_PF_SITE_ID)"
+    ),
+    site_name: Optional[str] = typer.Option(None, "--site-name", help="Site display name"),
+    residency: Optional[str] = typer.Option(None, "--residency", help="Site residency (e.g. US)"),
+    products: List[str] = typer.Option(
+        [], "--product", "-p", help=f"Product slug to grant on the site ({PRODUCT_SLUGS}); repeatable"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+    output: OutputFormat = typer.Option(
+        OutputFormat.TABLE, "--output", "-o", help="Output format"
+    ),
+):
+    """Invite a user to the organization — sends a real invitation email."""
+    slugs = [_slug(p) for p in products]
+
+    with _pf_call("invite user") as client:
+        site_id = site_id or client.site_id
+        site_meta = {"siteId": site_id}
+        if site_name:
+            site_meta["name"] = site_name
+        if residency:
+            site_meta["residency"] = residency
+
+        payload = {
+            "email": email,
+            "siteMetaData": [site_meta],
+            "productMetaData": [
+                {"name": s, "siteId": site_id, **({"siteName": site_name} if site_name else {})}
+                for s in slugs
+            ],
+        }
+        if first_name:
+            payload["firstName"] = first_name
+        if last_name:
+            payload["lastName"] = last_name
+
+        summary = f"Invite {email} to site {site_id}"
+        if slugs:
+            summary += f" with products: {', '.join(slugs)}"
+        _confirm(f"{summary} — sends an invitation email. Continue?", yes)
+
+        result = client.invite_user(payload) or {}
+
+    if output == OutputFormat.JSON:
+        print_json(result)
+        return
+    print_success(f"Invited {email}")
+    if isinstance(result, dict):
+        print_detail(result, [
+            ("Invite ID", "inviteId"),
+            ("User ID", "userId"),
+            ("Organization", "organizationId"),
+            ("Federated", "isFederated"),
+        ])
+
+
+@users_app.command("cancel-invite")
+def cancel_invite(
+    email: str = typer.Argument(..., help="Email address of the pending invite"),
+):
+    """Cancel a pending user invitation."""
+    with _pf_call("cancel invitation") as client:
+        client.cancel_invitation(email)
+    print_success(f"Cancelled pending invite for {email}")
+
+
+@users_app.command("delete")
+def delete_users(
+    user_ids: List[str] = typer.Argument(..., help="User ID(s) to delete"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+):
+    """Delete platform users (org admin; irreversible)."""
+    _confirm(f"Permanently delete {len(user_ids)} user(s): {', '.join(user_ids)}?", yes)
+    with _pf_call("delete users") as client:
+        client.delete_users(user_ids)
+    print_success(f"Deleted {len(user_ids)} user(s)")
+
+
+@users_app.command("grant")
+def grant_product(
+    user_id: str = typer.Option(..., "--user-id", "-u", help="User to grant access to"),
+    product: str = typer.Option(..., "--product", "-p", help=f"Product slug ({PRODUCT_SLUGS})"),
+    site_id: Optional[str] = typer.Option(
+        None, "--site-id", "-s", help="Site (default: configured BT_PF_SITE_ID)"
+    ),
+):
+    """Grant a user access to a product on a site."""
+    slug = _slug(product)
+    with _pf_call("grant product access") as client:
+        site_id = site_id or client.site_id
+        client.grant_product_access(slug, site_id, user_id)
+    print_success(f"Granted {slug} on site {site_id} to user {user_id}")
+
+
+@users_app.command("revoke")
+def revoke_product(
+    user_id: str = typer.Option(..., "--user-id", "-u", help="User to revoke access from"),
+    product: str = typer.Option(..., "--product", "-p", help=f"Product slug ({PRODUCT_SLUGS})"),
+    site_id: Optional[str] = typer.Option(
+        None, "--site-id", "-s", help="Site (default: configured BT_PF_SITE_ID)"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+):
+    """Revoke a user's access to a product on a site."""
+    slug = _slug(product)
+    with _pf_call("revoke product access") as client:
+        site_id = site_id or client.site_id
+        _confirm(f"Revoke {slug} on site {site_id} from user {user_id}?", yes)
+        client.revoke_product_access(slug, site_id, user_id)
+    print_success(f"Revoked {slug} on site {site_id} from user {user_id}")
+
+
+@users_app.command("add-to-site")
+def add_to_site(
+    user_id: str = typer.Option(..., "--user-id", "-u", help="User to add"),
+    site_id: Optional[str] = typer.Option(
+        None, "--site-id", "-s", help="Site (default: configured BT_PF_SITE_ID)"
+    ),
+    products: List[str] = typer.Option(
+        [], "--product", "-p", help="Product slug(s) to grant on the site too; repeatable"
+    ),
+):
+    """Grant a user access to a site (optionally with products)."""
+    slugs = [_slug(p) for p in products]
+    with _pf_call("grant site access") as client:
+        site_id = site_id or client.site_id
+        client.grant_site_access(site_id, user_id, slugs)
+    granted = f" with {', '.join(slugs)}" if slugs else ""
+    print_success(f"Added user {user_id} to site {site_id}{granted}")
+
+
+@users_app.command("remove-from-site")
+def remove_from_site(
+    user_id: str = typer.Option(..., "--user-id", "-u", help="User to remove"),
+    site_id: Optional[str] = typer.Option(
+        None, "--site-id", "-s", help="Site (default: configured BT_PF_SITE_ID)"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+):
+    """Revoke a user's access to a site."""
+    with _pf_call("revoke site access") as client:
+        site_id = site_id or client.site_id
+        _confirm(f"Remove user {user_id} from site {site_id}?", yes)
+        client.revoke_site_access(site_id, user_id)
+    print_success(f"Removed user {user_id} from site {site_id}")