Keeper Secrets Manager CLI (ksm)

The KSM CLI is Keeper's machine-oriented secrets management tool. It retrieves secrets from the Keeper Vault without requiring a full user login - it uses Application + Client Device authentication with one-time access tokens.

KSM CLI 是 Keeper 面向机器的密钥管理工具，无需完整用户登录即可从 Keeper Vault 检索密钥，采用基于一次性访问令牌的应用+客户端设备认证机制。

Official documentation

官方文档

Secrets Manager (KSM) - overview, installation, and configuration
Keeper notation -
```
keeper://
```
URI syntax for fields, custom fields, and files

Secrets Manager (KSM) - 概述、安装与配置说明
Keeper notation - 用于字段、自定义字段和文件的
```
keeper://
```
URI 语法规范

When to Use KSM vs Commander

KSM 与 Commander 适用场景对比

Need	Tool
Retrieve a secret (password, key, cert)	`ksm`
Inject secrets into env vars at runtime	`ksm exec`
Template secrets into config files	`ksm interpolate`
List/search records shared with your app	`ksm secret list`
Create or update secret records	`ksm secret add` / `ksm secret update`
Sync secrets to AWS/Azure secret stores	`ksm sync`
Generate secure passwords	`ksm secret password`
Admin tasks (users, teams, roles, SSO)	Use `keeper` (Commander) - see keeper-admin skill
Create KSM Applications or Client Devices	Use `keeper` (Commander) - see keeper-admin skill
Manage PAM resources or rotation	Use `keeper` (Commander) - see keeper-admin skill

需求	工具
检索密钥（密码、密钥、证书）	`ksm`
运行时将密钥注入环境变量	`ksm exec`
将密钥模板化写入配置文件	`ksm interpolate`
列出/搜索共享给当前应用的记录	`ksm secret list`
创建或更新密钥记录	`ksm secret add` / `ksm secret update`
同步密钥到 AWS/Azure 密钥存储	`ksm sync`
生成安全密码	`ksm secret password`
管理员任务（用户、团队、角色、SSO）	使用 `keeper` （Commander）- 参见 keeper-admin 技能
创建 KSM 应用或客户端设备	使用 `keeper` （Commander）- 参见 keeper-admin 技能
管理 PAM 资源或轮转策略	使用 `keeper` （Commander）- 参见 keeper-admin 技能

Prerequisites

前置条件

KSM CLI installed:
```
pip install keeper-secrets-manager-cli
```
(or binary from GitHub releases)
A KSM Application created in Keeper Vault (or via Commander)
A Client Device initialized with a One-Time Access Token

Check installation:

ksm version

已安装 KSM CLI：
```
pip install keeper-secrets-manager-cli
```
（或从 GitHub Releases 下载二进制文件）
已在 Keeper Vault 中创建 KSM 应用（或通过 Commander 创建）
已使用一次性访问令牌初始化客户端设备

检查安装状态：

ksm version

Authentication & Profile Setup

认证与配置文件设置

KSM uses profile-based authentication. Credentials are stored in OS-native secure storage (macOS Keychain, Windows Credential Manager, Linux Secret Service) by default when installed with keyring support.

bash

undefined

KSM 采用基于配置文件的认证机制。默认安装 keyring 支持时，凭证会存储在操作系统原生安全存储中（macOS 钥匙串、Windows 凭证管理器、Linux Secret Service）。

bash

undefined

Install with keyring support (recommended)

安装带 keyring 支持的版本（推荐）

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

Initialize with One-Time Access Token (set KSM_CLI_TOKEN in your shell first—see Keeper profile docs; do not pass --token with a literal value)

使用一次性访问令牌初始化（请先在 shell 中设置 KSM_CLI_TOKEN，参见 Keeper 配置文件文档；不要直接传入明文 --token 参数）

ksm profile init

For containers/CI (no keyring available)

适用于容器/CI 场景（无可用 keyring）

pip install keeper-secrets-manager-cli

Prerequisite: export KSM_CLI_TOKEN from a trusted source, then:

前置条件：从可信来源导出 KSM_CLI_TOKEN，然后执行：

ksm profile init

Creates keeper.ini with 0600 permissions

会生成权限为 0600 的 keeper.ini 文件

Auto-create profile from environment variable (containers; see Keeper docs)

从环境变量自动创建配置文件（容器场景，参见 Keeper 文档）

ksm secret list # When KSM_TOKEN is set, profile may be auto-created on first use

undefined

