bt-cli 0.4.31__tar.gz → 0.4.33__tar.gz

bt_cli-0.4.33/.claude/skills/epml/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: epml
+description: EPM Linux commands for endpoint privilege management — RBP roles/cmdgrps/usergrps, policy import/export, test suites, transactions, audit. Use when working with PMUL/RBP, PAT auth against api.beyondtrust.io, or `/site/<id>/epm/linux/` URLs.
+---
+
+# EPM Linux Commands (`bt epml`)
+
+## Configuration
+
+EPM Linux speaks to the cloud gateway with a **Personal Access Token** (PAT).
+The gateway URL takes a transform that the OpenAPI spec does NOT document — see "URL transform" below.
+
+```bash
+export BT_EPML_API_URL=https://api.beyondtrust.io       # default; usually omit
+export BT_EPML_SITE_ID=<your-site-uuid>                 # required
+export BT_EPML_PAT=PAT_xxxxxxxxxx                       # required (mint at app.beyondtrust.io)
+export BT_EPML_DEFAULT_HOST=100                         # default PMUL host id (optional)
+
+bt epml auth test     # confirms /settings is reachable
+bt epml auth status   # show current config (no secrets)
+```
+
+## URL transform — important
+
+The OpenAPI spec lists paths starting with `/api/...` and has an empty `servers`
+block. The deployed gateway requires a site/product prefix that ISN'T in the
+spec. The CLI handles this in one place (`_build_url`), but you'll see this if
+you debug raw curl:
+
+```
+spec path:  /api/<rest>
+real URL:   https://api.beyondtrust.io/site/<site-id>/epm/linux/<rest>
+```
+
+A direct `curl https://api.beyondtrust.io/api/v1/users -H "Authorization: Bearer <PAT>"` returns
+`401 {"error":"Access denied for this site"}` — that's NOT a PAT/audience problem,
+it's a missing path prefix.
+
+## Two-authorizer reality (PAT-OK vs IAM-blocked)
+
+The spec declares `nomine-authorizer` (PAT) globally with zero per-op overrides,
+but the gateway has some routes wired to AWS IAM (SigV4) instead. PAT cannot
+reach those — they return either `403 {"message":"Invalid key=value pair... SHA-256... Base64..."}`
+or `403 {"Message":"User is not authorized... no identity-based policy allows
+the execute-api:Invoke action"}`. Same root, different envelope.
+
+Known IAM-only paths (PAT-blocked):
+- `PUT /settings` (read is fine)
+- `POST/PUT/DELETE /v4/siems` (read is fine)
+- `/v1/hosts`, `/v6/users`, `/v6/auth`, `/v1/auth`, `/v2/appfeatures`
+- `/v7/directoryservices/*`, `/epml/license`, `/epml/licenseinfo`
+- All `/v6/pbul/rbp/*` (use the legacy `/pbul/{hostid}/rbp/*` instead)
+- **Inside testsuite**: `PUT /testsuite/{id}` and `POST /testsuite/test` (per-method split — list/get/create/delete/run *suites* are fine; PUT-test and DELETE-test are fine, but POST-add-test is IAM)
+
+## Auth + connection
+
+```bash
+bt epml auth test           # GET /settings, reports 401 vs 403 distinctly
+bt epml auth status         # show env config
+bt whoami                   # includes EPM Linux row
+```
+
+## Settings, users, hosts, license
+
+```bash
+bt epml settings list                        # /api/settings
+bt epml settings get session_timeout
+bt epml users list                           # /api/v1/users (table)
+bt epml users list --v2                      # /api/v2/users
+bt epml users get <user_id>
+bt epml hosts list                           # synthesized from /pbul/features
+bt epml hosts features                       # full feature flags per PMUL host
+bt epml license get                          # /api/epml/enhancedlicense
+```
+
+Note: `bt epml hosts list` is synthesized from `/api/pbul/features` because
+`/api/v1/hosts` is IAM-blocked.
+
+## Audit, SIEMs, External APIs, Iologs, Client packages
+
+```bash
+bt epml audit sessions list --take 50
+bt epml audit sessions categories
+bt epml siems list                                 # read only — write is IAM
+bt epml external-apis list
+bt epml external-apis get <id>
+bt epml iolog list                                 # default host
+bt epml iolog list -H 200 --start 0 --len 200
+bt epml client-pkg list                            # signed S3 URLs (~30min TTL)
+bt epml client-pkg status                          # build queue
+bt epml client-pkg link epml-client.x86_64.rpm
+```
+
+## RBP — Role-Based Policy
+
+All under `/api/pbul/{hostid}/rbp/...` (default host = `BT_EPML_DEFAULT_HOST`).
+Use `-H/--host` to override.
+
+```bash
+# Command groups
+bt epml rbp cmdgrps list
+bt epml rbp cmdgrps create --name "Admin Tools" --description "..."
+bt epml rbp cmdgrps delete 12,13
+bt epml rbp cmdgrps commands list <cmdgrp_id>
+bt epml rbp cmdgrps commands add <cmdgrp_id> --commands "vi,less,cat"
+bt epml rbp cmdgrps commands remove <cmdgrp_id> --ids 1,2
+
+# Host groups
+bt epml rbp hostgrps list
+bt epml rbp hostgrps create --name "Admin Hosts"
+bt epml rbp hostgrps hosts add <hostgrp_id> --hosts "web-*,db-*"
+
+# User groups
+bt epml rbp usergrps list
+bt epml rbp usergrps create --name "Helpdesk"
+bt epml rbp usergrps users add <usergrp_id> --users "alice,bob"
+
+# Time/date groups
+bt epml rbp tmdategrps list
+bt epml rbp tmdategrps create --name "Working Hours"
+
+# Roles + assignments
+bt epml rbp roles list
+bt epml rbp roles create --name "Helpdesk Role"
+bt epml rbp roles duplicate <role_id>
+bt epml rbp roles cmdgrps   add    <role_id> --ids 1,2
+bt epml rbp roles cmdgrps   remove <role_id> <cmdgrp_id>
+bt epml rbp roles hostgrps  list   <role_id>
+bt epml rbp roles usergrps  add    <role_id> --ids 5
+bt epml rbp roles tmdategrps add   <role_id> --ids 1
+
+# Entitlement report ('who can do what')
+bt epml rbp entitlement run
+bt epml rbp entitlement run --raw
+
+# Policy export/import/versions
+bt epml rbp policy export --file policy.json
+bt epml rbp policy import policy.json
+bt epml rbp policy versions
+bt epml rbp policy diff
+bt epml rbp policy snapshot
+bt epml rbp policy revert
+bt epml rbp policy delete-all --yes-i-mean-it      # destructive, gated
+```
+
+## Test suites + transactions (the killer workflow)
+
+```bash
+# Suites (CRUD is mostly Bearer-OK; update-suite and add-test are IAM-only — see caveats)
+bt epml rbp tests suites list
+bt epml rbp tests suites create -n "production-policy" -d "..."
+bt epml rbp tests suites get <suite_id>
+bt epml rbp tests suites delete <suite_id>
+
+# Tests within a suite (add is IAM-blocked → use the GUI to add tests; CLI to run)
+bt epml rbp tests tests update <test_id> -f test.json
+bt epml rbp tests tests delete <test_id>
+
+# Run a suite — exits 0 on pass, 1 on any failure
+bt epml rbp tests run --suite <suite_id>
+
+# Transactions
+bt epml rbp tx status
+bt epml rbp tx begin
+bt epml rbp tx commit
+bt epml rbp tx rollback
+bt epml rbp tx abort
+
+# Quick: tests-then-deploy — open a tx, edit, then commit-or-rollback based on tests
+bt epml rbp tx begin
+# ... make changes via rbp cmdgrps/roles/etc ...
+bt epml quick tests-then-deploy --suite <suite_id>      # commits if pass; rollbacks if fail
+```
+
+## Destructive operations (always confirm)
+
+- `bt epml rbp policy delete-all --yes-i-mean-it` — wipes the entire RBP DB
+- `bt epml rbp <resource> delete <ids>` — bulk delete by ID list
+- `bt epml rbp tx commit` — applies in-flight changes
+- `bt epml client-pkg ...` POST endpoints — triggers a real installer build
+
+## Path-version policy (CLI internal)
+
+Where the spec offers both legacy `/api/pbul/{hostid}/rbp/<x>` and newer
+`/api/v6/pbul/rbp/<x>`, the CLI uses the **legacy** version because v6 routes
+are mostly IAM-only. If the API team flips v6 to PAT later, the swap is a
+single-PR change in `client/base.py`.
+
+## Output formats
+
+All `list` and `get` commands accept `-o/--output table|json`. Table is the
+default for list; JSON is the default for single-resource gets.
+
+## Troubleshooting
+
+- **401 "Access denied for this site"** — the URL didn't include `/site/<id>/epm/linux/`. Should never happen via the CLI; if you see it, file a bug.
+- **403 IAM error** — the operation is on an IAM-only route. See the IAM-blocked list above.
+- **400 with detailed validation messages** — auth passed; the body shape is wrong. Cross-reference `/home/admin/epml-cloud-spec.json` schemas.
+- **Build server returns "building": true** — `bt epml client-pkg status` keeps `true` while a build is queued; idempotent to re-check.

