# Secrets Manager CLI
## 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
{% hint style="info" %}
Keeper provides 2 different CLI tools. The Secrets Manager CLI is targeted to machine-based secrets management. The [Commander CLI](https://docs.keeper.io/en/keeperpam/commander-cli) is more focused on administrative capabilities.
{% endhint %}
### 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](https://docs.keeper.io/en/keeperpam/secrets-manager/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](https://github.com/Keeper-Security/secrets-manager/releases?q=cli\&expanded=true). Download the installer based on your operating system.
:arrow\_down: [**Download the Secrets Manager CLI Binary**](https://github.com/Keeper-Security/secrets-manager/releases?q=cli\&expanded=true)
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](https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/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
#### 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](https://github.com/Keeper-Security/secrets-manager/tree/master/integration/keeper_secrets_manager_cli).
### 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")
```bash
ksm
```
```markup
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 `**
To get help on a particular command, run:
`ksm --help`
To get help on a sub-command, run:
`ksm --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 `
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 ` use specified configuration profile
`-o, --output <{stdout, stderr, filename}>` Sets the output destination
* `stdout` - Print to stdout (default)
* `stderr` - Print to stderr
* `` - 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-"
security delete-generic-password -s "KSM-cli" -a "ksm-cli-profile--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-
cmdkey /delete:KSM-cli:ksm-cli-profile--integrity
```
**Using command line (CMD):**
```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-
secret-tool clear service KSM-cli username ksm-cli-profile--integrity
```