bt CLI guide

Overview

The bt command-line interface (CLI) lets you use BeyondTrust Privileged Remote Access (PRA) features from a terminal. You type short commands instead of clicking through the Access console. With bt, you can do the following:

• Start Jump sessions. Open SSH, RDP, database, Kubernetes, and port tunnel sessions to Jump Items.
• Manage active sessions. List, inspect, and close the sessions you have open.
• Find Jump Items. See which Jump Items you can reach and which ones are online.
• Work with vault credentials. Get, check out, and check in credentials. You can also run a command with credentials added to its environment, so you never type or paste a password.
• Use your own SSH tools. Generate SSH config entries so that standard ssh, scp, and rsync commands create BeyondTrust sessions in the background.

The CLI works with the Access console. It does not replace it. When you run a bt command, the CLI sends the request to the console running on your computer, and the console does the work.

Why it matters

Many administrators and engineers spend most of their day in a terminal. Switching to a console to start a session or look up a password slows them down. The bt CLI keeps that work in one place.

The CLI also makes automation safer and easier:

• Scripts behave predictably. The CLI returns standard exit codes and passes along exit codes from tools like ssh and psql. Scripts that use set -e or && work as expected.
• Credentials stay protected. bt vault run adds credentials to a command's environment and checks them back in when the command finishes. Secrets do not appear in your shell history or scripts.
• The CLI blocks risky mistakes. It refuses to print a private key unless you ask for it by name. It also rejects requests that do not match the account type, such as asking for a password on an SSH key account.
• Every session goes through BeyondTrust. Even when you use plain ssh, the connection runs as a BeyondTrust session. Your organization keeps the same access controls and session records.

Prerequisites

Before you use the bt CLI, make sure you meet these requirements:

• The Access console is running and you are signed in. The CLI talks to the console on your computer. If the console is not running, bt commands do not work.
• Your account has CLI access. An administrator must turn on the allow_rep_cli permission for your account.
• The bt shim is installed. In the Access console, go to Settings > Global Settings > CLI, and then click Install. The console installs bt to the following locations:
  • macOS and Linux: ~/.sra-con/CLI/bt
  • Windows: %LocalAppData%\BeyondTrust\sra-con\CLI\bt.exe

    ❗

    Important

    The console does not install or update the shim when you log in. After a site upgrade, reinstall it from the console so it matches the upgraded version.

• Optional: Static port permission for SSH config. To use bt ssh-config or bt ssh --proxy, your account also needs the Static port and username for external tool sessions permission (perm_sd_static_port_for_external_tools). These two commands do not work on Windows. On Windows, use bt ssh <item> instead.
• Optional: jq for shell completion. Bash and zsh completion scripts install with the shim. To complete active session numbers, you also need jq.

Quick start

These commands cover the most common tasks:

# Check your connection
bt status

# List the Jump Items you can access
bt items

# Start an SSH session
bt ssh my-prod-server

# Get a password from the vault
bt vault get prod-admin

# Generate SSH config entries, and then connect with plain ssh
bt ssh-config > ~/.ssh/config.d/bt
ssh my-server.bt

Commands

Jump sessions

Jump session commands match your query against a Jump Item's hostname, computer name, or display name. You can use these formats:

If more than one Jump Item matches, the CLI shows a list so you can pick the right one.

bt ssh

bt ssh [user@]<host|name> [--account <account>] [--proxy]

Starts an SSH or Shell Jump session.

The CLI never matches Telnet Shell Jump Items, because they cannot complete an SSH handshake.

bt ssh [email protected]
bt ssh my-prod-server
bt ssh my-prod-server --account prod-admin
bt ssh my-prod-server --proxy

bt rdp

bt rdp [user@]<host|name> [--account <account>]

Starts an RDP Jump session. It uses the same matching rules as bt ssh.

bt rdp admin@win-server-01
bt rdp my-windows-box

bt db

bt db [user@]<host|name> [--account <account>]

Starts a database Jump session. Supported databases include MSSQL, PostgreSQL, MySQL, MongoDB, and Oracle. The username is optional, because the CLI matches database items by hostname or name.

bt db prod-mysql-01
bt db prod-db --account db-admin

bt k8s

bt k8s [user@]<host|name> [--account <account>]

Starts a Kubernetes Jump session.

bt k8s my-cluster

bt pt

bt pt <host|name>

Starts a port tunnel (TCP) session.

bt pt 10.0.0.5

Session management

bt list

bt list [--json]

Lists all active sessions with their session numbers, names, and connection details.

bt list
bt list --json | jq '.[].name'

bt info

bt info <session number> [--json]

Shows details for one session, including tunnel endpoints, listen addresses, and ports.

