keeper-secrets

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.

Official documentation

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

When to Use KSM vs 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

Prerequisites

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

Check installation: ksm version

Workflow

1. ALWAYS use dedicated TMUX session for all KSM related operations.
2. While configuring KSM for first time, pre-configure the KSM init command, Ask use input for one time token and inject that in pre-configured tmux session.
3. ALWAYS ask the user inputs for REQUIRED fields, DONT GUESS REQUIRED fields.
4. Search or inspect metadata first, then retrieve only the exact requested field, do not expose any sensitive data.
5. Prefer secret injection or one-command environment scoping over writing secrets to disk.
6. If syntax differs from expectation, fall back to --help and Keeper docs immediately.
7. ALWAYS ask confirmation from users for any delete operations.

REQUIRED tmux session

The shell tool uses a fresh TTY per command. To preserve Keeper interactive context, authentication state, and MFA prompts, run interactive Keeper commands or secrets manager command inside a dedicated tmux session.

Example pattern:

SOCKET_DIR="${TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/keeper-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/keeper-commander.sock"
SESSION="keeper-auth-$(date +%Y%m%d-%H%M%S)"

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "ksm shell || bash" Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -120

Then drive the session carefully:

tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -l -- "whoami"
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -120

Kill the tmux session when the task is complete unless the user wants a persistent Keeper shell.

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.

# Install with keyring support (recommended)
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)
ksm profile init

# For containers/CI (no keyring available)
pip install keeper-secrets-manager-cli
# Prerequisite: export KSM_CLI_TOKEN from a trusted source, then:
ksm profile init
# Creates keeper.ini with 0600 permissions

# Auto-create profile from environment variable (containers; see Keeper docs)
ksm secret list  # When KSM_TOKEN is set, profile may be auto-created on first use

Multiple Profiles

ksm profile list
# After exporting KSM_CLI_TOKEN for each setup step:
ksm profile init --profile production
ksm profile init --profile staging
ksm secret list --profile production

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)

Core Commands

List Secrets

ksm secret list
# Output:
# UID                     Record Type          Title
# ----------------------- -------------------- -------------------------
# SNzjw8tM1HsXEzXERCJrNQ login                Stripe API Key
# 8f8I-OqPV58o2r91wVgZ_A databaseCredentials  Production MySQL Database

Get a Secret

# Get full record as 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
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

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>

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.

Inject Secrets into Environment Variables (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.

# 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 run \
  -e DB_PASSWORD="keeper://8f8I-OqPV58o2r91wVgZ_A/field/password" \
  -e KSM_CONFIG="<base64-config>" \
  myimage ksm exec -- /app/start.sh

Interpolate Secrets into Config Files

# Replace keeper:// placeholders in a template file
ksm interpolate --in-file config.tmpl --out-file config.yaml

# Example template (config.tmpl):
# database:
#   host: keeper://8f8I-OqPV58o2r91wVgZ_A/field/host
#   password: keeper://8f8I-OqPV58o2r91wVgZ_A/field/password

Create & Update Secrets

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

Generate Passwords

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

Sync to Cloud Stores

# Sync to AWS Secrets Manager
ksm sync --type aws_sm --credentials <AWS_CREDS_RECORD_UID> \
  --map <KEEPER_UID>=<AWS_SECRET_NAME>

# Sync to Azure Key Vault
ksm sync --type azure_kv --credentials <AZURE_CREDS_RECORD_UID> \
  --map <KEEPER_UID>=<AZURE_SECRET_NAME>

Folder Management

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

Common Patterns

CI/CD Pipeline (GitHub Actions)

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

# Pass base64 config as env var
kubectl create secret generic ksm-config \
  --from-literal=config=<BASE64_CONFIG>

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

Local Development

# One-time setup
pip install keeper-secrets-manager-cli[keyring]
# Prerequisite: export KSM_CLI_TOKEN, then:
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