init command

Description: Initialize a one time access token

Parameters:

Sub-command to run

format: ksm init <sub-command>

Sub-Commands:

default

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==

k8s

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

profile command

Description: 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:

init

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

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

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

Method 1: EC2 instance role

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

Method 2: AWS profile credentials

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

Method 3: AWS custom keys

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.

Finishing the KSM CLI setup

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

Additional setup options

--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

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

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

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

active

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.

Profiles within Containers

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.

Default INI Filename

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.

folder command

Description: 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:

list

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"
    }
]

add

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

update

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

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

exec command

To 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>

Example Linux bash 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

Example Windows batch file

C:\> ksm exec -- my_script.bat

Example PowerShell script

PS C:\> ksm exec -- powershell my_script.ps1

Environment Variable Replacement

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"

Example Shell Script

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

version command

Description:

View 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

Example:

$ 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

Overview

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.

sync command

Description: 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.

Sync Types

Select an external provider below to learn more about the integration.

Overview

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.

Core Features

• 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

Application and Client Device Setup

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.

Secrets Manager CLI Installation

The KSM CLI is available as a binary application for Windows/Mac/Linux or a pip3 install for any Python environment.

Binary Install Method

The latest binary release can be found on the GitHub repository. Download the installer based on your operating system.

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.

Docker Install Method

See the Docker Container page for installation and setup from Keeper's Docker image.

Pip3 and Python3 Install Method

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.

Installing KSM using virtualenv

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

Source Code

Find the Keeper Secrets Manager CLI source code in the GitHub repository.

Usage

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.

Create a local Client Device

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.

Execution of Commands

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

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.

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:

config command

Description: Configure the CLI debug output

Parameters:

Sub-command to run

format: ksm config <sub-command>

Sub-Commands:

color

ksm config color <--enable | --disable>

Options:

--enable Turn on color display

--disable Turn off color display

Example:

$ ksm config color --disable
$ ksm config show
 Config Item            Value
 ---------------------- --------------
 Color Enabled          False

cache

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>

Options:

--enable Turn on record caching

--disable Turn off record caching

Example:

$ ksm config cache --enable
$ ksm config show
 Config Item            Value
 ---------------------- -----------
 Cache Enabled          True

record-type-dir

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

Example:

$ ksm config record-type-dir -d /path/to/directory
$ ksm config show
 Config Item            Value
 ---------------------- -----------
 Record Type Directory  /path/to/directory

editor

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

Application Options:

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.

Example:

 ksm config editor --app Code --blocking --proces-name code.exe
$ ksm config show
 Config Item            Value
 ---------------------- -----------
 Editor                 Code (code.exe)
 Editor Blocking        True

show

ksm config show

Example:

$ 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

secret command

Description: Retrieve secrets from the vault and parse the response.

Parameters:

Sub-command to run

format: ksm secret <sub-command>

Sub-Commands:

list

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

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

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.

Editor

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.

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"]

File

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

Field

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

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
    }
]

clone

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

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

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

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

template

Display record or field type template information.

record

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

field

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
}

notation

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.

totp

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

password

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

Record UIDs Starting With "-"

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

Getting the image

The first step is pulling the CLI image.

Running a container

The next step is running the container. By default the container is setup to run ksm in shell mode.

1. The docker run command.

2. Flags to remove the container when it is done running. That will prevent a build up of inactive containers.

3. Flag to enable interactions with the container.

4. 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.

5. 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.

6. Name of the image.

Aliasing

The docker run command can be a little too much to type each time. It is recommend that aliases be created.

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.

Built-in Binaries

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.

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.