BT-CLI

Unofficial BeyondTrust Platform CLI - manage privileged access across your environment from a single command line.

Supported Products

Installation

pip install bt-cli
bt version

Configuration

Set environment variables for each product you want to use. You only need to configure the products you'll use.

Password Safe

# Option 1: OAuth (recommended)
export BT_PWS_API_URL=https://your-server/BeyondTrust/api/public/v3
export BT_PWS_CLIENT_ID=your-client-id
export BT_PWS_CLIENT_SECRET=your-client-secret

# Option 2: API Key
export BT_PWS_API_URL=https://your-server/BeyondTrust/api/public/v3
export BT_PWS_API_KEY=your-api-key

Entitle

export BT_ENTITLE_API_URL=https://api.us.entitle.io
export BT_ENTITLE_API_KEY=your-api-key

PRA (Privileged Remote Access)

export BT_PRA_API_URL=https://your-site.beyondtrustcloud.com
export BT_PRA_CLIENT_ID=your-client-id
export BT_PRA_CLIENT_SECRET=your-client-secret

EPM Windows

export BT_EPM_API_URL=https://your-site-services.epm.bt3ng.com
export BT_EPM_CLIENT_ID=your-client-id
export BT_EPM_CLIENT_SECRET=your-client-secret

Workload Credentials (WLC) — formerly Secrets API

PAT-bearer auth against the BeyondTrust public API gateway. Mint a PAT at app.beyondtrust.io on the site that hosts WLC (PATs are site-bound).

export BT_WLC_API_URL=https://api.beyondtrust.io      # default
export BT_WLC_SITE_ID=<wlc-site-uuid>                 # required
export BT_WLC_PAT=PAT_xxx                             # required
export BT_WLC_API_VERSION=2026-04-28                  # default (doc page is stale)

The old BT_SECRETS_* variables (and the secrets profile section) still work as a fallback; BT_WLC_* wins when both are set. bt secrets ... is a deprecated alias of bt wlc ....

Common commands:

bt wlc tree                                    # folders, static, dynamic, integrations (names only)
bt wlc folders list -p lab                     # recursive by default
bt wlc dynamic list -p lab                     # all dynamic-secret configs under lab/
bt wlc dynamic generate lab/aws/ec2-readonly   # mint shell `export AWS_*` lines
eval $(bt wlc dynamic generate lab/aws/ec2-readonly)  # load into current shell
bt wlc leases list lab/aws/ec2-readonly        # who has active leases
bt wlc static get lab/db/creds                 # read a static secret (prints the value)

bt wlc dynamic generate mints real cloud credentials and is audited — don't loop it. bt wlc leases revoke is scope-gated; most PATs return 403 and exit code 3 with a clean warning. TTL still revokes.

Access control: workload identities and IAM policies

Who may do what inside WLC is a set of Cedar policies in the Pathfinder IAM policy service; CI jobs, pods and apps authenticate as workload identities. Both live on the Administration site (its id is the org id), so configure pf with a PAT minted there:

export BT_PF_SITE_ID=<org-id>   # Administration site
export BT_PF_PAT=PAT_yyy        # minted on the Administration site

bt pf wi list --wlc                       # workload identities that can use WLC
bt pf wi get <identityId>                 # ...and the policies that grant it access
bt pf policies list                       # live policies (--all includes deleted)
bt pf policies render --name demo-viewer --workload-name k8s-wc-reader \
    --folder /btlab/app/demo --role-grant Viewer          # show the Cedar, no write
bt pf policies grant  --name demo-viewer --workload-name k8s-wc-reader \
    --folder /btlab/app/demo --role-grant Viewer          # confirm, PUT, wait for ACTIVE
bt pf policies delete demo-viewer                         # revoke

bt wlc access who  --path /btlab/app/demo/db-pass         # who can reach this secret
bt wlc access what --workload k8s-wc-reader               # what this workload can reach
bt wlc access findings                                    # dead principals, stuck policies, ...

Policy PUT is an upsert: reusing a name replaces that policy (grant says so before asking). The service accepts a wrong workload id (ACTIVE, grants nothing) and a missing path (WAITING_FOR_RESOURCE); grant warns about both. Group/role membership isn't visible to PAT callers, so effective access can be more than the policies show.

Using a .env File

Create a .env file and source it before running commands:

source .env
bt pws auth test

Test Your Configuration

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 wlc auth test      # Test Workload Credentials connection
bt pf auth test       # Test Pathfinder platform connection

Command Reference

Password Safe (bt pws)

Systems

bt pws systems list                    # List all managed systems
bt pws systems list -o json            # Output as JSON
bt pws systems get <system-id>         # Get system details
bt pws systems create -n "name" -i "10.0.1.50" -w <workgroup-id> -p <platform-id>
bt pws systems delete <system-id>

Accounts

bt pws accounts list                   # List all managed accounts
bt pws accounts list -s <system-id>    # List accounts for a system
bt pws accounts get <account-id>       # Get account details

Credentials (Checkout/Checkin)

bt pws credentials request <system> <account>     # Request credential checkout
bt pws credentials show <request-id>              # Show checked-out password
bt pws credentials checkin <request-id>           # Check in credential

Secrets Safe

bt pws secrets safes list              # List safes
bt pws secrets folders list <safe>     # List folders in a safe
bt pws secrets list <safe> <folder>    # List secrets
bt pws secrets get <safe> <folder> <title>        # Get secret value
bt pws secrets create <safe> <folder> <title> <value>