{bt_cli-0.4.31 → bt_cli-0.4.33}/CLAUDE.md

@@ -1,6 +1,6 @@
 # BT-CLI
 
-BeyondTrust Platform CLI for Password Safe, Entitle, PRA, and EPM Windows. **Version: 0.4.31**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, and EPM Linux. **Version: 0.4.33**
 
 ## Setup
 
@@ -21,6 +21,7 @@ Use these slash commands for detailed product guidance:
 | `/pra` | PRA - jump items, vault, SSH CA |
 | `/entitle` | Entitle - JIT access, bundles, workflows |
 | `/epmw` | EPM Windows - computers, policies, requests |
+| `/epml` | EPM Linux - RBP roles/cmdgrps/usergrps, policy, test suites, transactions |
 
 ## Command Structure
 
@@ -31,6 +32,7 @@ Use these slash commands for detailed product guidance:
 | PRA | `bt pra` | `jump-items`, `vault`, `jump-groups`, `quick` |
 | Entitle | `bt entitle` | `integrations`, `resources`, `bundles`, `permissions` |
 | 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` |
 
 ## Common Patterns
 
@@ -58,6 +60,7 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 | Entitle | `page`/`perPage` | `{"result": [...], "pagination": {...}}` |
 | PRA | `per_page`/`current_page` (1-indexed) | Array (pagination in headers) |
 | EPMW | `pageNumber`/`pageSize` | `{"data": [...], "totalCount": N}` |
+| EPML | varies — `take`/`skip` (audit, siems), `start`/`len` (iologs), plain arrays | mostly arrays; some `{total, data}` |
 
 **Important:**
 - EPMW computers: Use `archive` not `delete` (405 error)
@@ -67,6 +70,8 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - Entitle permissions: Use server-side filters (`--resource`, `--user`, `--integration`) - dataset can be 20k+ records
 - Entitle users: Use `--all` flag only when needed - default fetches first page only
 - Windows builds: Rich must be pinned to `<14.0.0` (Rich 14 has PyInstaller unicode issues)
+- **EPML URL transform**: spec paths start with `/api/...` but real URL is `https://api.beyondtrust.io/site/<site-id>/epm/linux/<spec-path-minus-/api/>`. Encapsulated in client `_build_url` — never bypass it.
+- **EPML two authorizers**: spec claims `nomine-authorizer` (PAT) globally but the gateway has IAM-only routes (return 403 with AWS-flavored body). PAT cannot reach those. Documented per-op in `src/bt_cli/data/skills/epml/SKILL.md`. Where `/v6/pbul/rbp/...` exists alongside legacy `/pbul/{hostid}/rbp/...`, prefer legacy — v6 is mostly IAM-only.
 
 ## Functional vs Managed Accounts
 
