DocumentationRelease Notes
Documentation

Password Safe CLI Application

Suggest Edits

What is the Password Safe CLI application?

The Password Safe Command Line Interface (CLI) Application is an efficient tool specifically crafted to interface with the BeyondInsight and Password Safe APIs. This application gives users access to various API resources, including safes, folders, secrets, managed accounts, and more. It offers a user-friendly interface that simplifies command parsing, ensures input validation, and delivers detailed output.

How is it useful?

There are many benefits to using Password Safe CLI, including:

  • Reliable and Efficient Backend Operations - Password Safe CLI utilizes a robust backend logic for API calls, guaranteeing seamless and dependable interaction with BeyondInsight and Password Safe APIs. This allows users to concentrate on their tasks without the burden of navigating the complexities of API integration.
  • Intuitive Command-Line Interface - Crafted with simplicity and usability in mind, the CLI offers a user-friendly framework for executing commands. This design enables users of all experience levels to engage with the tool efficiently.
  • Comprehensive Help and Documentation - Password Safe CLI has detailed help texts for all commands, ensuring that users have access to clear and actionable guidance. These texts are meticulously refined for clarity and effectiveness, making it easier for users to understand and utilize the tool’s features.
  • Clear and Actionable Error Handling - Password Safe CLI delivers meaningful error messages that assist users in quickly identifying and resolving issues. This approach minimizes frustration and downtime, ensuring smooth operation even when unexpected problems arise.
  • Input Validation - Input parameters undergo thorough validation for consistency and correctness, reducing errors and ensuring accurate command execution. Users can rely on the CLI to manage their inputs securely and effectively.

Available environment variables

Required

  • PSCLI_API_URL - BeyondInsight and Password Safe API URL. This can be set in the settings file.
  • PSCLI_CLIENT_ID - Client ID to use when requesting data from the API. This can be set in the settings file.
  • PSCLI_CLIENT_SECRET - Client secret to use when requesting data from the API. This can be set in the settings file.

Optional

  • PSCLI_SETTINGS_PATH - Custom settings path to use for ps-cli. By default, the settings file is created in the user's home directory (~).
  • PSCLI_AUTH_RETRIES - The number of times ps-cli should attempt to authenticate in case of an error.
  • PSCLI_TIMEOUT_CONNECTION - How long to wait for the server to connect and send data before giving up. Integer value defined in seconds, by default 30 seconds.
  • PSCLI_TIMEOUT_REQUEST - How long to wait for each request made to the API. Defined in seconds, by default 30 seconds.

Prerequisites

  • Python 3.12+
  • Password Safe version 24.3

Installation

Using the Python Package Index (PyPI): https://pypi.org/project/beyondtrust-bips-cli/

pip install beyondtrust-bips-cli

Ensure that ps-cli is properly installed:

ps-cli -h
# Output usage instructions
# usage: ps-cli [-h] [-v] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--format {json,csv,tsv}] [--delimiter {,,;,   ,|, }]
#               [-av {3.0,3.1}]
#               {safes,folders,secrets,settings} ...

Configuration

Once ps-cli is properly installed in your system, generate the default pscli-settings.ini using this command:

ps-cli settings initialize-settings

By default, the settings file is created in the user's home directory (~). To specify a custom path for the settings, set the _PSCLI_SETTINGS_PATH _environment variable.

After creating the settings file, edit it and configure api_url, client_id, and client_secret.

Usage

In every service or command, you can request assistance by using the help option (-h). This provides you with detailed information about the command's functionality, as well as its required options and arguments.

The ps-cli offers three distinct output formats: TSV (which is the default), CSV, and JSON. To specify your preferred format, utilize the --format option in the ps-cli command:

ps-cli --format JSON {service} {command} {options}

You can adjust the verbosity level to receive more detailed information about the command being executed. To do this, use the -v option when calling the ps-cli:

ps-cli -v {service} {command} {options}

Available services and commands

