Secrets Manager CLI

The Secrets Manager CLI provides shell access to vault secrets

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

Keeper provides 2 different CLI tools. The Secrets Manager CLI is targeted to machine-based secrets management. The Commander CLI is more focused on administrative capabilities.

Secure Configuration Storage

The KSM CLI stores configuration securely in your operating system's native secure storage manager by default. This provides enhanced security compared to storing credentials in configuration files.

How It Works

Operating System	Secure Storage Backend
macOS	Keychain
Windows	Windows Credential Manager
Linux	Secret Service (GNOME Keyring, KWallet)

When you initialize a profile, your credentials are automatically stored in the OS-native secure storage. No keeper.ini file is created unless you explicitly request file-based storage.

Benefits of OS-Native Storage

• Enhanced Security: Credentials are encrypted using OS-level encryption

• No Plain-text Files: Eliminates the risk of accidentally exposing credential files

• Automatic Protection: Leverages existing OS security features (biometrics, system passwords)

• Multi-profile Support: Easily manage multiple KSM profiles securely

Note: OS-native secure storage requires the optional keyring extra: pip3 install keeper-secrets-manager-cli[keyring]. Without it, profiles fall back to keeper.ini file-based storage.

---

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.

⬇️ 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.

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.10 or higher 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 more information, see https://pypi.org/project/keeper-secrets-manager-cli/

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

Installing optional extras

The KSM CLI supports optional extras for additional functionality:

OS-native secure storage (recommended):

pip3 install keeper-secrets-manager-cli[keyring]

Note: The keyring extra enables storing profiles in macOS Keychain, Windows Credential Manager, or Linux Secret Service. Without it, profiles fall back to file-based storage with 0600 permissions.

AWS Secrets Manager sync support:

pip3 install keeper-secrets-manager-cli[aws]

Note: The aws extra (boto3) is required for the ksm sync command when syncing to AWS Secrets Manager. It is not installed by default.

Install all extras:

pip3 install keeper-secrets-manager-cli[keyring,aws]

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.
  --log-level [DEBUG|INFO|WARNING|ERROR]
                                 Debug log level.
  --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       Commands for secrets
  folder       Manage folders
  interpolate  Replace KSM notation placeholders in text files
  sync         Sync selected keys from Keeper vault to secure cloud based key value store
  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.

Default Behavior: For OS-Native Secure Storage

By default, configuration is stored in your operating system’s native secure storage when the KSM CLI is installed with keyring support pip3 install keeper-secrets-manager-cli[keyring]:

ksm profile init XX:XXXX

Example output (macOS):

Added profile _default to macOS Keychain

Example output (Windows):

Added profile _default to Windows Credential Manager

Example output (Linux):

Added profile _default to system keyring

After initialization, you can immediately use the CLI:

ksm secret list

Alternative: File-Based Storage

If you prefer to store configuration in a configuration file , use the --ini-file option:

ksm profile init --ini-file keeper.ini --token XX:XXXX

This creates a keeper.ini file with restricted permissions (0600 - owner-only access).

For Containerized / Serverless Environments

For containerized, serverless, or headless environments (such as Docker, Kubernetes, CI/CD pipelines, or cloud functions), install the KSM CLI without keyring support:

pip3 install keeper-secrets-manager-cli

Initialize the profile using the token:

ksm profile init --token XX:XXXX

This will create a keeper.ini configuration file, which is suitable for environments where OS-native secure storage is not available.

---

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	Description
KSM_CONFIG	Base64-encoded KSM configuration. If set, the CLI loads config from this variable — no profile init required.
KSM_TOKEN	One-time access token. If set and no INI config is found, a default profile is auto-created (for container use).
KSM_CLI_TOKEN	One-time access token for ksm profile init. Avoids exposing the token on the command line.
KSM_INI_FILE	Override the default INI filename (keeper.ini).
KSM_INI_DIR	Override the directory where keeper.ini is searched for and created.
KSM_CLI_PROFILE	Set the active profile name (default: _default).
KSM_HOSTNAME	Server region for profile initialization (default: US). Set before running ksm profile init.
KSM_CONFIG_KEYRING_UTILITY_PATH	Path to an alternative keyring utility (e.g., lkru) for Linux headless environments.

---

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

Command	Description
profile	Manage local client device profiles
secret	Manage secrets (list, get, update, delete, etc.)
folder	Manage folders
exec	Wrap an application and inject secrets as environment variables
interpolate	Replace KSM notation placeholders in text files
sync	Sync secrets to AWS, Azure, GCP, or JSON
config	Configure the CLI tool settings
init	Initialize a configuration file for integrations (k8s, etc.)
version	Show version information
shell	Run in interactive 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:ProgramData/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.

Deleting Keyring Configuration

To completely remove KSM configuration from your system's secure storage, follow the instructions for your operating system.

macOS (Keychain)

Using Keychain Access app:

1. Open Keychain Access (Applications → Utilities → Keychain Access)

2. In the search box, type KSM-cli

3. Select all matching entries

4. Right-click and choose Delete

Using command line:

# List KSM entries
security find-generic-password -s "KSM-cli" 2>/dev/null

# Delete specific entries (repeat for each profile)
security delete-generic-password -s "KSM-cli" -a "ksm-cli-common"
security delete-generic-password -s "KSM-cli" -a "ksm-cli-common-integrity"
security delete-generic-password -s "KSM-cli" -a "ksm-cli-profile-_default"
security delete-generic-password -s "KSM-cli" -a "ksm-cli-profile-_default-integrity"
security delete-generic-password -s "KSM-cli" -a "ksm-cli-profile-<profile_name>"
security delete-generic-password -s "KSM-cli" -a "ksm-cli-profile-<profile_name>-integrity"

Windows (Credential Manager)

Using Credential Manager UI:

1. Open Control Panel → User Accounts → Credential Manager

2. Click on Windows Credentials

3. Look for entries starting with KSM-cli

4. Click on each entry and select Remove

Using command line (PowerShell):

# List credentials
cmdkey /list | Select-String "KSM-cli"

# Delete specific credentials
cmdkey /delete:KSM-cli:ksm-cli-common
cmdkey /delete:KSM-cli:ksm-cli-common-integrity
cmdkey /delete:KSM-cli:ksm-cli-profile-_default
cmdkey /delete:KSM-cli:ksm-cli-profile-_default-integrity
cmdkey /delete:KSM-cli:ksm-cli-profile-<profile_name>
cmdkey /delete:KSM-cli:ksm-cli-profile-<profile_name>-integrity

Using command line (CMD):

cmdkey /delete:KSM-cli:ksm-cli-common
cmdkey /delete:KSM-cli:ksm-cli-common-integrity
cmdkey /delete:KSM-cli:ksm-cli-profile-_default
cmdkey /delete:KSM-cli:ksm-cli-profile-_default-integrity

Linux (Secret Service / GNOME Keyring)

Using Seahorse (GNOME Keyring GUI):

1. Open Passwords and Keys (Seahorse)

2. Look under Login keyring

3. Search for entries containing KSM-cli

4. Right-click and delete each entry

Using secret-tool (command line):

# Search for KSM entries
secret-tool search service KSM-cli 2>/dev/null

# Delete entries
secret-tool clear service KSM-cli username ksm-cli-common
secret-tool clear service KSM-cli username ksm-cli-common-integrity
secret-tool clear service KSM-cli username ksm-cli-profile-_default
secret-tool clear service KSM-cli username ksm-cli-profile-_default-integrity
secret-tool clear service KSM-cli username ksm-cli-profile-<profile_name>
secret-tool clear service KSM-cli username ksm-cli-profile-<profile_name>-integrity