@@ -94,7 +99,8 @@ src/bt_cli/
 ├── pws/                # Password Safe
 ├── pra/                # PRA
 ├── entitle/            # Entitle
-└── epmw/               # EPM Windows
+├── epmw/               # EPM Windows
+└── epml/               # EPM Linux (PAT auth, /site/<id>/epm/linux/... URLs)
 ```
 
 Each product follows: `client/` (API), `commands/` (CLI), `models/` (Pydantic)

{bt_cli-0.4.31 → bt_cli-0.4.33}/PKG-INFO

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

bt_cli-0.4.33/epml-implementation-plan.md

@@ -0,0 +1,259 @@
+# Plan: Add EPM Linux (`bt epml`) to bt-cli
+
+## Context
+
+`bt-cli` v0.4.32 already supports PWS, PRA, Entitle, EPMW. EPM Linux is the Linux counterpart to EPMW (Windows). API is reached via the BeyondTrust public gateway (`api.beyondtrust.io`) authorized by Personal Access Tokens (PATs) issued from `app.beyondtrust.io`.
+
+Discovery is done. Cached spec at `/home/admin/epml-cloud-spec.json` (OpenAPI 3.0.0, version 25.1.6, 160 paths / 205 ops, 12 product-area tags). Verified live against site `c882e07c-753b-4fcd-a1e6-7d39defec5ae` on 2026-05-01.
+
+## Two non-obvious gateway facts the spec doesn't tell you
+
+### 1. URL transform
+
+The spec lists every path with a `/api/` prefix and an empty `servers` block. The gateway does NOT route those paths at the document root. Real URL shape:
+
+```
+https://api.beyondtrust.io/site/<site-id>/epm/linux/<spec-path-minus-leading-/api/>
+```
+
+So spec `/api/v1/users` → real URL `/site/<site-id>/epm/linux/v1/users`. Spec `/api/pbul/{hostid}/rbp/cmdgrps` → real URL `/site/<site-id>/epm/linux/pbul/{hostid}/rbp/cmdgrps`.
+
+### 2. Two authorizers, one spec
+
+Spec declares `nomine-authorizer` (PAT) globally with **zero per-op overrides**. The gateway disagrees: a chunk of routes are wired to AWS IAM (SigV4), and PATs cannot reach those.
+
+- **PAT-Bearer routes (200 OK)** — most `/pbul/{hostid}/rbp/...`, `/pbul/features`, `/pbul/rbp/testsuite/*`, `/v1/users`, `/v2/users`, `/v4/audit/sessions/*`, `/v4/siems` (read), `/externalapis`, `/epml/enhancedlicense`, `/epml/clientpkg`, `/settings` (read), `/pbul/{hostid}/iologs`.
+- **IAM-only routes (403, AWS SigV4 error)** — all `/v6/pbul/rbp/*`, `/v1/hosts`, `/v6/users`, `/v1/auth/*`, `/v6/auth/*`, `/v2/appfeatures`, `/v7/directoryservices`, `/epml/license`, `/epml/licenseinfo`, `/v4/audit` (root), `/pbul/{hostid}/rbp/usrgrps`, `/pbul/{hostid}/rbp/timedategrps`, `/pbul/{hostid}/rbp/version`, `PUT /settings`, `POST /v4/siems`, etc.
+
+**Path-version policy**: prefer legacy `/pbul/{hostid}/rbp/...` over the newer `/v6/pbul/rbp/...` because the legacy host-scoped variants are mostly Bearer-reachable, the v6 variants mostly aren't. Opposite of what spec-versioning instinct suggests.
+
+### Key gap for downstream design
+
+**[Updated 2026-05-01]** Earlier draft called out `/pbul/{hostid}/rbp/usrgrps` as IAM-blocked — that was a path-name typo on my end. The real spec name is `usergrps`, and it (along with `tmdategrps` and `versions`) is fully Bearer-reachable. **No critical gaps in the RBP family for a PAT-only CLI.** All four child entity types under a role (cmdgrps, hostgrps, usergrps, tmdategrps) plus full policy export/import/versions/transactions ship as Bearer.
+
+## Command tree: `bt epml`
+
+```
+bt epml
+  auth          test | status
+  settings      list | get
+  hosts         list                          # synthesized from /pbul/features (since /v1/hosts is IAM)
+  users         list | get
+  license       get                            # /epml/enhancedlicense
+  siems         list | get                     # read only — write is IAM
+  audit         sessions list | sessions get | sessions categories
+  external-apis list | get | create | update | delete
+  client-pkg    list | status | build          # build = POST /epml/clientpkg
+  iolog         list | get | replay | playback | commands
+  rbp
+    cmdgrps     list | get | create | update | delete | members list/add/remove
+    hostgrps    list | get | create | update | delete | members ...
+    roles       list | get | create | update | delete | duplicate
+                  cmdgrps add/remove | hostgrps add/remove
+    entitlement run                            # /pbul/{hostid}/rbp/entitlement
+    policy      export | import | versions     # versions list / get / revert
+    tests       suites list | suites get | suites create | suites update | suites delete
+                tests add | tests update | tests delete | run
+    tx          begin | commit | rollback | status
+  quick         pasm-import-policy | tests-then-deploy   # cross-product workflows (later)
+```
+
+Deferred behind IAM (don't implement; document in skill file):
+- `bt epml rbp usrgrps`, `rbp timedategrps`, `rbp version`
+- `bt epml settings update`
+- `bt epml siems create|update|delete`
+- `bt epml license upload|retire|clients`
+- `bt epml directory ...` (entire DirectoryServices tag)
+- `bt epml auth roles|users|...` (appliance RBAC mgmt)
+- Everything under `/v6/pbul/rbp/*`
+
+## Implementation phases
+
+### Phase 1 — Foundation + auth smoke (one PR)
+
+**1a. New `PATAuth` strategy** — `src/bt_cli/core/auth.py`
+- Class `PATAuth(AuthStrategy)` with `pat: str` (and optional `site_id` for URL composition).
+- `authenticate()` is a no-op (PAT is already a bearer credential, no token exchange).
+- Sets `Authorization: Bearer <pat>` on every request.
+- No `sign_out()`.
+
+**1b. New `EPMLConfig`** — `src/bt_cli/core/config.py`
+- Fields: `api_url` (default `https://api.beyondtrust.io`), `site_id`, `pat`, `default_host_id` (default `100`), `verify_ssl`, `timeout`.
+- `load_epml_config()` env vars: `BT_EPML_API_URL`, `BT_EPML_SITE_ID`, `BT_EPML_PAT`, `BT_EPML_DEFAULT_HOST`, `BT_EPML_VERIFY_SSL`, `BT_EPML_TIMEOUT`.
+- Wire into `load_config()` dispatcher under key `"epml"`.
+
+**1c. Add `"epml"` entry in `src/bt_cli/core/config_file.py` PRODUCTS dict**
+- Fields: `api_url`, `site_id`, `pat`, `default_host_id`, `verify_ssl`, `timeout`.
+
+**1d. Module skeleton**
+- `src/bt_cli/epml/__init__.py`
+- `src/bt_cli/epml/client/__init__.py` — exports `EPMLClient, get_client`
+- `src/bt_cli/epml/client/base.py` — httpx client. **Critical detail**: every request URL is built as `f"{api_url}/site/{site_id}/epm/linux{path}"` where `path` is the spec path with `/api/` stripped. Provide a single `_build_path(spec_path: str) -> str` helper used by every method.
+- `src/bt_cli/epml/commands/__init__.py` — registers sub-typer apps
+- `src/bt_cli/epml/commands/auth.py` — `test` calls `GET /settings` and reports 200/403/401 distinctly (the 401 vs 403 split tells us which of the two failure modes — wrong site prefix vs IAM-blocked path — happened).
+- `src/bt_cli/epml/models/__init__.py`
+- `src/bt_cli/epml/models/common.py`
+
+**1e. Wire into CLI** — `src/bt_cli/cli.py`
+- `_get_epml_app()` lazy loader.
+- `app.add_typer(...)` registration.
+- Add `_test_epml_connection()` → list settings.
+- Add EPM-L line to `whoami` output.
+- Add `"epml"` to the valid-product list in `tree_command` and `find` command.
+- Update `main_callback` help text.
+
+**Verify**: `bt epml auth test` connects, gets 200 from `/settings`, prints "Connected to EPM Linux at site <id>".
+
+### Phase 2 — Read surface (one PR)
+
+Models + client methods + commands for everything that's purely a GET against a Bearer-reachable path:
+
+- `settings list/get` — `/settings`
+- `users list` — `/v1/users` (paginated; spec lists `page`/`pageSize`)
+- `users get` — `/v1/users/{id}`
+- `hosts list` — derived from `/pbul/features` JSON (extract HostID, Hostname, IP, PbulVersion, Features map). Synthesized resource since `/v1/hosts` is IAM-blocked.
+- `license get` — `/epml/enhancedlicense`
+- `siems list` — `/v4/siems`
+- `siems get` — `/v4/siems/{id}` (verify Bearer first)
+- `audit sessions list` — `/v4/audit/sessions`
+- `audit sessions get` — `/v4/audit/sessions/{id}`
+- `audit sessions categories` — `/v4/audit/sessions/categories`
+- `client-pkg list` — `/epml/clientpkg`
+- `client-pkg status` — `/epml/clientpkg/status`
+- `iolog list` — `/pbul/{hostid}/iologs` (host-scoped — defaults to `default_host_id`, override `--host`)
+
+Pydantic models in `models/` per resource. Output formatter handles JSON/table/raw consistently with PWS pattern.
+
+### Phase 3 — RBP CRUD (one PR, biggest)
+
+Resources, all under `/pbul/{hostid}/rbp/...`:
+
+**Command groups** (`rbp cmdgrps`)
+- `list` — `GET /pbul/{hostid}/rbp/cmdgrps`
+- `get` — `GET /pbul/{hostid}/rbp/cmdgrps/{id}`
+- `create` — `POST /pbul/{hostid}/rbp/cmdgrps`
+- `update` — `PUT /pbul/{hostid}/rbp/cmdgrps/{id}`
+- `delete` — `DELETE /pbul/{hostid}/rbp/cmdgrps/{id}`
+- `members list|add|remove` — child resource
+
+**Host groups** (`rbp hostgrps`) — same shape
+
+**Roles** (`rbp roles`)
+- CRUD + `duplicate` (if spec has it; otherwise GET-then-POST)
+- Sub-resources: cmdgrps, hostgrps add/remove (NOT usrgrps — IAM-blocked)
+
+**Entitlement report** (`rbp entitlement run`)
+- `GET /pbul/{hostid}/rbp/entitlement` — returns "who can run what" report
+- `--raw` flag → `/pbul/{hostid}/rbp/entitlement/raw`
+
+**Policy** (`rbp policy`)
+- `export` — full RBP DB serialization
+- `import` — file upload
+- `versions list|get|revert`
+- `delete-all` — gated behind `--yes-i-mean-it` confirmation
+
+### Phase 4 — RBP test suites + transactions (one PR)
+
+**Test suites** (`rbp tests`)
+- `suites list|get|create|update|delete`
+- `tests add|update|delete` (under a suite)
+- `run --suite <id>` — `GET /pbul/{hostid}/rbp/testsuite/{id}/run` returns `{total, failures}` — exit 0 on zero failures, exit 1 with failure detail otherwise. **This is the killer command.**
+
+**Transactions** (`rbp tx`)
+- `begin` — opens a transaction (returns transaction ID)
+- `commit` — atomic apply
+- `rollback` — discard
+- `status` — current pending changes
+
+Pair them in a `quick tests-then-deploy` workflow:
+1. `tx begin`
+2. apply user-supplied changes
+3. `tests run --suite <id>`
+4. on success → `tx commit`; on failure → `tx rollback`
+
+### Phase 5 — Tests + skill + docs (one PR)
+
+- `tests/epml/__init__.py`
+- `tests/epml/test_client.py` — respx-mocked unit tests for URL transform, auth header, pagination
+- `tests/epml/test_commands.py` — CLI invocations with mocked client
+- `tests/conftest.py` — `mock_epml_config`, `epml_env_vars` fixtures
+- `tests/fixtures/responses.py` — `EPML_*` constants
+- `src/bt_cli/data/skills/epml/SKILL.md` — command reference, the URL-transform gotcha, the IAM-blocked list, host-id concept, test-suite workflow
+- Update `btcli/CLAUDE.md` and `src/bt_cli/data/CLAUDE.md` — add `bt epml` row to the Command Structure table
+
+## Files to create (≈25)
+
+```
+src/bt_cli/epml/__init__.py
+src/bt_cli/epml/client/__init__.py
+src/bt_cli/epml/client/base.py
+src/bt_cli/epml/commands/__init__.py
+src/bt_cli/epml/commands/auth.py
+src/bt_cli/epml/commands/settings.py
+src/bt_cli/epml/commands/users.py
+src/bt_cli/epml/commands/hosts.py
+src/bt_cli/epml/commands/license.py
+src/bt_cli/epml/commands/siems.py
+src/bt_cli/epml/commands/audit.py
+src/bt_cli/epml/commands/external_apis.py
+src/bt_cli/epml/commands/client_pkg.py
+src/bt_cli/epml/commands/iolog.py
+src/bt_cli/epml/commands/rbp_cmdgrps.py
+src/bt_cli/epml/commands/rbp_hostgrps.py
+src/bt_cli/epml/commands/rbp_roles.py
+src/bt_cli/epml/commands/rbp_entitlement.py
+src/bt_cli/epml/commands/rbp_policy.py
+src/bt_cli/epml/commands/rbp_tests.py
+src/bt_cli/epml/commands/rbp_tx.py
+src/bt_cli/epml/models/__init__.py
+src/bt_cli/epml/models/common.py
+src/bt_cli/epml/models/{user,host,license,siem,audit,clientpkg,cmdgrp,hostgrp,role,test,policy,settings,iolog}.py  (one per resource as needed)
+src/bt_cli/data/skills/epml/SKILL.md
+tests/epml/__init__.py
+tests/epml/test_client.py
+tests/epml/test_commands.py
+```
+
+## Files to modify
+
+```
+src/bt_cli/core/auth.py            — add PATAuth (~25 lines)
+src/bt_cli/core/config.py          — add EPMLConfig + load_epml_config (~40 lines)
+src/bt_cli/core/config_file.py     — add "epml" entry (~10 lines)
+src/bt_cli/cli.py                  — lazy loader, register, whoami test, tree, find, help text
+tests/conftest.py                  — fixtures
+tests/fixtures/responses.py        — EPML_* mock constants
+btcli/CLAUDE.md                    — add bt epml row + 1-line callout for the URL transform
+src/bt_cli/data/CLAUDE.md          — same
+```
+
+## Key design decisions
+
+1. **Auth: dedicated `PATAuth` strategy.** Cleaner than overloading existing OAuth2 strategies; the auth flow is genuinely different (no token exchange, just a static bearer credential).
+2. **URL transform encapsulated in `_build_path()`.** Every client method calls it. Anyone reading the spec and writing a new method needs zero awareness — they paste the spec path verbatim.
+3. **Synthesize `hosts list` from `/pbul/features`.** `/v1/hosts` is IAM-blocked, but `/pbul/features` returns the host data we need anyway. Surface as a normal-looking command; document the substitution in the skill file.
+4. **Default host-id baked into config.** Most RBP commands take `--host` but default to `BT_EPML_DEFAULT_HOST` (default `100` per the discovery). Mirrors how PWS handles workgroup IDs.
+5. **Skip everything IAM-blocked.** Don't add stub commands. Skill file documents what's intentionally absent and why, so users don't ask "why no `bt epml directory`."
+6. **Path-version pick: legacy over v6.** Where the spec has both `/pbul/{hostid}/rbp/X` (legacy) and `/v6/pbul/rbp/X` (newer), use legacy — it's Bearer, v6 is IAM. If the API team flips v6 to Bearer later, swap in a single PR.
+7. **Env var prefix `BT_EPML_`.** Consistent with `BT_PWS_`, `BT_PRA_`, `BT_EPM_` (Windows).
+
+## What to bring back to the API team
+
+Capture in the skill file as known issues; track separately as upstream asks:
+
+1. Spec global security claims `nomine-authorizer` for every op, but the gateway has IAM-only routes. Either flip those to Bearer or override per-op `security` in the spec so it stops lying.
+2. `/pbul/{hostid}/rbp/usrgrps` IAM-only blocks core RBP workflows — highest-priority flip request.
+3. `/settings` is read-Bearer but write-IAM (same path, two authorizers per method). Unusual config.
+4. Service-account / non-human auth path. PATs are user-bound. CLI/automation needs an alternative; nothing in the EPM-L surface offers one today.
+5. `servers` is empty in the spec; the `/site/<id>/epm/linux/` prefix is invisible to anyone reading the OpenAPI doc. Add `servers: [{url: "https://api.beyondtrust.io/site/{siteId}/epm/linux", variables: {...}}]` and strip `/api/` from paths.
+
+## Verification
+
+1. `bt epml auth test` — 200 from `/settings`
+2. `bt epml hosts list` — shows HostID 100 PMULPolicy
+3. `bt epml users list` — returns user list
+4. `bt epml rbp cmdgrps list --host 100` — non-empty
+5. `bt epml rbp tests run --suite <id>` — runs and exits cleanly
+6. `bt tree epml` — full tree
+7. `bt whoami` — includes EPM-L line
+8. `pytest tests/epml/ -v` — all green

{bt_cli-0.4.31 → bt_cli-0.4.33}/pyproject.toml

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

{bt_cli-0.4.31 → bt_cli-0.4.33}/src/bt_cli/__init__.py

@@ -1,3 +1,3 @@
 """BeyondTrust Unified Admin CLI."""
 
-__version__ = "0.4.31"
+__version__ = "0.4.33"