bt info 1
bt info 1 --json | jq '.tunnels'

bt close

bt close <session number>

Closes an active session. The CLI does not close a session that has an active file transfer.

bt close 1

Discovery

bt items

bt items [ssh|rdp|db|pt|k8s] [--json] [--available]

Lists the Jump Items you can access through the CLI. You can filter the list by type.

By default, the list includes both online and offline items. Add --available to show only items whose Jumpoint is online right now. The list never includes Telnet Shell Jump Items.

bt items                    # All CLI-accessible items
bt items ssh                # SSH items only
bt items --available        # Only items that are online right now
bt items --json             # Machine-readable output
bt items ssh --json | jq '.[].name'

bt status

bt status [--json]

Shows your connection status: the site hostname, the logged-in user, and the number of active sessions. If the Access console is not running, the command stops working with an error.

bt status
bt status --json

Vault

bt vault list

bt vault list [--json]

Lists all vault accounts you can access, with each account's name, username, type, and group.

bt vault list
bt vault list --json | jq '.[] | select(.type == "ssh")'

bt vault get

bt vault get <account-query>[/<attribute>]

Gets one attribute from a vault account.

You can request these attributes: password, username, name, description, id, type, private_key, public_certificate, and secret.

Secret attributes (password, private_key, public_certificate, and secret) trigger a checkout and check in.

If you do not name an attribute, the CLI picks one based on the account type:

SSH CA and x509 CSR accounts refuse every secret attribute, not only the bare form. Each checkout issues a new key and certificate, so separate get calls would return halves of two different pairs. Use bt vault checkout, which writes a matching pair. Non-secret attributes such as username still work.

The CLI refuses key-based requests on purpose. A plain bt vault get <ssh-account> looks like a harmless lookup, but it would print a private key to your screen.

The CLI also checks each attribute against the account type. For example, if you ask for password on an SSH account, the CLI returns an error instead of quietly showing the private key.

bt vault get prod-admin                         # Gets the password (default)
bt vault get prod-admin/username                # Gets the username
bt vault get shared/prod-group/db-admin         # Gets a shared account in a group
bt vault get personal/my-key/private_key        # Gets a personal SSH key (attribute required)

bt vault checkout

bt vault checkout <account-query> [directory]

For SSH, SSH CA and x509 accounts, the CLI writes key files to the folder you name. The folder is required and must already exist.

On macOS and Linux, the CLI sets owner-only permissions on each key file before it writes any key data. On Windows, file permissions are inherited from the target folder.

Key files are named id__