ksm secret list # 当设置了 KSM_TOKEN 时，首次使用可能自动创建配置文件

undefined

Multiple Profiles

多配置文件管理

bash

ksm profile list

bash

ksm profile list

After exporting KSM_CLI_TOKEN for each setup step:

为每个环境导出对应 KSM_CLI_TOKEN 后执行：

ksm profile init --profile production ksm profile init --profile staging ksm secret list --profile production

undefined

ksm profile init --profile production ksm profile init --profile staging ksm secret list --profile production

undefined

Environment Variables

环境变量

Variable	Purpose
`KSM_CLI_TOKEN`	One-Time Access Token for `ksm profile init` without `--token` on the CLI (preferred)
`KSM_TOKEN`	One-Time Access Token for auto-init in some container flows (see Keeper docs)
`KSM_CONFIG`	Base64 config string (for K8s/containers)
`KSM_CONFIG_FILE`	Path to keeper.ini
`KSM_CLI_PROFILE`	Active profile name
`KSM_HOSTNAME`	Keeper host (US, EU, AU, JP, CA, US_GOV)

变量	用途
`KSM_CLI_TOKEN`	执行 `ksm profile init` 时无需在 CLI 传入 `--token` 的一次性访问令牌（推荐使用）
`KSM_TOKEN`	部分容器流程中用于自动初始化的一次性访问令牌（参见 Keeper 文档）
`KSM_CONFIG`	Base64 编码的配置字符串（适用于 K8s/容器场景）
`KSM_CONFIG_FILE`	keeper.ini 文件路径
`KSM_CLI_PROFILE`	活跃配置文件名称
`KSM_HOSTNAME`	Keeper 服务节点（US、EU、AU、JP、CA、US_GOV）

Core Commands

核心命令

List Secrets

列出密钥

bash

ksm secret list

bash

ksm secret list

Output:

输出示例：

UID Record Type Title

----------------------- -------------------- -------------------------

SNzjw8tM1HsXEzXERCJrNQ login Stripe API Key

8f8I-OqPV58o2r91wVgZ_A databaseCredentials Production MySQL Database

undefined

undefined

Get a Secret

获取密钥

bash

undefined

bash

undefined

Get full record as JSON

获取完整记录的 JSON 格式

ksm secret get -u <RECORD_UID> --json

Get a specific field value

获取指定字段的值

ksm secret get -u <RECORD_UID> -f password ksm secret get -u <RECORD_UID> -f login

Get with JSONPath query

使用 JSONPath 查询

ksm secret get -u <RECORD_UID> --json -q '$.fields[?@.type=="password"].value[0]'

Get by title

通过标题查询

ksm secret get -t "Production MySQL Database" -f password

Remove surrounding quotes from output (useful for scripting)

移除输出的前后引号（适用于脚本场景）

ksm secret get -u <RECORD_UID> -f password --raw

undefined

ksm secret get -u <RECORD_UID> -f password --raw

undefined

Keeper Notation

Keeper Notation is the URI format for referencing specific fields in records. See the Keeper notation documentation for full syntax and behavior.

Format:

keeper://<RECORD_UID>/field/<FIELD_TYPE>

or

keeper://<RECORD_UID>/custom_field/<LABEL>

text

keeper://SNzjw8tM1HsXEzXERCJrNQ/field/login
keeper://SNzjw8tM1HsXEzXERCJrNQ/field/password
keeper://8f8I-OqPV58o2r91wVgZ_A/field/host
keeper://8f8I-OqPV58o2r91wVgZ_A/custom_field/ConnectionString

For full notation syntax, read

references/keeper-notation.md

.

Keeper Notation 是用于引用记录中特定字段的 URI 格式。完整语法和行为参见 Keeper notation 文档。

格式：

keeper://<RECORD_UID>/field/<FIELD_TYPE>

或

keeper://<RECORD_UID>/custom_field/<LABEL>

text

keeper://SNzjw8tM1HsXEzXERCJrNQ/field/login
keeper://SNzjw8tM1HsXEzXERCJrNQ/field/password
keeper://8f8I-OqPV58o2r91wVgZ_A/field/host
keeper://8f8I-OqPV58o2r91wVgZ_A/custom_field/ConnectionString

完整 Notation 语法请参考

references/keeper-notation.md

。

Inject Secrets into Environment Variables (ksm exec)

将密钥注入环境变量（ksm exec）

This is the primary pattern for running applications with secrets. Any environment variable starting with

keeper://

gets replaced with the secret value before the command executes.

bash

undefined

