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
Integrate with 3rd party CI/CD and other dev tools
Sync secrets between Keeper and external secrets providers
Replace environment variables with Keeper secrets in scripts and containers
In order to use the Secrets Manager CLI, or environment 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.
⬇️ Download the Secrets Manager CLI Binary
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.
See the Docker Container page for installation and setup from Keeper's Docker image.
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
Find the Keeper Secrets Manager CLI source code in the GitHub repository.
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
folder Manage folders
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
Environment variables can be set to reduce the command line flags.
Environment 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> --help
To get help on a sub-command, run:
ksm <command> <sub-command> --help
Command
Explanation
secret
Retrieve secrets from the vault
folder
Manage folders
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 destination
stdout
- 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.
Setup and initialization of the Keeper Secrets Manager device profile
profile
commandDescription: Initialize and switch between device profiles. In order to support multiple environments on the same device, you can also switch between Secrets Manager device profiles.
Parameters:
Sub-command and options to run
format: ksm profile <sub-command>
Sub-Commands:
Sub-Command
Description
init
Initialize a new client device profile
setup
Setup a new profile from 3rd party external secrets manager like AWS.
list
List profiles that have been created, and note active profile
export
Export a configuration profile
import
Create a new configuration from an exported encrypted profile
active
Sets the active configuration profile
Initialize a client device profile.
ksm profile init
The file keeper.ini
file will be created in your current working directory. For the Windows or macOS binary applications, the keeper.ini
will be created in the users home directory (${HOME} or $env:USERPROFILE
environment variables). The keeper.ini
can be moved to the following locations:
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
Parameters:
-t, --token <token>
one-time access token
-h, --hostname <XX>
destination region
Defaults to US region. Customers hosted in other regions must set this value:
US
(United States)
EU
(Europe)
AU
(Australia)
JP
(Japan)
CA
(Canada)
US_GOV
(GovCloud)
--ini-file <FILENAME>
save the new profile to this file
-p, --profile-name <NAME>
set profile name
If not provided, the profile will be set as "default"
Typically, you will be initializing the KSM CLI with a token created in the vault or in Keeper Commander. For example:
ksm profile init --token XX:XXXXXXXX
To avoid exposing the token on the command line use KSM_CLI_TOKEN
environment variable. For example:
ksm profile init --ini-file=/tmp/custom.ini --profile=non_default
Usage of KSM_CLI_TOKEN
environment variable to provide one-time token allows for selecting a custom INI file and custom profile (to create/overwrite) and can be overridden by --token
option from command line.
As described in the Quick Start Guide, you can create a token from the Commander CLI or from the Keeper Vault interface. For example:
My Vault> secrets-manager client add --app MyApplicationName
Setup a new profile to be loaded from external storage like the AWS Secrets Manager. This is ideal when using Keeper Secrets Manager CLI from a cloud instance. Using this method of authentication adds additional layers of security.
There are 3 ways of integrating with external storage providers like AWS:
EC2 instance role (recommended)
AWS profile credentials
AWS custom keys
To initialize the KSM CLI profile on an EC2 instance using the AWS EC2 instance role:
ksm profile setup --type=aws
This creates a keeper.ini file which defines the secret key in AWS. For example:
....
[_default]
storage = aws
provider = ec2instance
secret = ksm-config
By default, the secret key is assumed to be called ksm-config
. You can specify a different key value by editing the keeper.ini file or using the --secret
option. Example:
ksm profile setup --type=aws --secret my-ksm-config
The KSM CLI can be configured to use a specific AWS profile that has been previously initialized on this device with the aws configure
command.
For example:
ksm profile setup --type=aws --secret=ksm-config --credentials=profile --credentials-profile=default
The KSM CLI can be configured to use a specific AWS Access Key / Secret Key pair. In this scenario, the Access Key and Secret Key will be stored locally in the keeper.ini
file.
For example:
ksm profile setup --type=aws --secret=ksm-config --credentials=keys --aws-access-key-id XXX --aws-secret-access-key XXX --region XXX
An additional flag --fallback
allows you to specify falling back to the default profile (from the AWS local configuration) if the initial credentials fail.
To complete the setup, a base64 KSM configuration value must be generated from the Keeper Vault interface or the Keeper Commander CLI. This is described in the Quick Start Guide.
For example, using the Commander CLI, this can be generated using a command such as the one below:
My Vault> secrets-manager client add --app "My KSM App" --config-init b64
Successfully generated Client Device
====================================
Initialized Config: [Base64 Config....]
Copy the provided configuration for use in the next step.
In order for this KSM device to authenticate against Keeper Secrets Manager, the KSM configuration value in base64 format must be populated into the AWS Secrets Manager. For example, using the AWS CLI:
aws secretsmanager create-secret --name ksm-config --secret-string '[Base64 Config]'
Now, you can verify that KSM CLI works and can access secrets from your vault using:
ksm secret list
UID Record Type Title
----------------------- -------------------- --------------------------
n9SdOX1cEyMj9Ttj3lsjYQ pamUser IAM Account: demouser
WfxgS6E_bY_tzdIChYIsAA login Amazon AWS - john
toAfybW5SsbhRT9LtZ7oyg serverCredentials QA Server
--ini-file <FILENAME>
save the new profile to this file instead of keeper.ini.
-p, --profile-name <NAME>
set profile name. If not provided, the profile will be set as "default"
List all available profiles for the current Client Device.
ksm profile list
Example:
$ ksm profile list
Active Profile
======== ===============
Production
* Test Server 1
Test Server 2
Local Dev
Export the current profile into a base64-encoded string.
ksm profile export [--plain] [--file-format] [PROFILE NAME]
optional parameters:
--plain
Export profile without base64-encoding the string.
--file-format
Export a profile to a specific file format. Available formats are:
ini - To be used by another instance of the CLI.
json - Can be used by the CLI and other Developer SDKs.
Example
$ ksm profile export my_profile
Note: When using an external storage provider for KSM configuration, the profile will not be exportable.
Import a client device profile from an encrypted base64-encoded string.
ksm profile import [--output-file "INI filename"] <BASE64 CONFIG>
optional parameters:
--output-file <INI filename>
Where to create the INI configuration file. If not set, will be create in current directory.
$ ksm profile import --output-file=my_profile BASE64_ENC_CONFIG
Set the currently active profile for this client device.
ksm profile active <PROFILE NAME>
Example:
$ ksm profile active production
production is now the active profile.
If you are running the CLI inside of a containerized environment, you might not have the ability to initialize a profile. If no INI config file is found and the environment variable KSM_TOKEN is found, a default profile will be auto-generated. A INI config file will be created and stored in the current working directory. That can be overridden with the environment variable KSM_INI_DIR.
The default name of the ini file is keeper.ini
, however this can overridden by using the KSM_INI_FILE
environment variable. By using KSM_INI_DIR
and KSM_INI_FILE
environment variables you can completely change the location and name of the INI configuration file.
Initialize
init
commandDescription: Initialize a one time access token
Parameters:
Sub-command to run
format: ksm init <sub-command>
Sub-Commands:
Sub-Command
Description
default
Return the redeemed token as base64 encoded JSON
k8s
Return the redeemed token as Kubernetes secret script.
Initialize a one time access token and create a configuration profile for use with external integrations like Github Actions, Terraform and others. The output of the configuration can be generated as either base64 encoded JSON (default), or k8s format. Other KSM Developer SDKs, and applications, will understand configurations in this format.
ksm init default <TOKEN>
optional parameters:
--plain
do not base64 encode the configuration. Return plain JSON.
-h, --hostname
change the hostname
--skip-ssl-verify
- Do not verify the remote SSL certificate.
$ ksm init default XX:XXXX
ewogICAgImNsaWVudElkIjogInd ... U1R4eUQrU3ZNbkhrMTVLUHRGS2MrZlZJOGtlOUtL==
Initialize a one time access token into a Kubernetes secret script.
ksm init k8s <TOKEN>
optional parameters:
--name, -n
Name of the Kubernetes secret. Default is ksm-config.
--namespace, --ns
Name of the Kubernetes namespace. Default is default.
--apply
Automatically use kubectl to apply the secret. You will not see the secret script.
--immutable, -i
Make the secret immutable. Requires Kubernetes >= 1.21
-h, --hostname
change the hostname
--skip-ssl-verify
- Do not verify the remote SSL certificate.
$ksm init k8s XX:XXXX
apiVersion: v1
data
config: ewogICAgImNsaWVudElkIjogIml ... dWJsaWNLZXlJZCI6ICIxMCIKfQ==
kind: Secret
metadata:
name: ksm-config
namespace: default
type: Opaque
Retrieve secrets and file attachments from the Keeper Vault
secret
commandDescription: Retrieve secrets from the vault and parse the response.
Parameters:
Sub-command to run
format: ksm secret <sub-command>
Sub-Commands:
Sub-Command
Description
list
List all secrets associated with the application
get
Get a secret from the vault, or specific fields from a secret
add
Add a new secret to the vault.
update
Update a field within an existing secret
delete
Delete secrets from the vault.
upload
Upload a file attachment to an existing secret
download
Download a vault secret file attachment by name
template
Display a record type template
notation
Test templating environment variables for the exec
command
totp
Generate pass code from a TOTP field of the secret
password
Generate a password
List all secrets associated with the application
ksm secret list
optional parameters:
--json
return in JSON format
--uid <RECORD UID(s)>
get specific records by Record UID
-t, --title <REGEX>
get records with title matching the REGEX
-f, --folder <folder UID>
List only records in the selected folder UID.
-r, --recursive
list recursively all records in the selected folder UID including all subfolders.
-q, --query <JSONPath Query>
List only records matching the JSON Path query.
-v, --show-value
print matching value instead of the record title when using JSON Path query.
Example 1: Tabular format
$ ksm secret list
UID Record Type Title
----------------------- -------------------- -------------------------
SNzjw8tM1HsXEzXERCJrNQ login Stripe API Key
8f8I-OqPV58o2r91wVgZ_A databaseCredentials Production MySQL Database
hDFhwSUe6pTWdkJDSRmtBg login Amazon AWS
Example 2: JSON format
$ ksm secret list --json
[
{
"uid": "SNzjw8tM1HsXEzXERCJrNQ",
"title": "Stripe API Key",
"record_type": "login"
},
{
"uid": "8f8I-OqPV58o2r91wVgZ_A",
"title": "Production MySQL Database",
"record_type": "databaseCredentials"
},
{
"uid": "hDFhwSUe6pTWdkJDSRmtBg",
"title": "Amazon AWS",
"record_type": "login"
}
]
Example 3: Search by Title while filtering by folder
$ ksm secret list --recursive --folder=KOx3pRkAnODGVWyDuK7ttw -t Stripe
UID Record Type Title
----------------------- -------------------- --------------
SNzjw8tM1HsXEzXERCJrNQ login Stripe API Key
Example 4: Search by field attributes using JSONPath
$ ksm secret list --query=$.custom_fields[?(@.type==text)].value
UID Record Type Title
----------------------- -------------------- --------------
SNzjw8tM1HsXEzXERCJrNQ login Stripe API Key
$ ksm secret list -v --query=$.custom_fields[?(@.type==text)].value
UID Record Type Value
----------------------- -------------------- ---------------
SNzjw8tM1HsXEzXERCJrNQ login <API_Key_Value>
Get a secret from the vault, or specific fields from a secret
ksm secret get <RECORD UID>
requires at least one of the following parameter:
<RECORD UID>
- if retrieving one record, the record UID can be part of the command line argument.
-u, --uid <RECORD UID>
get a specific record by it's unique ID. Muliple -u can be used to get more than one record.
-t, --title <RECORD TITLE>
get a specific record by it's title.
optional parameters:
-f, --field <Field Type or Custom Field Label>
return the value of a specific field by label or type.
-q, --query <JSONPath Query>
get specific fields within a secret
--json
return in JSON format (required when --query used)
--raw
remove quotation marks from result
--force-array
return results as an array even if there is only one result
--unmask
show password values in table views
--inflate/--deflate
by default, references to other records will be loaded into a record. If --deflate is used, the reference records will not be loaded into the record.
Example 1: Returning a Secret to the console with tabular format
$ ksm secret get 8f8I-OqPV58o2r91wVgZ_A
Record: 8f8I-OqPV58o2r91wVgZ_A
Title: Production MySQL Database
Record Type: databaseCredentials
Field Value
--------- ----------------------------------------------
text MySQL
host [{"hostName": "192.168.1.24", "port": "3306"}]
login user
password ****
Example 2: Returning a Secret to the console with tabular format and password unmasked
$ ksm secret get --unmask --uid 8f8I-OqPV58o2r91wVgZ_A
Record: 8f8I-OqPV58o2r91wVgZ_A
Title: Production MySQL Database
Record Type: databaseCredentials
Field Value
--------- ----------------------------------------------
text MySQL
host [{"hostName": "192.168.1.24", "port": "3306"}]
login user
password ksv#$0sbnb7W@b3VGCHb
Example 3: Retrieving the password field from a secret. There are 2 different methods of doing this.
# Using field searching
$ ksm secret get -u SNzjw8tM1HsXEzXERCJrNQ -f password
# Using query syntax
$ ksm secret get -u 8f8I-OqPV58o2r91wVgZ_A \
--json --query '$.fields[?(@.type=="password")].value'
# Using query syntax for complex values
$ ksm secret get -u SNzjw8tM1HsXEzXERCJrNQ \
--json --query '$.fields[?(@.type=="keyPair")].value[0].publicKey'
Example 4: Retrieving a particular Custom Field value. There are 2 different methods of doing this.
# Using field searching
$ ksm secret get -u SNzjw8tM1HsXEzXERCJrNQ -f "API Key"
# Using query notation
$ ksm secret get --uid SNzjw8tM1HsXEzXERCJrNQ \
--json --query '$.custom_fields[?(@.label=="API Key")].value'
Example 5: Retrieving raw JSON for the individual secret
$ ksm secret get --unmask --uid 8f8I-OqPV58o2r91wVgZ_A --json
{
"uid": "8f8I-OqPV58o2r91wVgZ_A",
"title": "Production MySQL Database",
"type": "databaseCredentials",
"fields": [
{
"type": "text",
"value": [
"MySQL"
]
},
{
"type": "host",
"value": [
{
"hostName": "192.168.1.24",
"port": "3306"
}
]
},
{
"type": "login",
"value": [
"user"
]
},
{
"type": "password",
"value": [
"ksv#$0sbnb7W@b3VGCHb"
]
},
{
"type": "fileRef",
"value": []
}
],
"custom_fields": [],
"files": []
}
Add a record to the vault. There is four ways to add a secret record: clone existing record, use visual editor, from a file, and from field arguments.
The editor command will launch an editor application with a record with placeholder values. Replace the placeholder values or remove the value all together. The editor application can be set via ksm config editor
or it will use the editor specified by the EDITOR environment variable. If the editor is not set, the CLI will attempt to find an installed editor.
An editor with a UI can be set. For Windows and MacOS blocking may need to be enabled if the the editor instantly warns about placeholder still existing in the record template. This is because, without blocking, the CLI will attempt to process the record before you are finished editing.
On MacOS, blocking will wait until the application fully exits before processing the record data. This mean the application is closed and no longer in the dock, not that the editor window is closed.
On Windows, blocking will wait until the process is no longer in the task list. If the application is launched via a .bat or .cmd file, the process name will be different from the application that was launch. To properly handle this use ksm config editor
to set up the editor.
ksm secret add editor --sf <STORAGE FOLDER UID> --rt <RECORD TYPE> [--title "TITLE"] [--notes "NOTES"] [-p] [-o yaml | json]
Required parameters:
--storage-folder-uid, --sf
The storage folder UID where the new secret record will be created.
--record-type, --rt
The record type of the secret record.
Optional parameters:
--title, -t
Title of the secret record.
--notes, -n
Notes associated with the secret record.
--password-generate, -p
Generate a password for any password field that does not have a value.
--output-format, -o
The output format of the template in the editor. Can either be JSON or YAML. The default is JSON.
--editor, -e
Override the editor. If using this parameter, the editor should cause blocking.
Example:
Launch an editor with a login record with placeholder values. Either set the value or replace the value altogther, save file and exist browser.
ksm secret add editor --sf XXXXXX --rt login -o yaml
<in the editor>
version: v3
kind: KeeperRecord
data:
- recordType: login
title: '<#ADD: The title of record here. This is required.>'
notes: '<#ADD: Add some notes or remove.>'
...
<save and exit from editor>
The following is the new record UID ...
["Ai9iFYWf6EOE0T9fV-ynBg"]
The file command is similar to editor command except done in two steps. The first step is getting a placeholder record file using the command ksm secret template. Then replacing the placeholder values and using this command to read in that file to create the record(s).
Using this command allows you create multiple records at one time.
ksm secret add file --sf <STORAGE FOLDER UID> -f <TEMPLATE FILE> [-p]
Required parameters:
--storage-folder-uid, --sf
The storage folder UID where the new secret record will be created.
--file, -f
Path and name of the record template file.
Optional parameters:
--password-generate, -p
Generate a password for any password field that does not have a value.
Example:
Save a bank account record type with placeholder values. Edit in your favorite editor and save. Then add using the ksm secret add file
command. Also generate a password in any blank password fields.
ksm secret template bankAccount -f new_bank_account_record.json
<edit new_bank_account_record.json in favortite editor>
ksm secret add file --sf XXXX -f new_bank_account_record.json -p
The field command set the values of a record via key/value arguments passed into the command.
ksm secret add field <--sf STORAGE FOLDER UID> <--rt RECORD TYPE> <--title "TITLE>"> [--notes "<NOTES>"] [-p] <"FIELDS" ...>
Required parameters:
--storage-folder-uid, --sf
The storage folder UID where the new secret record will be created.
--record-type, --rt
The record type of the secret record.
--title, -t
Title of the secret record.
FIELDS
- Key/Value pairs of the fields and their values. There can be multiple fields.
Optional parameters:
--notes, -n
Notes associated with the secret record.
--password-generate, -p
Generate a password for any password field that does not have a value.
Example:
ksm secret add field --sf XXXX --rt bankAccount \
-t "My Bank Account" -n "My Checking Account" -p \
"f.bankAccount.accountType=Checking" \
"f.bankAccount.routingNumber=ROUT123" \
"f.bankAccount.accountNumber=ACC456" \
'f.name={"first": "John", "last": "Smith"}' \
"login=jsmith" \
"url=http://mybank.com" \
"c.text[Bank Hours]=7:00AM to 5:00PM" \
'c.phone=[{"number": "5551234567", "type": "Home"}, {"number": "5550987654"}]'
The following is the new record UID ...
Ai9iFYWf6EOE0T9fV-ynBg
The structure of the field
is [field section .
]<field type
>[[field label]
][. value key
]<=value
>
The field section
is where the field is to be set. 'f' is the standard fields, 'c' is the custom fields. If not included, the field default to the standard fields.
The field type
is required. For the standard field section, the field type must be part of the record type schema. If you attempt to add a field that doesn't exist, an error with be displayed. For the custom field section, any field type can be added. They will be ordered as they are added.
The field label
is optional. The field label is surrounded by []
directly after the field type
. For the custom field section, if the label is not set, the record field type is used in the UI.
The value key
is optional for field types that have complex value, such a phone
, bankAccount
, and name
. The value key
allows a value to be built in pieces instead of setting the value as a JSON value.
The value
begins after the = character. If the value is complex, then JSON is set as the value. If using JSON make sure the quote the field appropriately. If the JSON uses double quotes, then surround the field with single quotes. And if you need both, then you will need to escape the quotes with a backslash (\).
Rules
For standard fields, the order in which the fields are set does not matter. The fields will be ordered by the record type schema. Fields that do not exists in the record type schema standard fields cannot be added to the standard fields.
For custom field, the fields will be ordered the same as the order of the field arguments.
If you have multiple fields of the same type you will need to include a field label
to make them unique.
Value Key
Setting values using value key is useful when setting one field, however there are rules when setting another field of the same type or when the field accepts multiple values (ie phone).
If you are setting more than one field of the same type, the use a field label
will make the field unique.
ksm secret add field --sf XXXX --rt "Custom Record" \
"name[My Doctor].first=Jane" \
"name[My Doctor].last=Smith" \
"name[My Lawyer].first=John" \
"name[My Lawyer].last=Doe"
If a field label
is not used, the prior values will overwrite the existing values.
JSON Values
A value can be set to a JSON value. For fields that allow multiple values, setting a JSON value will be consider a complete value. That means if a value key
comes after a JSON value, an additional value will be added to the field. The example below will create a phone field with two values.
ksm secret add field --sf XXXX --rt "Custom Record" \
'c.phone={"number": "5551234567"}' \
"c.phone.number=5551111111"
If the JSON value is an array of JSON objects. the field is considered a completed field. This mean no additional values can be added the field. The following will result in an error about the fields last field not being unique. To make the field unique a field label
can be added.
ksm secret add field --sf XXXX --rt "Custom Record" \
'c.phone=[{"number": "5551234567"}, {"number": "55599999999"}]',
"c.phone.number=5551111111"
ksm had a problem: Cannot add this field due to it not being unique. To make unique add a label to the field or make sure the label is not being duplicated.
Delete secrets associated with the application
ksm secret delete
--uid <RECORD UID(s)>
delete records by Record UID
optional parameters:
--json
return in JSON format
Example 1: Tabular format
$ ksm secret delete -u AAAAAAAAAAAAAAAAAAAAAA -u SNzjw8tM1HsXEzXERCJrNQ
UID Response Code Error
----------------------- -------------------- ---------
AAAAAAAAAAAAAAAAAAAAAA n/a Not Found
SNzjw8tM1HsXEzXERCJrNQ ok
Example 2: JSON format
$ ksm secret delete --json -u AAAAAAAAAAAAAAAAAAAAAA -u riEeV5KUeiGqXXSidg47Zw
[
{
"uid": "AAAAAAAAAAAAAAAAAAAAAA",
"responseCode": "n/a",
"error": "Not found"
},
{
"uid": "riEeV5KUeiGqXXSidg47Zw",
"responseCode": "ok",
"error": null
}
]
The clone
command creates new record using data from an existing record with an option to set a new title.
ksm secret add clone --uid <RECORD UID> --title "TITLE"
Required parameters:
--uid, -u
The record UID of existing record.
Optional parameters:
--title, -t
Title of the new record.
Example:
ksm secret add clone --uid XXXX --title NewTitle
The following is the new record UID ...
Ai9iFYWf6EOE0T9fV-ynBg
Update an existing field within an existing secret.
ksm secret update --uid <RECORD UID>
Optional Parameters:
--field
- Update the value of a specific standard field in the secret.
--custom-field
- Update the value of a specific custom field in the secret.
--field-json
- Update the value of a specific standard field using JSON. Use for complex field values.
--custom-field-json
- Update the value of a specific custom field using JSON. Use for complex field values.
--title, -t
- Update the title of the secret.
--notes, -n
- Update the notes of the secret.
The update will match your key on existing field and custom field labels. Anything that appears after the '=' character is assumed to be the value. No escaping values is required, unless you are wrapping the parameter value is quotes.
Example 1: Basic use case
# Update the password for a secret
$ ksm secret update --uid XXXXX --field password=xxxxxxxxxxx
# Update a custom field value
$ ksm secret update --uid XXXXX --custom-field "My Custom Label=XXXXX"
Example 2: If a key or field values contains a space, the entire parameter value needs to be wrapped in quotes. If your value contains quotes you need differnet quotes around the parameter value. For example, if your value contains JSON, use single quotes around the parameter value.
$ ksm secret update --uid XXXXX --custom-field "My Base64=SElUSEVSRQo="
$ ksm secret update --uid XXXXX --field-json 'name={"first": "John", "middle": "X", "last": "Doe"}'
Upload attachment to an existing secret in the vault
ksm secret upload -u <RECORD UID> --file "<FILENAME>" --title "<FILE_TITLE>"
Parameters:
-u, --uid <RECORD UID>
UID of the secret to upload to (Required)
-f, --file <FILENAME>
file path to the file to upload (Required)
-t, --title
file title - if not provided defaults to the file name (without the path) (Optional)
Example:
$ ksm secret download -u oxhtLx9qrQIzeSXBtvQj2Q \
--name "SSHKey.pem" --file-output SSHKey.pem
Download attachments from secrets in the vault, such as SSH keys
ksm secret download -u <RECORD UID> --name "<FILENAME>" --file-output "<OUTFILE>"
Optional parameters:
-u, --uid <RECORD UID>
UID of the secret to download (Required)
--name <FILENAME>
name of the file to download (Required)
--file-output <FILENAME | STDOUT | STDERR>
where to write the file's content (Required)
--create-folders
create folder for filename path
Example:
$ ksm secret download -u oxhtLx9qrQIzeSXBtvQj2Q \
--name "SSHKey.pem" --file-output SSHKey.pem
Display record or field type template information.
Get the record type schema template and record type list.
ksm secret template record [-l] [-o json | yaml] [-f OUTPUT FILE] [RECORD TYPE]
Required one of the following parameters:
--show-list, -l
Display a list of all available record types.
RECORD TYPE
- Get the schema template for this record type.
Optional parameter
--output-format, -o
Output the schema as JSON or YAML. The default is JSON.
--output-file, -f
Output the schema to a file.
Example 1: Gettting a list of record types
$ ksm secret template record -l
Record Type
------------------------
login
bankAccount
address
...
Example 2: Getting the schema for the record type bankAccount
in YAML.
ksm secret template record -o yaml bankAccount
version: v3
kind: KeeperRecord
data:
- recordType: bankAccount
title: '<#ADD: The title of record here. This is required.>'
notes: '<#ADD: Add some notes or remove.>'
fields:
- type: bankAccount
value:
accountType: '<#ADD: Checking | Other | Savings>'
otherType: '<#ADD: Other Type Description>'
routingNumber: '<#ADD: Routing Number>'
accountNumber: '<#ADD: Account Number>'
privacyScreen: false
- type: name
value:
first: '<#ADD: First Name>'
middle: '<#ADD: Middle name>'
last: '<#ADD: Last Name>'
privacyScreen: false
- type: login
value: '<#ADD: Insert a str>'
privacyScreen: false
- type: password
value: '<#ADD: Password or Remove If Generating>'
privacyScreen: false
enforceGeneration: false
complexity:
length: 64
caps: 0
lowercase: 0
digits: 0
special: 0
- type: url
value: '<#ADD: Insert a str>'
privacyScreen: false
- type: cardRef
value: '<#ADD: Record UID of PaymentCard record.>'
privacyScreen: false
- type: fileRef
value: '<#ADD: Record UID of File record.>'
privacyScreen: false
- type: oneTimeCode
value: '<#ADD: URL starting with otpauth://>'
privacyScreen: false
Get the field type schema and field type list.
Required one of the following parameters:
--show-list, -l
Display a list of all available field types.
FIELD TYPE
- Get the schema for this field type.
Optional parameter
--output-format, -o
Output the schema as JSON or YAML. The default is JSON.
Example 1: Getting a list if field types.
$ ksm secret template field -l
Field Type
----------------
accountNumber
address
addressRef
...
Example 2: Get a field type's schema in the default JSON
$ ksm secret template field securityQuestion
{
"type": "securityQuestion",
"value": {
"question": "<#ADD: Security Question>",
"answer": "<#ADD: Answer To The Question>"
},
"privacyScreen": false
}
Test the magic environmental variable substitution for the ksm exec
command.
ksm secret notation <NOTATION FIELD PATH>
This sub-command allows you to test the environmental variable substitution method by returning the field value through a keeper://
template URL.
Example:
$ ksm secret notation keeper://8f8I-OqPV58o2r91wVgZ_A/field/password
ksv#$0sbnb7W@b3VGCHb
$ ksm secret notation keeper://oxhtLx9qrQIzeSXBtvQj2Q/field/password
H=cBcl(u6%Ouv]mXpkPU>u]C;P0>E%yrcML
For more details about environmental variable substitution, see the Exec Command.
Generate valid pass code from a TOTP field from secret in the vault.
ksm secret tot <RECORD UID>
Required parameters:
<RECORD UID>
UID of the secret with a TOTP field
Example:
$ ksm secret totp oxhtLx9qrQIzeSXBtvQj2Q
123456
Generate a random password.
ksm secret password --length <PASSWORD LENGTH> --lc <# OF LOWERCASE CHARS> --uc <# OF UPPCASE CHARS> -d <# OF DIGITS> --sc <# OF SPECIAL CHARACTERS>
Optional parameters:
Overall length. Character group values will automatically be split equally from the length.
--length, -l
= Length of password. This will split the length between lowercase, uppercase, digits, and special characters.
Character groups
-lc
= Number of lowercase characters.
-uc
= Number of uppercase characters.
-d
= Number of digits
-sc
= Number of special characters.
Example:
$ ksm secret password
j.th,D,X92[B;d<F{2IkxuWS={#G4g7=b39kA16v6p44lqBU=v.Y6?MH5}$H3pG4
$ ksm secret password --length 32
5N=%B6ytb9No3w[F7WYgN0V@"+2j!u1#%
$ ksm secret password -lc 10
qaytxkwdwb
$ ksm secret password -lc 2 -uc 2 -digits 2 -sc 0
4keD0V
If a record UID starts with "-" (dash / hyphen) it needs to be pre-pended with "--" to be used with the KSM CLI.
Example:
ksm secret get -- -id8QpE2ZAkdd4KlCfoWQ
*The UID in this example is not a real record UID
See the Troubleshooting section for more details
Manage folders from the Keeper Vault shared to KSM Applications
folder
commandDescription: List, create, update and delete folders from the vault. Works only within folders shared to KSM Applications. The folder command manages subfolders within existing shared folders.
Parameters:
Sub-command to run
format: ksm folder <sub-command>
Sub-Commands:
Sub-Command
Description
list
List all folders associated with the application
add
Add a new subfolder to the vault.
update
Rename a folder
delete
Delete the folders from the vault
List all folders associated with the application
ksm folder list
optional parameters:
--json
return results in JSON format
-f, --folder <folder UID>
List only folders/records in the selected folder UID.
-r, --recursive
list recursively all folders/records in the selected folder UID including all subfolders.
-l, --list-records
Include folder records info in the output.
Example 1: Tabular format
$ ksm folder list
Type Parent UID Title
---- ----------------------- ----------------------- ---------------
dir vZdNYOi7Oh1q6pvI9jY8KA Applications
dir EVvnsKbrlYHMi4HVTBn3-w Databases
dir EVvnsKbrlYHMi4HVTBn3-w Bj9bNJjSFobG-VE7MImaIA Oracle
Example 2: JSON format
$ ksm folder list --json
[
{
"type": "dir",
"parent_uid": "",
"uid": "vZdNYOi7Oh1q6pvI9jY8KA",
"title": "Applications"
},
{
"type": "dir",
"parent_uid": "",
"uid": "EVvnsKbrlYHMi4HVTBn3-w",
"title": "Databases"
},
{
"type": "dir",
"parent_uid": "EVvnsKbrlYHMi4HVTBn3-w",
"uid": "Bj9bNJjSFobG-VE7MImaIA",
"title": "Oracle"
}
]
Create a new subfolder into the specified parent folder. KSM can create subfolders only in existing shared folders that are shared to the KSM App including their subfolders and cannot create new shared folder(s).
ksm folder add --parent-folder <FOLDER UID> --title <FOLDER TITLE>
Required parameters:
--parent-folder, -f
The parent folder UID where the new (sub)folder will be created.
--title, -t
Title of the new folder.
Example:
ksm folder add --parent-folder vZdNYOi7Oh1q6pvI9jY8KA --title NewApp
The following is the new folder UID ...
Ai9iFYWf6EOE0T9fVAynBg
Rename a folder.
ksm folder update --folder <FOLDER UID> --title NEW_TITLE
Parameters:
--folder, -f
- Folder UID of the folder to rename.
--title, -t
- The new folder title.
Example:
$ ksm folder update --uid Ai9iFYWf6EOE0T9fVAynBg --title NewAppTitle
Delete a folder in the vault (shared to the KSM App)
ksm folder delete <FOLDER UID>
Parameters:
<FOLDER UID>
UID of the folder to delete (Required)
-f, --force
force deletion of non-empty folders (Optional)
Example:
$ ksm folder delete Ai9iFYWf6EOE0T9fVAynBg
UID Response Code Error
----------------------- ------------- -----
Ai9iFYWf6EOE0T9fVAynBg ok
Synchronizes selected keys from Keeper Vault to an external secrets manager
Synchronization is one way only, using Keeper as a source of truth (read only) and updates only the remote key-value pairs in the external secrets manager.
sync
commandDescription: Import and synchronize secrets from the Keeper Vault with external secrets management systems
ksm sync --credentials <UID> --type [aws|azure|gcp|json] [--dry-run] [--preserve-missing] --map <KEY NOTATION>...
parameters:
-t, --type
Type of the target key/value storage. Available types are:
aws
- AWS Secrets Manager
azure
- Azure Key Vault
gcp
- GCP Secret Manager
json
- lists all pending sync operations including both source and destination values
-m, --map
<KEY NOTATION>...
Map destination key names to values using notation URI
-c, --credentials <uid>
UID of Keeper record with credentials to access destination key/value storage. The specified record must be shared with the Keeper Secrets Manager Application
optional parameters:
-n, --dry-run
Perform a trial run with no changes made.
-p, --preserve-missing
Preserve destination value when source value is deleted.
Select an external provider below to learn more about the integration.
AWS Secrets Manager SyncAzure Key Vault SyncGoogle Cloud Secret Manager SyncExecute arbitrary system calls and replaces templated environment variables with Keeper vault secrets
exec
commandTo perform magic environment variable substitution, use the ksm exec
command.
Parameters:
System call or script to run with replaced environment variables
format: ksm exec -- <SYSTEM CALL OR SCRIPT>
#!/bin/bash
# Bash script that pulls Keeper secrets
connect_db() {
echo "Database Password:" $DB_PASSWORD
}
call_stripe() {
echo "API Key:" $API_KEY
}
connect_db
call_stripe
Set a couple environment variables then execute the script:
$ export DB_PASSWORD="keeper://XXX/field/password"
$ export API_KEY="keeper://XXX/custom_field/API Key"
$ ksm exec -- ./my_script.sh
Database Password: ksv33110sbnb7W@b3VGCHb
API Key: sk_test_MY2A30Ofg6Ukkq2NjMQVo87c
C:\> ksm exec -- my_script.bat
PS C:\> ksm exec -- powershell my_script.ps1
Environment variables must be templated so that the CLI can find and replace them correctly. For example:
export DB_PASSWORD="keeper://XXX/field/password"
export API_KEY="keeper://XXX/custom_field/API Key"
Below is a Linux bash script example. Before an application is started or a command is run, any environment variables that start with keeper://
will be replaced with secret values from the vault. Make sure to replace XXXX with the Record UID of the secret.
export MY_PASSWORD=keeper://XXXX/field/password
export MY_OTHER_PASSWORD=keeper://XXXX/field/password[0]
export MY_LAST_NAME=keeper://XXXX/custom_field/Name 2[last]
export MY_SECOND_PHONE=keeper://XXXX/custom_field/phone[1][number]
Here's a simple bash script that prints the secrets to the console:
#!/usr/bin/env bash
echo
echo "My Password = \${MY_PASSWORD}"
echo "Other Password = \${MY_OTHER_PASSWORD}"
echo "My Last Name = \${MY_LAST_NAME}"
echo "My Second Phone = \${MY_SECOND_PHONE}"
And here's the output from executing the bash script with ksm exec
$ ksm exec -- ./my_script.sh
My Password = $71387feh24fE%4416ffFHA
Other Password = YYFash328f^F^@#Fsdfjhsgblqef'f;
My Last Name = Smith
My Second Phone = 123-456-7890
Configure the local Secrets Manager CLI environment
config
commandDescription: Configure the CLI debug output
Parameters:
Sub-command to run
format: ksm config <sub-command>
Sub-Commands:
Sub-Command
Description
color
Turn on or off color display
cache
Turn on or off the record cache
record-type-dir
Set the directory that hold custom record type schemas.
editor
Set an editor for visual adding new records.
show
Display current CLI settings
ksm config color <--enable | --disable>
--enable
Turn on color display
--disable
Turn off color display
$ ksm config color --disable
$ ksm config show
Config Item Value
---------------------- --------------
Color Enabled False
The record cache creates a copy of your records and will be used if the CLI cannot access the Secrets Manager server. A copy of records are stored encrypted on local storage.
ksm config cache <--enable | --disable>
--enable
Turn on record caching
--disable
Turn off record caching
$ ksm config cache --enable
$ ksm config show
Config Item Value
---------------------- -----------
Cache Enabled True
Set the record type schema directory containing custom record type schema files.
ksm config record-type-dir [-d DIRECTORY PATH] [--clear]
Options:
--directory, -d
Directory path
--clear
Remove the directory path
$ ksm config record-type-dir -d /path/to/directory
$ ksm config show
Config Item Value
---------------------- -----------
Record Type Directory /path/to/directory
Set the editor to use when visually adding records.
ksm config editor [--app APPLICATION] [--blocking] [--process-name PROCESS NAME]
Options:
--application, --app
The editor application to launch.
--clear
Remove the directory path
These optionals can be used when setting the --application
.
--blocking
Enable to prevent the CLI from prematurely processing your record data.
--process-name
Used in blocking to find the real process name in the task list.
ksm config editor --app Code --blocking --proces-name code.exe
$ ksm config show
Config Item Value
---------------------- -----------
Editor Code (code.exe)
Editor Blocking True
ksm config show
$ ksm config show
Config Item Value
---------------------- -----------
Active Profile all_records
Cache Enabled False
Color Enabled False
Record Type Directory -NOT SET-
Editor vim (NA)
Editor Blocking False
Display Keeper Secrets Manager CLI version information
version
commandView CLI information such as version and Python module installation location. The command will also show the Python version, SDK version, and the path of the INI configuration file
format: ksm version
$ ksm version
Python Version: 3.9.16
Python Install: /usr/local/ksm/bin/ksm
CLI Version: 1.1.0
CLI Install: /usr/local/ksm/bin/keeper_secrets_manager_cli
SDK Version: 16.5.4
SDK Install: /usr/local/ksm/bin/keeper_secrets_manager_core
Config file: /Users/craig/keeper.ini
Version 1.1.1 is available for the CLI
Version 16.6.2 is available for the SDK
Use the Keeper Commander CLI for hundreds of Vault and Admin Console commands
The Keeper Secrets Manage CLI is focused specifically on retrieving and updating secrets in the vault.
For all other commands, please refer to the Keeper Commander CLI:
Commander CLIRun the CLI using a Docker container.
The first step is pulling the CLI image.
docker pull keeper/keeper-secrets-manager-cli:latest
The next step is running the container. By default the container is setup to run ksm
in shell mode.
docker run \
--rm \
-it \
-v $PWD:/wd --workdir /wd \
-v $HOME/.config:/etc/keeper -e KSM_INI_DIR=/etc/keeper \
keeper/keeper-secrets-manager-cli:latest
The docker run command.
Flags to remove the container when it is done running. That will prevent a build up of inactive containers.
Flag to enable interactions with the container.
Mounts the current directory as /wd inside of the container and then set the working directory to /wd inside of the container. This will allow anything written to /wd to be written to the current directory outside of the container. This is useful when downloading a file.
Mounts a directory where we want to store, or have, the keeper.ini file. Then we passing the environmental variable telling the CLI where to write or read the keeper.ini file.
Name of the image.
The docker run command can be a little too much to type each time. It is recommend that aliases be created.
$ alias ksm_shell='docker run --rm -it --workdir $PWD -v $PWD:$PWD -v $HOME/.config:/etc/keeper -e KSM_INI_DIR=/etc/keeper keeper/keeper-secrets-manager-cli:latest'
The above will launch the ksm shell.
The next alias is slightly different. At the end of the run command, the application ksm
is added. This will cause the ksm
not to start in shell mode.
$ alias ksm='docker run --rm -it --workdir $PWD -v $PWD:$PWD -v $HOME/.config:/etc/keeper -e KSM_INI_DIR=/etc/keeper keeper/keeper-secrets-manager-cli:latest ksm'
The KSM CLI docker includes a volume mount to both GLIBC (most Linux distributions) and MUSL (Alpine Linux) CLI binaries. The volume is /cli
. This directory can be mounted into another container using the volumes_from
in docker-compose or -v
from command line docker. The ksm executables exists in directory based on the version of C library your Linux distribution is using.
/cli/glibc/ksm
- For standard GLIBC distributions like Ubuntu, Debian, Fedora, and CentOS.
/cli/musl/ksm
- For Alpine Linux.
For example, the following is simple framework showing how to access the CLI binary.
---
version: "2"
services:
init:
image: keeper/keeper-secrets-manager-cli:latest
main:
image: ubuntu:latest
volumes_from:
- init:ro
command: [ '/cli/glibc/ksm', 'exec', 'printenv', 'MY_LOGIN' ]
environment:
KSM_CONFIG: ewog ... M09IemdQMnc9Igp9
MY_LOGIN: keeper://bf18xLR3aVut5eYy7oIZZZ/field/login
LC_ALL: C.UTF-8
LANG: C.UTF-8
depends_on:
init:
condition: service_completed_successfully
The init
service will load the CLI docker. The container will start, display a CLI splash screen, and then exit. Even though the container has stopped, the /cli
volume is still accessible.
The main
service will mount the CLI docker's volume under the directory /cli
using volumes_from
. The command
is overridden to run the GLIBC version of the KSM CLI. The command
is using the exec
function of the CLI. That will replace environment variables environment variable, that use the Keeper Notation, with a secret value. The exec
command, of the CLI, is running the printenv
application. That will print the environment variable, MY_LOGIN, that has been set to Keeper Notation, and has had its value replaced with a secret by the exec
command.
$ example : docker-compose up
[+] Running 2/0
⠿ Container example-init-1 Created 0.0s
⠿ Container example-main-1 Recreated 0.1s
Attaching to example-init-1, example-main-1
example-init-1 |
example-init-1 | ██╗ ██╗███████╗███╗ ███╗ ██████╗██╗ ██╗
example-init-1 | ██║ ██╔╝██╔════╝████╗ ████║ ██╔════╝██║ ██║
example-init-1 | █████╔╝ ███████╗██╔████╔██║ ██║ ██║ ██║
example-init-1 | ██╔═██╗ ╚════██║██║╚██╔╝██║ ██║ ██║ ██║
example-init-1 | ██║ ██╗███████║██║ ╚═╝ ██║ ╚██████╗███████╗██║
example-init-1 | ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═════╝╚══════╝╚═╝
example-init-1 |
example-init-1 | Current Version: 1.0.13
example-init-1 |
example-init-1 | Running in shell mode. Type 'quit' to exit.
example-init-1 |
example-init-1 exited with code 0
example-main-1 | john.smith@localhost
example-main-1 exited with code 0
Utilizing custom record types in the Keeper Secrets Manager CLI
The Keeper Secrets Manager CLI has a list of default record types that are available for use. The CLI also allows for the creation of records using custom record types.
In order to create records that use custom record types, the schema needs to be defined within the CLI. This is done by exporting the custom record type using Keeper Commander.
The below will export the "My Custom" record type, as JSON, to the file my_record_type.json
.
My Vault> rti --format json -lr "My Custom" --output my_record_type.json
The JSON file should be copied into a directory called record_type
. The location of the record_type
directory is the same as the location of the keeper.ini
file. The record_type
doesn't need to be in the same directory as the keeper.ini
, it just need to be in locations where the CLI will check for the keeper.ini
.
The path defined by the environment 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
An alternative directory can be set via the config command.
$ ksm config record-type-dir -d /path/to/my/record/type/schemas
Once the file is copied into the record_type
directory, it will be visible in the list of available record types.
$ ksm secret template record -l
Record Type
------------------------
login
bankAccount
address
...
My Custom
At this point the custom record type can be used to create a new record.
$ ksm secret add field --sf XXXX --rt "My Custom" -t "My Record" \
"login=jsmith" "password=XXXX" "url=https://localhost"
If the custom record type name contains spaces, the name will need to be surrounded by quotes.