Quick Commands (Workflows)

# Checkout a credential (combines request + show)
bt pws quick checkout -s "system-name" -a "account-name"
bt pws quick checkout -s "system-name" -a "account-name" --raw  # Password only

# Onboard a new system with account
bt pws quick onboard -n "hostname" -i "10.0.1.50" -w <workgroup-id> -f <functional-account-id>

# Offboard (remove system and accounts)
bt pws quick offboard -s "system-name"

Other Commands

bt pws workgroups list                 # List workgroups
bt pws platforms list                  # List platforms
bt pws functional list                 # List functional accounts

Entitle (bt entitle)

Integrations

bt entitle integrations list           # List all integrations
bt entitle integrations get <id>       # Get integration details

Resources

bt entitle resources list              # List all resources
bt entitle resources list -s "search"  # Search resources
bt entitle resources get <id>          # Get resource details

Bundles

bt entitle bundles list                # List access bundles
bt entitle bundles get <id>            # Get bundle details

Workflows

bt entitle workflows list              # List approval workflows
bt entitle workflows get <id>          # Get workflow details

Permissions

bt entitle permissions list            # List all permissions
bt entitle permissions list -u <user>  # List user's permissions
bt entitle permissions revoke <id>     # Revoke a permission

Users

bt entitle users list                  # List users
bt entitle users get <id>              # Get user details

PRA (bt pra)

Jump Items - Shell (SSH)

bt pra jump-items shell list           # List SSH jump items
bt pra jump-items shell get <id>       # Get jump item details
bt pra jump-items shell create -n "name" -h "hostname" -j <jumpoint-id> -g <jump-group-id>
bt pra jump-items shell delete <id>

Jump Items - RDP

bt pra jump-items rdp list             # List RDP jump items
bt pra jump-items rdp create -n "name" -h "hostname" -j <jumpoint-id> -g <jump-group-id>

Vault Accounts

bt pra vault list                      # List vault accounts
bt pra vault get <id>                  # Get vault account details
bt pra vault checkout <id>             # Checkout credentials
bt pra vault checkin <id>              # Checkin credentials
bt pra vault rotate <id>               # Rotate password

Jump Groups

bt pra jump-groups list                # List jump groups
bt pra jump-groups get <id>            # Get group details
bt pra jump-groups create -n "name"    # Create jump group

Jumpoints

bt pra jumpoints list                  # List jumpoints
bt pra jumpoints get <id>              # Get jumpoint details

Quick Commands

# Create shell jump with vault account
bt pra quick shell-jump -n "name" -h "host" -j <jumpoint> -g <group> --vault-account <account-id>

EPM Windows (bt epmw)

Computers

bt epmw computers list                 # List managed computers
bt epmw computers list -o json         # Output as JSON
bt epmw computers get <id>             # Get computer details
bt epmw computers archive <id>         # Archive (remove) computer

Groups

bt epmw groups list                    # List computer groups
bt epmw groups get <id>                # Get group details

Policies

bt epmw policies list                  # List policies
bt epmw policies get <id>              # Get policy details
bt epmw policies download <id>         # Download policy XML

Admin Requests

bt epmw requests list                  # List pending requests
bt epmw requests list --status approved
bt epmw requests approve <id>          # Approve request
bt epmw requests deny <id> -r "reason" # Deny request

Events & Audits

bt epmw events list                    # List recent events
bt epmw events list --hours 48         # Events from last 48 hours
bt epmw events search -q "keyword"     # Search events
bt epmw audits list                    # List audit logs

Cross-Product Commands (bt quick)

For environments with both Password Safe and PRA (PASM):

# Onboard system to both PWS and PRA
bt quick pasm-onboard -n "hostname" -i "10.0.1.50" -w <workgroup> -j <jumpoint> -g <jump-group>

# Offboard from both
bt quick pasm-offboard -n "hostname"

# Search across both products
bt quick pasm-search -q "hostname"

Output Formats

All list commands support multiple output formats:

bt pws systems list              # Default table format
bt pws systems list -o json      # JSON output
bt pws systems list -o json | jq # Pipe to jq for processing

Scripting with Raw Output

# Get just the password for scripting
PASSWORD=$(bt pws quick checkout -s "server" -a "admin" --raw)

# Use in SSH
sshpass -p "$PASSWORD" ssh admin@server

Concepts

Password Safe: Functional vs Managed Accounts

Functional accounts are service accounts used BY Password Safe to connect to and manage systems. They perform password rotation, discovery, and other automated tasks.

Managed accounts are the accounts ON systems that Password Safe stores and rotates passwords for. These are what users check out.

# List functional accounts (for system management)
bt pws functional list

# List managed accounts (for checkout)
bt pws accounts list

PRA: Jump Items and Jumpoints

Jumpoints are agents installed in your network that facilitate connections. Jump items are the actual connection definitions (SSH, RDP, etc.) that use jumpoints.

# Find available jumpoints
bt pra jumpoints list

# Create a jump item using a jumpoint
bt pra jump-items shell create -n "my-server" -h "10.0.1.50" -j <jumpoint-id> -g <group-id>

Troubleshooting

Authentication Errors

# Test connectivity
bt pws auth test

# Enable debug output to see API calls
export BT_SHOW_REST=true
bt pws systems list

SSL Certificate Issues

For self-signed certificates (not recommended for production):

export BT_SSL_INSECURE_ALLOW=true

Common Issues

License

MIT License - This is an unofficial tool not affiliated with or supported by BeyondTrust.