这是为运行中的应用提供密钥的主流模式。任何以

keeper://

开头的环境变量都会在命令执行前被替换为对应的密钥值。

bash

undefined

Single secret

单个密钥场景

export DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password" ksm exec -- myapp

Inline

内联使用场景

DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password"
API_KEY="keeper://SNzjw8tM1HsXEzXERCJrNQ/field/password"
ksm exec -- ./start_server.sh

Docker example

Docker 示例

docker run
-e DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password"
-e KSM_CONFIG="<base64-config>"
myimage ksm exec -- /app/start.sh

undefined

docker run
-e DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password"
-e KSM_CONFIG="<base64-config>"
myimage ksm exec -- /app/start.sh

undefined

Interpolate Secrets into Config Files

将密钥插值到配置文件

bash

undefined

bash

undefined

Replace keeper:// placeholders in a template file

替换模板文件中的 keeper:// 占位符

ksm interpolate --in-file config.tmpl --out-file config.yaml

Example template (config.tmpl):

模板示例（config.tmpl）：

database:

host: keeper://8f8I-OqPV58o2r91wVgZ_A/field/host

password: keeper://8f8I-OqPV58o2r91wVgZ_A/field/password

undefined

undefined

Create & Update Secrets

创建与更新密钥

bash

undefined

bash

undefined

Create from editor

通过编辑器创建

ksm secret add editor --record-type login --title "New API Key"

Create from field arguments (supply sensitive field values from secure input, not sample literals)

通过字段参数创建（敏感字段值请从安全输入获取，不要使用示例明文）

ksm secret add field --record-type login --title "New API Key"
--field "login=admin"

Update a field (use secure input for password fields)

更新字段（密码字段请使用安全输入）

ksm secret update -u <RECORD_UID> --field "login=newuser"

Delete a record

删除记录

ksm secret delete -u <RECORD_UID>

undefined

ksm secret delete -u <RECORD_UID>

undefined

Generate Passwords

生成密码

bash

ksm secret password --length 32
ksm secret password --lc 8 --uc 8 -d 8 --sc 8

bash

ksm secret password --length 32
ksm secret password --lc 8 --uc 8 -d 8 --sc 8

Sync to Cloud Stores

同步到云存储

bash

undefined

bash

undefined

Sync to AWS Secrets Manager

同步到 AWS Secrets Manager

ksm sync --type aws_sm --credentials <AWS_CREDS_RECORD_UID>
--map <KEEPER_UID>=<AWS_SECRET_NAME>

Sync to Azure Key Vault

同步到 Azure Key Vault

ksm sync --type azure_kv --credentials <AZURE_CREDS_RECORD_UID>
--map <KEEPER_UID>=<AZURE_SECRET_NAME>

undefined

ksm sync --type azure_kv --credentials <AZURE_CREDS_RECORD_UID>
--map <KEEPER_UID>=<AZURE_SECRET_NAME>

undefined

Folder Management

文件夹管理

bash

ksm folder list
ksm folder get -u <FOLDER_UID>

bash

ksm folder list
ksm folder get -u <FOLDER_UID>

Guardrails

使用规范

NEVER paste, print, or log secret values into chat, code comments, or commit messages.
ALWAYS prefer
```
ksm exec
```
or
```
ksm interpolate
```
over writing secrets to disk or embedding them in source code.
If a command fails with authentication errors, re-initialize the profile with a fresh One-Time Access Token.
Record UIDs that start with
```
-
```
must be prefixed with
```
--
```
:
```
ksm secret get -- -AbCdEfGh
```
For commands that reference sensitive records, confirm the action with the user before executing destructive operations (delete, update).

切勿将密钥值粘贴、打印或记录到聊天、代码注释或提交信息中。
始终优先使用
```
ksm exec
```
或
```
ksm interpolate
```
，避免将密钥写入磁盘或嵌入源代码。
如果命令报认证错误，请使用新的一次性访问令牌重新初始化配置文件。
以
```
-
```
开头的记录 UID 需要添加
```
--
```
前缀：
```
ksm secret get -- -AbCdEfGh
```
对于涉及敏感记录的命令，执行删除、更新等破坏性操作前请先和用户确认。

Common Patterns

常用场景

CI/CD Pipeline (GitHub Actions)

CI/CD 流水线（GitHub Actions）

yaml

env:
  KSM_CONFIG: ${{ secrets.KSM_CONFIG }}
steps:
  - run: pip install keeper-secrets-manager-cli
  - run: |
      DB_PASSWORD="keeper://<UID>/field/password" \
      ksm exec -- ./deploy.sh