To view the most up-to-date list of available services, use ps-cli -h.

To view the most up-to-date list of available commands by service, use ps-cli {service} -h.

Current Services

Address Groups: Address groups management commands

To display the available commands for safes, use:

ps-cli address-groups -h

Output:

get-address-group (get)
                      Returns an Address Group by name or ID.
list-address-groups (list)
                      List the address groups.

Retrieve an address group

To retrieve an address group by its ID and show output in JSON format, use:

ps-cli --format json address-groups get -id <INTEGER ID>

To retrieve an address group by its Name and show output in JSON format, use:

ps-cli --format json address-groups get -n <FULL NAME>

List address groups

To list address groups and show the output in JSON format, use:

ps-cli --format json address-groups list

Safes: Commands for managing safes

To display the available commands for safes, use:

ps-cli safes -h

Output:

create-safe (create)
                    Creates a new Safe.
delete-safe (delete)
                    Deletes a Safe by ID.
get-safe (get)      Returns a safe by ID.
list-safes (list)   Returns all safes to which the current user has access.
update-safe (update)
                    Updates an exiging Safe using its ID.

Create a safe

To create a safe and show output in JSON format, use:

ps-cli --format json safes create -n <SAFE'S NAME> [-d <DESCRIPTION>]

Update a safe

ps-cli safes update -n <NEW SAFE'S NAME> -id <SAFE GUID>

Retrieve a safe

To retrieve a safe using JSON format, use:

ps-cli --format json safes get -id <SAFE GUID>

List safes

To return all safes to which the current user has access and show output in JSON format, use:

ps-cli --format json safes list

Delete a safe

To delete a safe, use:

ps-cli safes delete -id <SAFE GUID>

Folders: Commands for managing folders

To display the available commands for folders, use:

ps-cli folders -h

Create folder

To create a folder, specify a parent folder or a safe location, along with the name of the folder being created, use:

ps-cli folders create -pid <folder or safe GUID> -n <FolderName>

You can view all available options to create secrets by using the help command associated with the create function: ps-cli folders create -h.

List folders

You can retrieve a list of folders and apply filters to customize your results using the following options:

  • -p or --path to filter by path
  • -n or --name to filter by the partial name of the folder
  • -l or --limit to specify the maximum number of results
  • -o or --offset to set the starting point for the results
  • -oi or --owner-id to filter results by the folders which are owned by the given owner ID
  • -ro or --root-only to display the results only including those folders at the root level
ps-cli --format json folders list [-o offset] [-l limit] [-oi owner_id] [-p path] [-n name]

Delete a folder

To delete a folder by ID, use:

ps-cli folders delete -id <FOLDER GUID>

To delete a folder by name, use:

ps-cli folders delete -n <FOLDER Name>

ℹ️

If several folders match the name, then the delete operation cannot be completed.

Secrets: Commands for managing secrets

To display the available commands for secrets, use:

ps-cli secrets -h

Create secret

Based on the options specified in the secrets create command, you can generate a credential, text, or file secret.

You can view all available options for creating secrets by using the help command associated with the create function: ps-cli secrets create -h.

Credential secret

To create a credential secret, you must use --username and --password, among other options, such as --owner-type (-ot) and --owners (-o):

ps-cli secrets create --username <USERNAME> --password <PASSWORD> -t <SECRET TITLE> -fid <FOLDER_GUID> --owner-type <User|Group> --owners <OWNER ID>
Text secret

To create a text secret, you must use the --text option:

ps-cli secrets create --text "<TEXT FOR SECRET>" -t <SECRET TITLE> -fid <FOLDER_GUID> -ot <User|Group> -o <OWNER ID>
File secret

To create a file secret, you must use the --file-path option:

ps-cli secrets create --file-path <PATH TO FILE> -t <SECRET TITLE> -fid <FOLDER_GUID> --owner-type <User|Group> --owners <OWNER ID>

Update a secret

Credential secret

