bt-cli 0.4.30

BeyondTrust Platform CLI (unofficial) - Password Safe, Entitle, PRA, EPM

BT-CLI

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

Supported Products

Product	Command	Description
Password Safe	bt pws	Credential vaulting, secrets management, password rotation
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

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

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

---

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

Error	Solution
401 Unauthorized	Check credentials in environment variables
403 Forbidden	Verify API user has required permissions
404 Not Found	Check API URL format and resource IDs
Connection refused	Verify URL and network connectivity
EPMW 405 on delete	Use archive instead of delete for computers

---

License

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