Comment on page
Secrets Manager CLI
The Secrets Manager CLI provides shell access to vault secrets
The Keeper Secrets Manager CLI ("KSM CLI") provides core Secrets Manager Vault interaction from a terminal, shell script or any software that can be launched from a shell.
- Get Secrets from the Keeper Vault
- Update Secrets from the Keeper Vault
- Replace environmental variables with Keeper secrets in scripts and containers
The KSM CLI is different than the Commander CLI. The KSM CLI is specifically for secrets management and the Commander CLI is for initial setup and administrative functions.
In order to use the Secrets Manager CLI, or environmental variable substitutions for accessing secrets stored in the Keeper Vault, you must first have an Application and Client Device configured. Check out the Quick Start Guide to set this up.
The KSM CLI is available as a binary application for Windows/Mac/Linux or a pip3 install for any Python environment.
The latest binary release can be found on the GitHub repository. Download the installer based on your operating system and click to install, or unarchive, to use.
When launching the CLI in Windows or macOS, the CLI will run in a shell mode. The
ksm command is still available via the command line.The Linux binary is just an executable and should be moved to a directory in the PATH.
Please ensure that Python 3.x is installed. If not, use your OS-specific package manager to install it.
sudo yum install python3
Make sure your pip3 is up to date:
sudo pip3 install --upgrade pip
Now you can install the Secrets Manager CLI:
sudo pip3 install keeper-secrets-manager-cli
To upgrade to the latest version:
sudo pip3 install -U keeper-secrets-manager-cli keeper-secrets-manager-core
This method will install the CLI into the system Python. If you do not have root or admin permissions, you can install the CLI by setting up a virtualenv. If you do not use virtualenv, the module and binary will be install into your $HOME/.local directory for Linux or macOS. You may need to include a PATH to the bin directory.
For developers, using virtualenv is a clean way to install KSM in an isolated environment.
sudo pip3 install virtualenv
virtualenv -p python3 my_env
source my_env/bin/activate
Then, install ksm to the virtual environment
pip3 install keeper-secrets-manager-cli
The
ksm CLI tool can be used for the following purposes:- Initialize a configuration file for use in integrations such as Github Actions ("init")
- Create a local profile to execute commands as a client device ("profile")
- Query the Keeper vault and retrieve secrets ("secret")
- Wrap command-line applications for environmental variable substitution ("exec")
ksm
Usage: ksm [OPTIONS] COMMAND [ARGS]...
Keeper Secrets Manager CLI Version: X.X.X
Options:
--ini-file TEXT INI config file.
-p, --profile-name TEXT Config profile
-o, --output TEXT Output [stdout|stderr|filename]
-c, --color / -nc, --no-color Use color in table views, where applicable.
--cache / --no-cache Enable/disable record caching.
--help Show this message and exit.
Commands:
config Configure the command line tool
exec Wrap an application and replace env variables
init Initialize a configuration file for integrations
profile Manage local client device profiles
quit Quit shell mode
secret Query the Keeper vault and retrieve secrets
shell Run KSM in a shell
version Get module versions and information.
The CLI is initialized as a client device by passing in the One Time Access Token in the
ksm profile init command. After initialization, the CLI can be used to obtain secrets. In the example below, replace "XX:XXXX" with the One Time Access Token for your Client Device.ksm profile init XX:XXXX
ksm secret list
If you are including the CLI within a container with an automated startup, or do not wish to perform a "profile init", a profile can be auto-created if the KSM_TOKEN is set.
Example:
KSM_TOKEN="XX:XXXX" ksm secret list
Environmental variables can be set to reduce the command line flags.
Environmental Variable Name | Description |
KSM_TOKEN | The one time access token used to initialize the client device |
KSM_HOSTNAME | The host of your Keeper environment. Either US, EU, AU, JP, CA, US_GOV or a full URL. The token will contain the hostname, so this variable is not used in most cases. |
KSM_INI_DIR | The directory where the INI config file is stored for the CLI. |
KSM_INI_FILE | The name of the INI config file for the CLI. |
KSM_CLI_PROFILE | The active profile in the CLI. |
KSM_CONFIG | A Base64 config string. The CLI will use this for the default profile. |
Keeper Secrets Manager commands are run using the
ksm program from the command line.ksm <command> <sub-command> <options>To get help on a particular command, run:
ksm <command> --helpTo get help on a sub-command, run:
ksm <command> <sub-command> --helpCommand | Explanation |
secret | Retrieve secrets from the vault |
profile | Manage local configuration profiles |
init | Initialize one time access token |
exec | Execute scripts with environmental variable substitution |
config | Manage CLI configuration |
version | Display the CLI version information |
shell | Start the CLI in an interactive shell mode |
quit | Quit the shell mode |
Options
--ini-file </path/to/keeper.ini> Sets the keeper.ini configuration file. If not set the CLI will check the following directories for the keeper.ini file.
- The path defined by the environmental variable
KSM_INI_DIR - The current directory
- The user's home directory
${HOME}${HOME}/.config/ksm$env:USERPROFILE
- Various system directories
/etc/etc/ksm/etc/keeper$env:APPDATA/Keeper$env:ProgamData/Keeper$env:ProgramFiles/Keeper
-p, --profile-name <name> use specified configuration profile-o, --output <{stdout, stderr, filename}> Sets the output destinationstdout- Print to stdout (default)stderr- Print to stderr<filename>- Send output to a specified text file
--color/--no-color, -c/-nc Enable or disable color in the output instance.--cache/--no-cache Enable or disable using the record cache for this command instance.
Last modified 2d ago