Updating a credential secret is similar to its creation. The main difference is that secret GUID (-sid) must be provided in the command:

ps-cli -v secrets update -sid <SECRET GUID> -fid <FOLDER GUID> -t <SECRET TITLE> --username <USERNAME> --password <PASSWORD> --owner-type <User|Group> --owners <OWNER ID>
List secrets

You can retrieve a list of secrets and apply filters to customize your results using the following options:

  • -t or --title to filter by title
  • -p or --path to filter by path
  • -l or --limit to specify the maximum number of results
  • -o or --offset to set the starting point for the results

For further details, you can use the command ps-cli secrets list -h.

ps-cli secrets list -t <SECRET FULL TITLE>

Get a secret

You can return a secret by ID or title.

To retrieve a secret by GUID, use:

ps-cli secrets get -id <SECRET GUID>

To retrieve a secret by Title, use:

ps-cli secrets get -t <SECRET FULL TITLE>

Delete a secret

To delete a secret, provide the secret GUID (-id):

ps-cli secrets delete -id <SECRET GUID>

Settings: Management commands for PS CLI settings

Refresh settings

Update the .ini file with the latest structure. If a new setting has been added, it is included.

ps-cli settings refresh-settings

Update single setting

The update-setting -s command allows you to update the value of a specific key in a given section of the settings file. If the section does not exist, it is created. If the key does not exist in the section, it is added with the provided value.

ps-cli settings update-setting -s <SECTION> -k <KEY> -v <VALUE>

Assets: Asset management commands.

Assign attribute

To assign an attribute to an asset using the asset ID, use:

ps-cli assets assign-attribute -id <ASSET_ID> -aid <ATTRIBUTE_ID>

To assign an attribute to an asset using the asset name and Workgroup name, use:

ps-cli assets assign-attribute -an <ASSET_NAME> -wgn <WORKGROUP_NAME> -aid <Attribute ID>

To assign an attribute to an asset using the asset name and Workgroup ID, use:

ps-cli assets assign-attribute -an <ASSET_NAME> -wgi <WORKGROUP_ID> -aid <Attribute ID>

Create an asset

To create a new asset in the Workgroup, either WORKGROUP ID or WORKGROUP NAME is required:

ps-cli assets create -ip <IP_ADDRESS> [-os <OPERATING_SYSTEM>] [-d <DESCRIPTION>] [-t <ASSET_TYPE>] [-mac <MAC_ADDRESS>] [-domain <DOMAIN_NAME>] [-dns DNS_NAME] [-n <ASSET_NAME>] [-wgi <WORKGROUP_ID>] [-wgn <WORKGROUP_NAME>]

Delete an asset

To delete an existing asset by Asset ID, use:

ps-cli assets delete-attribute -aid <ATTRIBUTE_ID> -id <ASSET_ID>

To delete an attribute from an asset by Asset Name and Workgroup ID, use:

ps-cli assets delete-attribute -aid <ATTRIBUTE_ID> -wgi <WORKGROUP_ID> -an <ASSET_NAME>

Get an asset by ID

To returns an asset by Asset ID (-id), use:

ps-cli assets get-by-id -id ASSET_ID

Get an asset by its name and Workgroup’s ID or Name

To return an asset by workgroup name or ID (-wgn | -wgi) and asset name (-an), use:

ps-cli assets get-by-wg -an ASSET_NAME [-wgi <WORKGROUP_ID>] [-wgn <WORKGROUP_NAME>]

List assets

To return a list of assets by Workgroup name (-wgn) or ID (-wgi), use:

ps-cli assets list [-wgi <WORKGROUP_ID>] [-wgn <WORKGROUP_NAME>] [-o <OFFSET>] [-l <LIMIT>]

List asset’s attributes

To return a list of assets by Asset ID, use:

ps-cli assets list-attributes -id <ASSET_ID>

To return a list of assets by Asset’s name by Workgroup name (-wgn) or ID (-wgi)), use:

ps-cli assets list-attributes -an ASSET_NAME [-wgi <WORKGROUP_ID>] [-wgn <WORKGROUP_NAME>]

List assets by Smart Rule

To return a list of assets by Smart Rule ID, use:

ps-cli assets list-by-sr -id <SMART_RULE_ID> [-o <OFFSET>] [-l <LIMIT>]

To return a list of assets by Smart Rule title, use:

ps-cli assets list-by-sr -t <TITLE> [-o <OFFSET>] [-l <LIMIT>]

Search assets

Returns a list of assets that match the given search options. At least one search option should be provided; any property not provided is ignored. All search criteria is case insensitive and is an exact match, except for IP Address:

ps-cli assets search [-t <ASSET_TYPE>] [-mac <MAC_ADDRESS>] [-ip <IP_ADDRESS>] [-domain <DOMAIN_NAME>] [-dns <DNS_NAME>] [-n <ASSET_NAME>] [-o <OFFSET>] [-l <LIMIT>]

Update an asset

To update an existing asset by Asset’s ID, use:

ps-cli assets update -id <ASSET_ID> [-os <OPERATING_SYSTEM>] [-d <DESCRIPTION>] [-t <ASSET_TYPE>] [-mac <MAC_ADDRESS>] [-domain <DOMAIN_NAME>] [-dns <DNS_NAME>] [-n <ASSET_NAME>] [-ip <IP_ADDRESS>] [-pn <PREV_ASSET_NAME>] [-wgi <WORKGROUP_ID>] [-wgn <WORKGROUP_NAME>]

ℹ️

To set a new workgroup, use -wgi / -wgn options.

To update an existing asset by Asset’s name and Workgroup's name, use:

ps-cli assets update -n <ASSET_NAME> -pwgn <PREV_WORKGROUP_NAME>> [-os <OPERATING_SYSTEM>] [-d <DESCRIPTION>] [-t <ASSET_TYPE>] [-mac <MAC_ADDRESS>] [-domain <DOMAIN_NAME>] [-dns <DNS_NAME>]  [-ip <IP_ADDRESS>] [-pn <PREV_ASSET_NAME>] [-wgi <WORKGROUP_ID>] [-wgn <WORKGROUP_NAME>] [-pwgi <PREV_WORKGROUP_ID>]

ℹ️

To set a new workgroup, use -wgi or -wgn .

To identify the asset using the workgroup Name, use -pwgn.

To update an existing asset by Asset’s name and Workgroup's ID, use:

ps-cli assets update -n <ASSET_NAME> [-pwgi <PREV_WORKGROUP_ID>] [-os <OPERATING_SYSTEM>] [-d <DESCRIPTION>] [-t <ASSET_TYPE>] [-mac <MAC_ADDRESS>] [-domain <DOMAIN_NAME>] [-dns <DNS_NAME>]  [-ip <IP_ADDRESS>] [-pn <PREV_ASSET_NAME>] [-wgi <WORKGROUP_ID>] [-wgn <WORKGROUP_NAME>]

ℹ️

To set a new workgroup, use -wgi or -wgn .

To identify the asset using the workgroup ID, use -pwgi.

Organizations: Organizations management commands

Retrieve an organization

To retrieve an organization by its ID and show output in JSON format, use:

ps-cli --format json organizations get -id <GUID>

To retrieve an organization by its Name in JSON format, use:

ps-cli --format json organizations get -n <FULL NAME>

List organizations

To return a list of organizations to which the current user has permission and show output in JSON format, use:

ps-cli --format json organizations list

Managed Accounts: Managed Accounts management commands

To display the available commands for Managed Systems, use:

ps-cli managed-accounts -h

Get a Managed Account

To return a managed account by ID, use:

ps-cli --format json managed-accounts get -id <ACCOUNT_ID>

To return a managed accounts as a list by searching by Account and System's name, use:

ps-cli --format json managed-accounts get -sn <SYSTEM_NAME> -an <ACCOUNT_NAME>

