bt-cli 0.4.45__tar.gz → 0.4.47__tar.gz

{bt_cli-0.4.45 → bt_cli-0.4.47}/CLAUDE.md

@@ -1,6 +1,6 @@
 # BT-CLI
 
-BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, and EPM Linux. **Version: 0.4.45**
+BeyondTrust Platform CLI for Password Safe, Entitle, PRA, EPM Windows, EPM Linux, and the BeyondTrust Secrets API. **Version: 0.4.47**
 
 ## Setup
 
@@ -31,6 +31,7 @@ Use these slash commands for detailed product guidance:
 | `/entitle` | Entitle - JIT access, bundles, workflows |
 | `/epmw` | EPM Windows - computers, policies, requests |
 | `/epml` | EPM Linux - RBP roles/cmdgrps/usergrps, policy, test suites, transactions |
+| `/secrets` | Secrets API - folders, static, dynamic AWS credentials, leases, integrations |
 
 ## Command Structure
 
@@ -42,6 +43,7 @@ Use these slash commands for detailed product guidance:
 | 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` |
+| Secrets API | `bt secrets` | `folders`, `static`, `dynamic` (incl. `generate`), `leases`, `integrations` |
 
 ## Common Patterns
 
@@ -70,6 +72,7 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 | 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}` |
+| Secrets | `path`/`recursive`/`folder` query params | `{"data": [...]}` for lists; bare objects for single GETs |
 
 **Important:**
 - EPMW computers: Use `archive` not `delete` (405 error)
@@ -84,6 +87,8 @@ PASSWORD=$(bt pws quick checkout -s server -a admin --raw)
 - **EPML body-shape gotchas**: role create needs `action ∈ {A,R}`; hostgrp/usergrp create needs `type ∈ {I,E}` (Internal=static / External=directory-resolved); role assignments need `--kind S|R|B` for hostgrps/usergrps (S=Submit user, R=Run-as user); collection deletes use `?id=N` query params (CLI loops); child collections (commands/hosts/users/tmdates) have **no per-item delete** — `clear` nukes all, use `replace` to keep some.
 - **EPML role update is upsert-on-id (overwrite, not partial)**: hitting `POST /roles` with `{id, ...}` clears any field you don't include. The CLI's `roles update` does read-modify-write so it feels partial; child relations are filtered out of the merge so assignments survive. Direct `curl` users must send the full record.
 - **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-02-16` (NOT 2026-01-02); `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.
 
 ## Functional vs Managed Accounts
 
@@ -112,7 +117,8 @@ src/bt_cli/
 ├── pra/                # PRA
 ├── entitle/            # Entitle
 ├── epmw/               # EPM Windows
-└── epml/               # EPM Linux (PAT auth, /site/<id>/epm/linux/... URLs)
+├── epml/               # EPM Linux (PAT auth, /site/<id>/epm/linux/... URLs)
+└── secrets/            # BeyondTrust Secrets API (PAT auth, /site/<id>/secrets/... URLs)
 ```
 
 Each product follows: `client/` (API), `commands/` (CLI), `models/` (Pydantic)

{bt_cli-0.4.45 → bt_cli-0.4.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bt-cli
-Version: 0.4.45
+Version: 0.4.47
 Summary: BeyondTrust Platform CLI (unofficial) - Password Safe, Entitle, PRA, EPM
 Author-email: Dave Grendysz <dgrendysz@beyondtrust.com>
 License: MIT
@@ -57,6 +57,7 @@ Unofficial BeyondTrust Platform CLI - manage privileged access across your envir
 | **Entitle** | `bt entitle` | Just-in-time access requests and approval workflows |
 | **PRA** | `bt pra` | Privileged remote access - jump items, sessions, vault |
 | **EPM Windows** | `bt epmw` | Endpoint privilege management - computers, policies, admin requests |
+| **Secrets API** | `bt secrets` | BeyondTrust Secrets API — folders, static secrets, dynamic AWS credentials, leases |
 
 ## Installation
 
@@ -105,6 +106,33 @@ export BT_EPM_CLIENT_ID=your-client-id
 export BT_EPM_CLIENT_SECRET=your-client-secret
 ```
 