Characters that are not valid in a file name on every platform (/ \ : * ? " < > | and control characters) become _, so username CORP\svc on account 42 is written as id_CORP_svc_42.

bt vault checkout my-ssh-key ~/.ssh/

bt vault checkin

bt vault checkin <account-query>

Checks in credentials you checked out earlier. You cannot check in personal accounts.

bt vault checkin my-ssh-key

bt vault run

bt vault run [-a <account>] [-e VAR=attr]... [env-file] -- <command> [args...]

Runs a command with vault credentials added to its environment.

Put all options before a single --. Everything after -- is the command and its arguments. The CLI passes them exactly as typed and starts the command without a shell, so it does not reprocess quotes, wildcards, or $VAR values.

Account injection (-a)

The -a option adds the account's credentials as BT_* environment variables:

The CLI puts each secret in the variable that matches what it is. For example, it never puts a private key in BT_PASSWORD.

Custom mapping (-e)

The -e option maps an account attribute to an environment variable name you choose. You can repeat it, and it requires -a. Every mapping must succeed. The CLI stops with an error if a mapping uses an attribute that does not fit the account type (such as -e X=password on an SSH account), an unknown attribute, an empty value, or a duplicate variable name.

# Add credentials as BT_* variables
bt vault run -a prod-admin -- psql -h mydb

# Map attributes to custom variable names
bt vault run -a prod-admin -e PGPASSWORD=password -e PGUSER=username -- psql -h mydb

# Use an env file with bt-vault:// URIs
echo 'DB_PASS=bt-vault://shared/prod/dbadmin/password' > .env
bt vault run .env -- psql -h mydb

# Resolve bt-vault:// URIs already exported in your shell
export DB_PASS=bt-vault://shared/prod/dbadmin/password
bt vault run -- mycommand

# Combine account injection with an env file
bt vault run -a prod-admin .env -- mycommand

The CLI always scans your environment for bt-vault:// values, so the second-to-last example doesn't need -a. The CLI checks out each referenced account once, and then checks it back in once after it resolves every variable that uses that account.

Account query syntax

Vault commands accept these account query formats:

SSH config integration

Requirements: SSH config integration needs the Static port and username for external tool sessions permission (perm_sd_static_port_for_external_tools). It does not work on Windows.

bt ssh-config

bt ssh-config [--filter <text>] [--group <name>]

Generates SSH config Host entries for the SSH Jump Items you can access. The CLI prints the output to your screen, so you can send it to an SSH config file.

Each entry uses ProxyCommand bt ssh --proxy ..., so running ssh <alias> creates a BeyondTrust session in the background.

# Preview the output
bt ssh-config

# Write to a separate config file (recommended)
bt ssh-config > ~/.ssh/config.d/bt
# Then add this line to ~/.ssh/config: Include config.d/*

# Narrow the output
bt ssh-config --filter prod --group "My Group"

# Or add the entries directly to your main config
bt ssh-config >> ~/.ssh/config

Generated format

# Generated by bt ssh-config
# Re-run 'bt ssh-config' to regenerate after jump item changes.

# Jump item: My Production Server
Host my-production-server.bt
    ProxyCommand bt ssh --proxy admin@my-production-server
    StrictHostKeyChecking ask

The CLI still includes offline items and marks them with a # (currently offline) comment. You keep the config file for a long time, and the item's Jumpoint might be online when you use it.

StrictHostKeyChecking ask prompts you the first time you connect, instead of quietly trusting a new host key. Because each entry has no HostName, the known_hosts file stores keys under the stable alias for each Jump Item, not under a temporary local port.

Alias names

The CLI builds each alias from the Jump Item name. It changes the name to lowercase, adds .bt to the end, and replaces any character that is unsafe for the shell or meaningful to ssh_config with a dash. For example, "My Prod Server" becomes my-prod-server.bt.

Replacing these characters prevents real problems:

• ssh_config reads Host lines as patterns and uses the first match.
• A * or ? in an alias could match and take over other aliases.
• A , splits one Host line into several patterns.
• A # starts a comment, and = acts as a separator.

The CLI targets items by Jump Item name. If two items share a name, the CLI adds the username to the alias, such as admin-my-prod-server.bt. If it still can't tell items apart, or if an item contains characters that would break the config format, the CLI skips the item and lists it in a comment at the end of the output.

After you generate the config, you can use standard SSH tools:

ssh my-prod-server.bt                        # Creates a session in the background
scp file.txt my-prod-server.bt:              # Works with scp
rsync -avz ./dir my-prod-server.bt:/path/    # Works with rsync

The CLI creates the session when the SSH connection starts and closes it when the connection ends.

bt ssh --proxy

The --proxy option puts bt ssh into stdio proxy mode. Instead of opening an SSH client, it connects your standard input and output to the SSH tunnel. SSH uses this mode as a ProxyCommand. You do not run it directly.

The session lasts only while the proxy process runs. When SSH disconnects, the proxy exits and the session closes. If you press Ctrl+C, the CLI restores your terminal and closes the session, even if the session is still waiting for approval.

Help

bt --help

bt --help
bt -h

Shows a summary of all commands.

bt <command> --help

Shows help for a specific command. This works for every command.

bt ssh --help
bt vault --help      # Shows subcommands and account query examples
bt items --help

Output formats

Most commands support --json, which returns output that scripts can read:

bt items --json | jq '.[] | select(.type == "ssh") | .name'
bt list --json | jq '.[].number'
bt status --json | jq '.activeSessions'
bt vault list --json | jq '.[] | select(.personal == true)'
bt info 1 --json | jq '.tunnels[0].listenPort'

By default, the CLI shows human-readable output. JSON output is always a valid JSON array or object.

Shell completion

When you install the CLI from the console, it also installs bash and zsh completion scripts in the same folder as bt. You do not need to copy them. You only need to point your shell to them.

Bash

source ~/.sra-con/CLI/bt.bash
# Or copy the file to /etc/bash_completion.d/bt

Zsh

# The script installs as _bt, not bt.zsh. Zsh loads a #compdef
# script by file name, so any other name does nothing.
fpath=(~/.sra-con/CLI $fpath)        # Add to .zshrc, before compinit
autoload -Uz compinit && compinit

To regenerate the scripts or install them somewhere else, print them from the CLI. This works even when the console is not running:

bt --completions bash > /etc/bash_completion.d/bt
bt --completions zsh  > ~/.zsh/completions/_bt

Completion covers subcommands, type filters, options, and active session numbers for close and info. Session number completion uses bt list --json | jq. If jq isn't installed, completion covers options only.

Exit codes

The CLI passes along exit codes from child processes like ssh and psql. This keeps set -e scripts and && chains working correctly.

Troubleshooting