List Managed Accounts by Managed System ID

To return a list of managed accounts by managed system ID and show output in JSON format, use:

ps-cli --format json managed-accounts list -id <MANAGED_SYSTEM_ID>

List Managed Accounts by Quick Rule

To list managed accounts by Quick Rule's ID, use:

ps-cli --format json managed-accounts list-by-qr -id <QUICK_RULE_ID>

To list managed accounts by Quick Rule's Title, use:

ps-cli --format json managed-accounts list-by-qr -t <QUICK_RULE_TITLE>

List Managed Accounts by Smart Rule

To list managed accounts by Smart Rule's ID and show output in JSON format, use:

ps-cli --format json managed-accounts list-by-sr -id <SMART_RULE_ID>

To list managed accounts by Smart Rule's Title, use:

ps-cli managed-accounts list-by-sr -t <SMART_RULE_TITLE>

Managed Systems: Managed Systems management commands

To display the available commands for Managed Systems, use:

ps-cli managed-systems -h

Output:

usage: ps-cli managed-systems [-h]
                              {create-managed-system-by-asset,create-managed-system-by-database-id,create-managed-system-by-workgroup,delete-managed-system-by-id,get-managed-system-by-asset,get-managed-system-by-database-id,get-managed-system-by-functional-account-id,get-managed-system-by-id,get-managed-system-by-workgroup-id,list-managed-systems,update-managed-system-by-id}
                              ...
    Works with Secrets Safe Managed Systems - Create, Update, Get, or Delete
    Requires Password Safe Secrets Safe License.
    Requires Password Safe SecretsSafe Read for Get, Read/Write for all others.
options:
  -h, --help            show this help message and exit
subcommands:
  Subcommands available for managed-systems
  {create-managed-system-by-asset,create-managed-system-by-database-id,create-managed-system-by-workgroup,delete-managed-system-by-id,get-managed-system-by-asset,get-managed-system-by-database-id,get-managed-system-by-functional-account-id,get-managed-system-by-id,get-managed-system-by-workgroup-id,list-managed-systems,update-managed-system-by-id}
    create-managed-system-by-asset
                        Creates a new Managed System using the asset ID.
    create-managed-system-by-database-id
                        Creates a new Managed System using the database ID.
    create-managed-system-by-workgroup
                        Creates a new Managed System using the workgroup ID or name. If both workgroup ID and name are provided, the ID will be used. If
                        neither is provided, an error will be raised.
    delete-managed-system-by-id
                        Deletes a Managed System by ID.
    get-managed-system-by-asset
                        Returns a Managed System by Asset ID or Asset Name.
    get-managed-system-by-database-id
                        Returns a Managed System by Database ID.
    get-managed-system-by-functional-account-id
                        Returns a list of managed systems auto-managed by the functional account referenced by ID.
    get-managed-system-by-id
                        Returns a Managed System by ID.
    get-managed-system-by-workgroup-id
                        Returns a list of managed systems by the workgroup referenced by ID.
    list-managed-systems
                        Returns a list of Managed Systems to which the current user has access.
    update-managed-system-by-id
                        Updates a Managed System by ID.

List Managed Systems

To list all managed systems that the user has access to and show output in JSON format, use:

ps-cli --format json managed-systems list-managed-systems

Get Managed System by ID

To return a managed system searching by ID (-id) and show output in JSON format, use:

ps-cli --format json managed-systems get-managed-system-by-id

Get Managed System by Asset

To return a Managed System by Asset ID or Asset Name and show output in JSON format, use:

ps-cli --format json managed-systems get-managed-system-by-asset

Get Managed System by Database ID

To return a Managed System by Database ID and show output in JSON format, use:

ps-cli --format json managed-systems get-managed-system-by-database-id

Get Managed System by Functional Account ID

To return a list of managed systems auto-managed by the functional account referenced by ID and show output in JSON format, use:

ps-cli --format json managed-systems get-managed-system-by-functional-account-id