+### Secrets API
+
+PAT-bearer auth against the BeyondTrust public API gateway. Mint a PAT at
+[app.beyondtrust.io](https://app.beyondtrust.io).
+
+```bash
+export BT_SECRETS_API_URL=https://api.beyondtrust.io      # default
+export BT_SECRETS_SITE_ID=<site-uuid>                     # required
+export BT_SECRETS_PAT=PAT_xxx                             # required
+export BT_SECRETS_API_VERSION=2026-02-16                  # default (doc page is stale)
+```
+
+Common commands:
+
+```bash
+bt secrets folders list -p lab                    # filter server-side (recursive default)
+bt secrets dynamic list -p lab                    # all dynamic-secret configs under lab/
+bt secrets dynamic generate lab/aws/ec2-readonly  # mint shell `export AWS_*` lines
+eval $(bt secrets dynamic generate lab/aws/ec2-readonly)  # load into current shell
+bt secrets leases list lab/aws/ec2-readonly       # who has active leases
+bt secrets static get lab/db/creds                # read a static secret (default JSON)
+```
+
+`bt secrets dynamic generate` mints **real** AWS STS credentials and is
+audited — don't loop it. `bt secrets leases revoke` is scope-gated; most
+PATs return 403 and exit code 3 with a clean warning. TTL still revokes.
+
 ### Using a .env File
 
 Create a `.env` file and source it before running commands:
@@ -121,6 +149,7 @@ bt pws auth test      # Test Password Safe connection
 bt entitle auth test  # Test Entitle connection
 bt pra auth test      # Test PRA connection
 bt epmw auth test     # Test EPM Windows connection
+bt secrets auth test  # Test Secrets API connection
 ```
 
 ---

{bt_cli-0.4.45 → bt_cli-0.4.47}/README.md

@@ -10,6 +10,7 @@ Unofficial BeyondTrust Platform CLI - manage privileged access across your envir
 | **Entitle** | `bt entitle` | Just-in-time access requests and approval workflows |
 | **PRA** | `bt pra` | Privileged remote access - jump items, sessions, vault |
 | **EPM Windows** | `bt epmw` | Endpoint privilege management - computers, policies, admin requests |
+| **Secrets API** | `bt secrets` | BeyondTrust Secrets API — folders, static secrets, dynamic AWS credentials, leases |
 
 ## Installation
 
@@ -58,6 +59,33 @@ export BT_EPM_CLIENT_ID=your-client-id
 export BT_EPM_CLIENT_SECRET=your-client-secret
 ```
 
+### Secrets API
+
+PAT-bearer auth against the BeyondTrust public API gateway. Mint a PAT at
+[app.beyondtrust.io](https://app.beyondtrust.io).
+
+```bash
+export BT_SECRETS_API_URL=https://api.beyondtrust.io      # default
+export BT_SECRETS_SITE_ID=<site-uuid>                     # required
+export BT_SECRETS_PAT=PAT_xxx                             # required
+export BT_SECRETS_API_VERSION=2026-02-16                  # default (doc page is stale)
+```
+
+Common commands:
+
+```bash
+bt secrets folders list -p lab                    # filter server-side (recursive default)
+bt secrets dynamic list -p lab                    # all dynamic-secret configs under lab/
+bt secrets dynamic generate lab/aws/ec2-readonly  # mint shell `export AWS_*` lines
+eval $(bt secrets dynamic generate lab/aws/ec2-readonly)  # load into current shell
+bt secrets leases list lab/aws/ec2-readonly       # who has active leases
+bt secrets static get lab/db/creds                # read a static secret (default JSON)
+```
+
+`bt secrets dynamic generate` mints **real** AWS STS credentials and is
+audited — don't loop it. `bt secrets leases revoke` is scope-gated; most
+PATs return 403 and exit code 3 with a clean warning. TTL still revokes.
+
 ### Using a .env File
 
 Create a `.env` file and source it before running commands:
@@ -74,6 +102,7 @@ bt pws auth test      # Test Password Safe connection
 bt entitle auth test  # Test Entitle connection
 bt pra auth test      # Test PRA connection
 bt epmw auth test     # Test EPM Windows connection
+bt secrets auth test  # Test Secrets API connection
 ```
 
 ---

{bt_cli-0.4.45 → bt_cli-0.4.47}/pyproject.toml

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

{bt_cli-0.4.45 → bt_cli-0.4.47}/src/bt_cli/__init__.py

@@ -1,3 +1,3 @@
 """BeyondTrust Unified Admin CLI."""
 
-__version__ = "0.4.45"
+__version__ = "0.4.47"

{bt_cli-0.4.45 → bt_cli-0.4.47}/src/bt_cli/cli.py

@@ -89,6 +89,12 @@ def _get_epml_app() -> typer.Typer:
     return epml_app
 
 
+def _get_secrets_app() -> typer.Typer:
+    """Lazy load BeyondTrust Secrets API commands."""
+    from .secrets.commands import app as secrets_app
+    return secrets_app
+
+
 def _get_configure_app() -> typer.Typer:
     """Lazy load configure commands."""
     from .commands.configure import app as configure_app
@@ -134,6 +140,11 @@ try:
 except Exception:
     pass  # EPML module not ready yet
 
+try:
+    app.add_typer(_get_secrets_app(), name="secrets", help="BeyondTrust Secrets API commands")
+except Exception:
+    pass  # Secrets module not ready yet
+
 try:
     app.add_typer(_get_configure_app(), name="configure", help="Configure bt-cli settings")
 except Exception:
@@ -288,9 +299,9 @@ def tree_command(
 
     if product:
         product = product.lower()
-        if product not in ["pws", "pra", "entitle", "epmw", "epml", "quick", "configure"]:
+        if product not in ["pws", "pra", "entitle", "epmw", "epml", "secrets", "quick", "configure"]:
             console.print(f"[red]Unknown product: {product}[/red]")
-            console.print("Available: pws, pra, entitle, epmw, epml, quick, configure")
+            console.print("Available: pws, pra, entitle, epmw, epml, secrets, quick, configure")
             raise typer.Exit(1)
 
     tree = Tree("[bold cyan]bt[/bold cyan]")
@@ -404,6 +415,16 @@ def tree_command(
         rbp.add("tx status|begin|commit|rollback|abort")
         epml.add("[green]quick[/green] tests-then-deploy")
 
+    # Secrets API
+    if not product or product == "secrets":
+        secrets = tree.add("[bold yellow]secrets[/bold yellow] - BeyondTrust Secrets API")
+        secrets.add("[green]auth[/green] test|status")
+        secrets.add("[green]folders[/green] list|get|create|delete")
+        secrets.add("[green]static[/green] list|get|create|update|delete")
+        secrets.add("[green]dynamic[/green] list|get|generate|create|delete")
+        secrets.add("[green]leases[/green] list|get|revoke")
+        secrets.add("[green]integrations[/green] list|get|create|update|delete")
+
     # Quick
     if not product or product == "quick":
         quick = tree.add("[bold yellow]quick[/bold yellow] - Cross-product workflows")
@@ -591,6 +612,31 @@ def _get_all_commands() -> list[tuple[str, str]]:
         ("bt epml rbp tests tests delete", "Delete a test"),
         ("bt epml rbp tests run", "Run a test suite, exit non-zero on failure"),
         ("bt epml quick tests-then-deploy", "Run tests, commit or rollback the open RBP transaction"),
+        # Secrets API
+        ("bt secrets auth test", "Test BeyondTrust Secrets API connection"),
+        ("bt secrets auth status", "Show Secrets API configuration status"),
+        ("bt secrets folders list", "List folders (server-side filter)"),
+        ("bt secrets folders get", "Get folder metadata"),
+        ("bt secrets folders create", "Create a folder"),
+        ("bt secrets folders delete", "Delete a folder"),
+        ("bt secrets static list", "List static secrets"),
+        ("bt secrets static get", "Get a static secret value"),
+        ("bt secrets static create", "Create a static secret"),
+        ("bt secrets static update", "Update a static secret (bumps version)"),
+        ("bt secrets static delete", "Delete a static secret"),
+        ("bt secrets dynamic list", "List dynamic-secret configs"),
+        ("bt secrets dynamic get", "Get a dynamic-secret config"),
+        ("bt secrets dynamic generate", "Mint a fresh dynamic credential (e.g. AWS STS)"),
+        ("bt secrets dynamic create", "Create a dynamic-secret config"),
+        ("bt secrets dynamic delete", "Delete a dynamic-secret config"),
+        ("bt secrets leases list", "List active leases for a dynamic secret"),
+        ("bt secrets leases get", "Get lease details by id"),
+        ("bt secrets leases revoke", "Revoke a lease (scope-gated; lab returns 403)"),
+        ("bt secrets integrations list", "List integrations"),
+        ("bt secrets integrations get", "Get an integration"),
+        ("bt secrets integrations create", "Create an integration"),
+        ("bt secrets integrations update", "Update an integration (PUT or --partial PATCH)"),
+        ("bt secrets integrations delete", "Delete an integration"),
         # Quick
         ("bt quick pasm-onboard", "Onboard host to PWS + PRA (Total PASM)"),
         ("bt quick pasm-offboard", "Offboard host from PWS + PRA"),
@@ -817,6 +863,11 @@ def whoami(
     if epml_result:
         results.append(epml_result)
 
+    # Test Secrets API
+    secrets_result = _test_secrets_connection()
+    if secrets_result:
+        results.append(secrets_result)
+
     if not results:
         console.print("[yellow]No products configured.[/yellow]")
         console.print("\nTo configure products, set environment variables or run:")
@@ -1024,6 +1075,39 @@ def _test_epml_connection() -> Optional[dict]:
         }
 
 
+def _test_secrets_connection() -> Optional[dict]:
+    """Test BeyondTrust Secrets API connection and return status."""
+    try:
+        from .core.config import load_secrets_config
+        from .secrets.client import get_client
+
+        config = load_secrets_config()
+        masked_pat = config.pat[:12] + "..." if len(config.pat) > 12 else "***"
+        result = {
+            "product": "Secrets API",
+            "url": f"{config.api_url}/site/{config.site_id}/secrets",
+            "auth_method": f"PAT ({masked_pat})",
+            "connected": False,
+        }
+
+        with get_client() as client:
+            folders = client.list_folders()
+            result["connected"] = True
+            result["user_info"] = f"site {config.site_id[:8]}…, {len(folders)} root folder(s)"
+
+        return result
+    except ValueError:
+        return None
+    except Exception as e:
+        return {
+            "product": "Secrets API",
+            "url": "",
+            "auth_method": "-",
+            "connected": False,
+            "error": str(e)[:50],
+        }
+
+
 def run() -> None:
     """Run the CLI application."""
     app()

{bt_cli-0.4.45 → bt_cli-0.4.47}/src/bt_cli/core/config.py

@@ -116,6 +116,35 @@ class EPMWConfig(ProductConfig):
             )
 
 
+@dataclass
+class SecretsConfig(ProductConfig):
+    """BeyondTrust Secrets API configuration.
+
+    Uses Personal Access Token (PAT) bearer authentication against the
+    BeyondTrust public API gateway. URLs are composed as:
+
+        {api_url}/site/{site_id}/secrets/<path>
+
+    The `api_version` is sent as the `bt-secrets-api-version` header on
+    every request. The live API version differs from the public doc page
+    (which lists 2026-01-02 — that gets rejected); the default below is
+    what the server currently accepts.
+    """
+
+    site_id: str = ""
+    pat: str = ""
+    api_version: str = "2026-02-16"
+
+    def validate(self) -> None:
+        """Validate configuration."""
+        if not self.api_url:
+            raise ValueError("BT_SECRETS_API_URL is required")
+        if not self.site_id:
+            raise ValueError("BT_SECRETS_SITE_ID is required")
+        if not self.pat:
+            raise ValueError("BT_SECRETS_PAT is required")
+
+
 @dataclass
 class EPMLConfig(ProductConfig):
     """EPM Linux configuration.
@@ -448,11 +477,49 @@ def load_epml_config(env_file: Optional[str] = None, profile: Optional[str] = No
     return config
 
 
+def load_secrets_config(env_file: Optional[str] = None, profile: Optional[str] = None) -> SecretsConfig:
+    """Load BeyondTrust Secrets API configuration.
+
+    Configuration sources (in order of precedence):
+        1. Environment variables
+        2. Config file (~/.bt-cli/config.yaml)
+
+    Environment variables:
+        BT_SECRETS_API_URL      - Gateway URL (default: https://api.beyondtrust.io)
+        BT_SECRETS_SITE_ID      - Site UUID (required)
+        BT_SECRETS_PAT          - Personal Access Token (required)
+        BT_SECRETS_API_VERSION  - API version header (default: 2026-02-16)
+        BT_SECRETS_VERIFY_SSL   - SSL verification (default: true)
+        BT_SECRETS_TIMEOUT      - Request timeout in seconds (default: 30)
+    """
+    if env_file:
+        load_dotenv(env_file)
+    else:
+        load_dotenv()
+
+    profile = profile or _get_profile()
+    layered = get_layered_config("secrets", profile)
+
+    if "pat" in layered:
+        layered["pat"] = _resolve_value(layered["pat"])
+
+    config = SecretsConfig(
+        api_url=layered.get("api_url") or os.getenv("BT_SECRETS_API_URL", "https://api.beyondtrust.io"),
+        site_id=layered.get("site_id") or os.getenv("BT_SECRETS_SITE_ID", ""),
+        pat=layered.get("pat") or os.getenv("BT_SECRETS_PAT", ""),
+        api_version=layered.get("api_version") or os.getenv("BT_SECRETS_API_VERSION", "2026-02-16"),
+        verify_ssl=_to_bool(layered.get("verify_ssl")) if "verify_ssl" in layered else _get_bool(os.getenv("BT_SECRETS_VERIFY_SSL")),
+        timeout=_to_float(layered.get("timeout")) if "timeout" in layered else _get_float(os.getenv("BT_SECRETS_TIMEOUT"), 30.0),
+    )
+    config.validate()
+    return config
+
+
 def load_config(product: str, env_file: Optional[str] = None) -> ProductConfig:
     """Load configuration for a specific product.
 
     Args:
-        product: Product name ('pws', 'entitle', 'pra', 'epmw')
+        product: Product name ('pws', 'entitle', 'pra', 'epmw', 'epml', 'secrets')
         env_file: Optional path to .env file
 
     Returns:
@@ -467,6 +534,7 @@ def load_config(product: str, env_file: Optional[str] = None) -> ProductConfig:
         "pra": load_pra_config,
         "epmw": load_epmw_config,
         "epml": load_epml_config,
+        "secrets": load_secrets_config,
     }
 
     loader = loaders.get(product.lower())

{bt_cli-0.4.45 → bt_cli-0.4.47}/src/bt_cli/core/config_file.py

@@ -95,6 +95,33 @@ PRODUCTS = {
             "timeout": {"prompt": "Timeout (seconds)", "required": False, "secret": False, "default": 30},
         },
     },
+    "secrets": {
+        "name": "BeyondTrust Secrets API",
+        "fields": {
+            "api_url": {
+                "prompt": "Gateway URL",
+                "required": True,
+                "secret": False,
+                "default": "https://api.beyondtrust.io",
+                "example": "https://api.beyondtrust.io",
+            },
+            "site_id": {
+                "prompt": "Site ID (UUID)",
+                "required": True,
+                "secret": False,
+                "example": "7f735e1b-5ecb-49fa-87e8-eddf54a9c745",
+            },
+            "pat": {"prompt": "Personal Access Token", "required": True, "secret": True},
+            "api_version": {
+                "prompt": "API version (bt-secrets-api-version header)",
+                "required": False,
+                "secret": False,
+                "default": "2026-02-16",
+            },
+            "verify_ssl": {"prompt": "Verify SSL", "required": False, "secret": False, "default": True},
+            "timeout": {"prompt": "Timeout (seconds)", "required": False, "secret": False, "default": 30},
+        },
+    },
     "epml": {
         "name": "EPM Linux",
         "fields": {
@@ -328,6 +355,7 @@ def _get_env_prefix(product: str) -> str:
         "pra": "BT_PRA",
         "epmw": "BT_EPM",
         "epml": "BT_EPML",
+        "secrets": "BT_SECRETS",
     }
     return prefixes.get(product, f"BT_{product.upper()}")
 
@@ -359,6 +387,13 @@ def _get_env_mappings(product: str) -> dict[str, str]:
         # EPM-L doesn't use api_key/client_id/client_secret — drop the inherited mappings
         for unused in ("api_key", "client_id", "client_secret"):
             mappings.pop(unused, None)
+    elif product == "secrets":
+        mappings["site_id"] = f"{prefix}_SITE_ID"
+        mappings["pat"] = f"{prefix}_PAT"
+        mappings["api_version"] = f"{prefix}_API_VERSION"
+        # Secrets API doesn't use api_key/client_id/client_secret — drop the inherited mappings
+        for unused in ("api_key", "client_id", "client_secret"):
+            mappings.pop(unused, None)
 
     return mappings
 

bt_cli-0.4.47/src/bt_cli/data/skills/secrets/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: secrets
+description: BeyondTrust Secrets API commands — folders, static secrets, dynamic AWS credentials, leases, integrations. Use when minting STS credentials, managing secret folders/values, or browsing/revoking dynamic-credential leases.
+---
+
+# Secrets API Commands (`bt secrets`)
+
+Direct CLI for the BeyondTrust Secrets API. PAT-bearer auth, same gateway as
+EPM-L (`api.beyondtrust.io`). **Not** a wrapper around Entitle.
+
+## IMPORTANT: Destructive Operations
+
+**ALWAYS confirm with the user before:**
+- `bt secrets folders delete --recursive` — wipes the folder and all contents
+- `bt secrets folders delete --permanent` — bypasses soft-delete
+- `bt secrets static delete` / `dynamic delete` — removes the secret/config
+- `bt secrets integrations delete` — disables downstream dynamic generation
+
+List affected resources first, then ask for explicit confirmation. Every
+delete supports `--force` to skip the prompt — only use it when the user has
+already confirmed.
+
+## IMPORTANT: Generate Sparingly
+
+`bt secrets dynamic generate <path>` mints **real** AWS STS credentials and
+shows up in the audit trail. Don't loop it during development. For exploring,
+use `dynamic list` / `dynamic get` / `leases list` — those don't mint.
+
+## Configuration
+
+Set these before running commands. PAT comes from `app.beyondtrust.io`.
+
+```bash
+export BT_SECRETS_API_URL=https://api.beyondtrust.io    # default
+export BT_SECRETS_SITE_ID=<site-uuid>                   # required
+export BT_SECRETS_PAT=PAT_xxx                           # required
+export BT_SECRETS_API_VERSION=2026-02-16                # default; doc page is stale
+```
+
+```bash
+bt secrets auth test    # verifies PAT + site + version-header reach the API
+bt secrets auth status  # env-var view (no network)
+```
+
+## Path Semantics
+
+Every item lives at a "path" like `lab/aws/cloudwatch-readonly`. The CLI
+auto-splits the trailing segment as the `name` and the rest as the parent
+`folder`, so users (and you) pass single paths everywhere. The folder may be
+empty for top-level items.
+
+```bash
+bt secrets dynamic get lab/aws/cloudwatch-readonly  # folder=lab/aws, name=cloudwatch-readonly
+bt secrets folders get lab/aws                      # folder=lab, name=aws
+```
+
+## Folders
+
+`list` is **recursive by default** (mirrors how users browse the UI tree).
+Pass `--shallow` / `-S` for direct children only.
+
+```bash
+bt secrets folders list                  # all folders, anywhere in the site
+bt secrets folders list -p lab           # everything under lab/ recursively
+bt secrets folders list -p lab --shallow # only direct children of lab/
+bt secrets folders get lab/aws           # metadata
+bt secrets folders create lab/aws/staging
+bt secrets folders delete lab/aws/staging
+bt secrets folders delete lab/aws/staging --recursive --force   # nuke contents
+```
+
+## Static Secrets
+
+Versioned key/value secrets. The body is a JSON object — pass it inline via
+`--data` or from disk via `--data-file`.
+
+```bash
+bt secrets static list                   # everything in the site (recursive default)
+bt secrets static list -p lab            # everything under lab/
+bt secrets static list -p lab --shallow  # direct children of lab/ only
+bt secrets static get lab/db-pass        # default JSON output (values are structured)
+bt secrets static get lab/db-pass --version 2   # specific historical version
+bt secrets static create lab/db-pass -d '{"password":"hunter2","username":"admin"}'
+bt secrets static update lab/db-pass -d '{"password":"newpass"}'   # bumps version, returns 204
+bt secrets static delete lab/db-pass --force
+```
+
+## Dynamic Secrets
+
+Configurations that mint short-lived credentials on demand (AWS STS today).
+
+```bash
+bt secrets dynamic list                   # all dynamic-secret configs in the site
+bt secrets dynamic list -p lab            # everything under lab/
+bt secrets dynamic list -p lab --shallow  # only items directly at lab/ (usually none — they nest)
+bt secrets dynamic get lab/aws/ec2-readonly
+
+# Mint fresh credentials — default prints shell `export AWS_*` lines.
+bt secrets dynamic generate lab/aws/ec2-readonly
+eval $(bt secrets dynamic generate lab/aws/ec2-readonly)   # one-liner load into shell
+aws sts get-caller-identity                                # verify
+
+# Other formats:
+bt secrets dynamic generate lab/aws/ec2-readonly --format json    # full payload w/ leaseId
+bt secrets dynamic generate lab/aws/ec2-readonly --format env     # KEY=value (no `export`)
+bt secrets dynamic generate lab/aws/ec2-readonly --format dotenv  # KEY="value" for .env files
+```
+
+Create dynamic-secret config (AWS example):
+
+```bash
+bt secrets dynamic create lab/aws/my-new-role -d '{
+  "type":"aws",
+  "integrationName":"AWS-Green-SE-Lab",
+  "credentialType":"assumed_role",
+  "roleArn":"arn:aws:iam::614212341445:role/beyondtrust/my-role",
+  "ttl":900
+}'
+```
+
+## Leases
+
+Each `generate` call creates a lease. Leases auto-expire at TTL; the
+`revoke` endpoint is **scope-gated** and most lab PATs return 403 — that's
+not a generic error, it's the expected "you can't revoke" signal.
+
+```bash
+bt secrets leases list lab/aws/ec2-readonly
+bt secrets leases get <lease-uuid>         # rich detail: externalEntityId (assumed-role ARN), etc.
+bt secrets leases revoke <lease-uuid>      # exit 3 + warning if PAT lacks the revoke scope
+```
+
+## Integrations
+
+External-system connections (currently AWS). Required before a dynamic-secret
+config can reference an `integrationName`.
+
+```bash
+bt secrets integrations list
+bt secrets integrations list -t aws
+bt secrets integrations get my-aws
+bt secrets integrations create my-aws -d '{
+  "type":"aws",
+  "roleArn":"arn:aws:iam::123456789012:role/MyRole",
+  "externalId":"ext-id"
+}'
+bt secrets integrations update my-aws -d '{...}'           # PUT (full replace)
+bt secrets integrations update my-aws --partial -d '{...}' # PATCH (partial)
+bt secrets integrations delete my-aws --force
+```
+
+## API Quirks (Gotchas)
+
+- **Dynamic path is `/dynamic`, NOT `/dynamic-secrets`** — the static doc
+  page hasn't caught up to the live API. The client handles this; never
+  hand-hack URLs.
+- **API version**: header value is `bt-secrets-api-version: 2026-02-16`. The
+  doc says `2026-01-02` and the server rejects it.
+- **POST `/dynamic/{name}/generate` returns 201**, not 200. The client
+  accepts both via `raise_for_status` semantics.
+- **`/leases/revoke` is scope-gated** — `bt secrets leases revoke` exits 3
+  with a clean warning when the server returns 403. TTL still expires the
+  lease eventually.
+- **Rate limit**: 500/window. The client retries 429 once, honoring
+  `x-ratelimit-reset` (clamped to ≤ 30s so a bogus header can't park the
+  CLI).
+- **PAT redaction**: errors and logs route through `bt_cli.core.errors` which
+  scrubs `Authorization` headers and bearer tokens before display. Never
+  add a `print(client.pat)` to debug — the PAT must never echo back.
+
+## Output Formats
+
+- All `list` commands default to rich tables; pass `-o json` for scripting.
+- `get` commands default to JSON since values are structured.
+- `dynamic generate` defaults to `export` shell lines — designed for
+  `eval $(...)`.
+
+## Common Workflows
+
+### Mint creds, run an AWS command, let TTL revoke
+
+```bash
+eval $(bt secrets dynamic generate lab/aws/ec2-readonly)
+aws ec2 describe-instances --max-results 5
+# (don't bother revoking — TTL handles it)
+```
+
+### Audit who currently has access via a dynamic config
+
+```bash
+bt secrets leases list lab/aws/full-admin -o json \
+  | jq -r '.[] | "\(.leaseId) \(.expiration) \(.externalEntityId)"'
+```
+
+### Browse the tree
+
+```bash
+bt secrets folders list -p lab
+bt secrets static  list -p lab
+bt secrets dynamic list -p lab
+```
+
+`list` is recursive by default; the API otherwise only returns items
+directly at the requested path (this trips up newcomers — passing
+`-p lab` returns 0 in shallow mode because the items live in `lab/aws`).
+
+## API Notes
+
+- Base URL: `https://api.beyondtrust.io/site/<site-id>/secrets`
+- Auth: `Authorization: Bearer <PAT>`
+- Version header: `bt-secrets-api-version: 2026-02-16`
+- Rate limit: 500/window — respect `x-ratelimit-reset` on 429.

bt_cli-0.4.47/src/bt_cli/secrets/__init__.py

@@ -0,0 +1 @@
+"""BeyondTrust Secrets API module."""