yaml

env:
  KSM_CONFIG: ${{ secrets.KSM_CONFIG }}
steps:
  - run: pip install keeper-secrets-manager-cli
  - run: |
      DB_PASSWORD="keeper://<UID>/field/password" \
      ksm exec -- ./deploy.sh

Docker / Kubernetes

bash

undefined

bash

undefined

Pass base64 config as env var

将 base64 编码的配置作为环境变量传入

kubectl create secret generic ksm-config
--from-literal=config=<BASE64_CONFIG>

In pod spec, mount KSM_CONFIG and use ksm exec as entrypoint

在 Pod 配置中挂载 KSM_CONFIG，使用 ksm exec 作为入口点

undefined

undefined

Local Development

本地开发

bash

undefined

bash

undefined

One-time setup

一次性初始化设置

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

Prerequisite: export KSM_CLI_TOKEN, then:

前置条件：导出 KSM_CLI_TOKEN 后执行：

ksm profile init

Daily use - run your app with secrets injected

日常使用 - 运行应用时自动注入密钥

DB_URL="keeper://<UID>/field/url"
API_KEY="keeper://<UID>/field/password"
ksm exec -- npm run dev

undefined

DB_URL="keeper://<UID>/field/url"
API_KEY="keeper://<UID>/field/password"
ksm exec -- npm run dev

undefined

keeper-secrets

Original

Translation

Keeper Secrets Manager CLI (ksm)

Keeper Secrets Manager CLI (ksm)

Official documentation

官方文档

When to Use KSM vs Commander

KSM 与 Commander 适用场景对比

Prerequisites

前置条件

Authentication & Profile Setup

认证与配置文件设置

Install with keyring support (recommended)

安装带 keyring 支持的版本（推荐）

Initialize with One-Time Access Token (set KSM_CLI_TOKEN in your shell first—see Keeper profile docs; do not pass --token with a literal value)

使用一次性访问令牌初始化（请先在 shell 中设置 KSM_CLI_TOKEN，参见 Keeper 配置文件文档；不要直接传入明文 --token 参数）

For containers/CI (no keyring available)

适用于容器/CI 场景（无可用 keyring）

Prerequisite: export KSM_CLI_TOKEN from a trusted source, then:

前置条件：从可信来源导出 KSM_CLI_TOKEN，然后执行：

Creates keeper.ini with 0600 permissions

会生成权限为 0600 的 keeper.ini 文件

Auto-create profile from environment variable (containers; see Keeper docs)

从环境变量自动创建配置文件（容器场景，参见 Keeper 文档）

Multiple Profiles

多配置文件管理

After exporting KSM_CLI_TOKEN for each setup step:

为每个环境导出对应 KSM_CLI_TOKEN 后执行：

Environment Variables

环境变量

Core Commands

核心命令

List Secrets

列出密钥

Output:

输出示例：

UID Record Type Title

UID Record Type Title

----------------------- -------------------- -------------------------

----------------------- -------------------- -------------------------

SNzjw8tM1HsXEzXERCJrNQ login Stripe API Key

SNzjw8tM1HsXEzXERCJrNQ login Stripe API Key

8f8I-OqPV58o2r91wVgZ_A databaseCredentials Production MySQL Database

8f8I-OqPV58o2r91wVgZ_A databaseCredentials Production MySQL Database

Get a Secret

获取密钥

Get full record as JSON

获取完整记录的 JSON 格式

Get a specific field value

获取指定字段的值

Get with JSONPath query

使用 JSONPath 查询

Get by title

通过标题查询

Remove surrounding quotes from output (useful for scripting)

移除输出的前后引号（适用于脚本场景）

Keeper Notation

Keeper Notation

Inject Secrets into Environment Variables (ksm exec)

将密钥注入环境变量（ksm exec）

Single secret

单个密钥场景

Inline

内联使用场景

Docker example

Docker 示例

Interpolate Secrets into Config Files

将密钥插值到配置文件

Replace keeper:// placeholders in a template file

替换模板文件中的 keeper:// 占位符

Example template (config.tmpl):

模板示例（config.tmpl）：

database:

database:

host: keeper://8f8I-OqPV58o2r91wVgZ_A/field/host

host: keeper://8f8I-OqPV58o2r91wVgZ_A/field/host

password: keeper://8f8I-OqPV58o2r91wVgZ_A/field/password

password: keeper://8f8I-OqPV58o2r91wVgZ_A/field/password

Create & Update Secrets