Get Managed System by Workgroup ID

To return a list of managed systems by the workgroup referenced by ID and show output in JSON format, use:

ps-cli --format json managed-systems get-managed-system-by-workgroup-id

Create a Managed System by Asset

To create a new Managed System using the asset reference, which could be asset ID or asset name with workgroup name, and show output in JSON format, use:

ps-cli --format json managed-systems create-managed-system-by-asset

Create a Managed System by Database ID

To create a new Managed System using the database ID and show output in JSON format, use:

ps-cli --format json managed-systems create-managed-system-by-database-id

Create a Managed System by Workgroup

To create a new Managed System using the workgroup ID or name and show output in JSON format, use:

ps-cli --format json managed-systems create-managed-system-by-workgroup

Delete Managed System by ID

To delete a Managed System by ID, use:

ps-cli --format json managed-systems delete-managed-system-by-id

Update Managed System by ID

To update a Managed System by ID and show output in JSON format, use:

ps-cli --format json managed-systems update-managed-system-by-id

Workgroups: Workgroup management commands

To display the available commands for Workgroups, use:

ps-cli workgroups -h

Output:

usage: ps-cli workgroups [-h] {create-workgroup,get-workgroup,list-workgroups} ...
    Works with Secrets Safe Workgroups - Create, Update, Get, or Delete
    Requires Password Safe Secrets Safe License.
    Requires Password Safe SecretsSafe Read for Get, Read/Write for all others.
options:
  -h, --help            show this help message and exit
subcommands:
  Subcommands available for workgroups
  {create-workgroup,get-workgroup,list-workgroups}
    create-workgroup    Creates a new Workgroup.
    get-workgroup       Returns a Workgroup by name or id.
    list-workgroups     Returns a list of Workgroups to which the current user has access.

List Workgroups

To list all workgroups that the user has access to and show output in JSON format, use:

ps-cli --format json workgroups list-workgroups

Get Workgroup

To return a Workgroup by name or id and show output in JSON format, use:

ps-cli --format json workgroups get-workgroup

Create a Workgroup

To create a new Workgroup and show output in JSON format, use:

ps-cli --format json workgroups create-workgroup

Databases: Database management commands

To display the available commands for Databases, use:

ps-cli databases -h

Output:

usage: ps-cli databases [-h]
                        {create-database-by-asset-id,delete-database-by-id,get-database-by-id,get-databases-by-asset,list-databases,update-database-by-id}
                        ...
    Controller for managing databases.
    Requires Password Safe Secrets Safe License.
    Requires Password Safe SecretsSafe Read for Get, Read/Write for all others.
options:
  -h, --help            show this help message and exit
subcommands:
  Subcommands available for databases
  {create-database-by-asset-id,delete-database-by-id,get-database-by-id,get-databases-by-asset,list-databases,update-database-by-id}
    create-database-by-asset-id
                        Creates a new database by asset ID.
    delete-database-by-id
                        Deletes a database by ID.
    get-database-by-id  Returns a database by ID.
    get-databases-by-asset
                        Returns a list of databases by asset ID or name.
    list-databases      Returns all databases to which the current user has access.
    update-database-by-id
                        Updates a database by ID.

List Databases

To list all databases that the user has access to and show output in JSON format, use:

ps-cli --format json databases list-databases

Get Database by ID

To return a database by ID and shows output in JSON format, use:

ps-cli --format json databases get-database-by-id

Get Database by Asset

To return a list of databases by asset ID or name and shows output in JSON format, use:

ps-cli --format json databases get-databases-by-asset

Created Database by Asset ID

To create a new database by asset ID and shows output in JSON format, use:

ps-cli --format json databases create-database-by-asset-id

Update Database by ID

To update a database by ID and shows output in JSON format, use:

ps-cli --format json databases update-database-by-id

Delete Database by ID

To delete a database by ID, use:

ps-cli --format json databases delete-database-by-id

Updated about 2 months ago

©2003-2025 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.