Skip to main content

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
Workload Credentials (WLC) bt wlc Formerly the Secrets API — folders, static secrets, dynamic AWS/Azure credentials, leases, effective-access reports (bt secrets = deprecated alias)
Identity Security Insights bt insights Recommendations and detections, entities, identities, privileged access paths, posture summary, exports, finding status
Pathfinder bt pf Platform — whoami, sites, site/product access, tokens, users, workload identities, Cedar IAM policies

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.

Identity Security Insights

PAT-bearer auth, like WLC. Any PAT minted on the site that hosts Insights works: a PAT belongs to a site, not a product, so the WLC PAT for the same site can be reused. The tenant id is the site id.

export BT_INSIGHTS_API_URL=https://api.beyondtrust.io   # default
export BT_INSIGHTS_SITE_ID=<site-uuid>                  # required
export BT_INSIGHTS_PAT=PAT_xxx                          # required

The API allows 120 requests per user per tenant, refilled at 1 per second, shared by all your tokens (the Insights MCP server included). Lists are bounded (--limit, default 25); --all says how many requests a long walk takes and asks first. A 403 on everything means the tenant is on Embedded Insights, which has no public API.

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 insights auth test # Test Identity Security Insights 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

Identity Security Insights (bt insights)

bt insights summary                                   # open findings, inventory, risky paths, top providers

# Findings (recs = recommendations, dets = detections)
bt insights recs list                                 # open + in progress, highest privilege first
bt insights recs list -d <definition-id> -s resolved  # one kind of finding, one status
bt insights recs get <id>                             # evidence and remediation
bt insights recs defs list --min-severity 8           # the global catalogue
bt insights recs impacted --search "access key"       # who is affected, with instance IDs
bt insights dets list
bt insights dets defs list --mitre-tactic TA0001

# Inventory
bt insights entities list --provider aws --min-privilege 9
bt insights entities list --classification nhi
bt insights entities get <id> --related               # identities, findings, paths from/to
bt insights identities get <id> --related
bt insights paths list --privilege-escalation --names
bt insights paths get <id> --names                    # the path drawn as a chain or tree

# Exports: every list takes --out (.jsonl, .csv or .json), streamed page by page
bt insights entities list --all --out entities.jsonl  # resumable with --page-token

Set a finding's status (recorded in its history under your name). It reads each finding first, skips the ones already set, asks, writes, and reads each one back:

bt insights recs set-status <id> -s in_progress
bt insights recs set-status <id> -s resolved -c "Rotated the key"     # --comment required to close
bt insights recs list -d <def-id> --all -o json | \
    bt insights recs set-status -F - -s expected -c "Break-glass" --dry-run

Lists can take a minute or more to show a new status; get shows it at once.

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.

Metadata

Release files for bt-cli 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bt-cli 0.7.0
File Size Uploaded Provenance Actions
bt_cli-0.7.0.tar.gz 1.0 MB With provenance Details for bt_cli-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bt-cli 0.7.0
File Interpreter ABI Platform Actions
bt_cli-0.7.0-py3-none-any.whl Python 3 none any Details for bt_cli-0.7.0-py3-none-any.whl

Total release size: 1.6 MB

Release files / bt_cli-0.7.0.tar.gz

Download URL bt_cli-0.7.0.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums
e2a57e445fee962dd4e53f8c1d74413696042d69cb543eb3cca2e4da91838a70
BLAKE2b-256 checksum
How to use checksums
1ef64ccec6ca9c6edcee2212def6b46e9308f74573f43eb7b4d3cea5a907a682
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / bt_cli-0.7.0-py3-none-any.whl

Download URL bt_cli-0.7.0-py3-none-any.whl
Size 572.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e6099b5d3c01731fd17ae41a9a264a7d1f16f1715cfd19f9365819982f10e03
BLAKE2b-256 checksum
How to use checksums
1c6eca802e0422a58d694bfe9fb93659ccd73cf63df5dcf871b214c380e774a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for bt-cli 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for bt_cli-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.7.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page