Interpolate Command

Replace Keeper notation in template files with actual secret values from your Keeper vault.

interpolate command

Description: Replace Keeper notation in template files with actual secret values from your Keeper vault. The interpolate command reads template files containing Keeper notation references, fetches the secrets from your vault, and replaces the notation with actual values. This enables secure configuration file generation for deployments, CI/CD pipelines, and shell environment setup.

Parameters:

format: ksm interpolate [INPUT_FILE...] [OPTIONS]

Options:

Option	Short	Description
INPUT_FILE		Input template file(s) to process. If omitted, reads from stdin
--output-file PATH	-o	Write output to specified file instead of stdout
--in-place	-w	Edit files in place (modifies original files)
--backup-suffix SUFFIX	-b	Backup suffix when using -w (default: .bak)
--dry-run	-n	Show what would be replaced without making changes
--verbose	-v	Verbose output showing each replacement
--continue	-C	Continue processing on errors
--validate		Ensure all notations were successfully resolved
--allow-unsafe-for-eval		[RISKY] Allow secrets containing shell metacharacters (required for eval/source)

Common flags also apply: --profile-name, --ini-file, --color/--no-color, --cache/--no-cache

---

Keeper Notation Format

The interpolate command supports extended Keeper notation with default values and transformations:

Basic notation:

keeper://RECORD_UID/field/FIELD_NAME
keeper://RECORD_UID/custom_field/CUSTOM_FIELD_NAME
keeper://RECORD_UID/file/FILE_NAME

With default values (shell-style :- syntax):

keeper://RECORD_UID/field/FIELD_NAME:-default_value

With transformations (pipe | operator):

keeper://RECORD_UID/field/FIELD_NAME|transform
keeper://RECORD_UID/field/FIELD_NAME:-default|transform

Available transformations: base64, base64url, urlencode, urlencodeplus, upper, lower, trim, sha256, md5

---

Security Features

CRITICAL: Shell Injection Protection

By default, the command blocks secrets containing shell metacharacters (newlines, backticks, $, ;, |, &, >, <) to prevent command injection attacks when using eval or source.

Safe usage options:

1. RECOMMENDED Write to file instead of eval:

   ksm interpolate secrets.env --output-file /tmp/secrets.env
   source /tmp/secrets.env && rm /tmp/secrets.env

2. RISKY Use --allow-unsafe-for-eval flag only if you fully trust all users with Keeper write access:

   eval "$(ksm interpolate secrets.env --allow-unsafe-for-eval)"

Additional security features:

• Output files created with 0600 permissions (owner read/write only)

• Atomic file operations prevent partial writes

• Git safety warnings for files not in .gitignore

• Path traversal attack prevention

---

Examples

Basic File Processing

Template file: config.env.template

# Database configuration
DB_HOST=keeper://MyDatabaseCreds/field/host
DB_PORT=keeper://MyDatabaseCreds/field/port
DB_PASSWORD=keeper://MyDatabaseCreds/field/password

# API configuration
API_KEY=keeper://ApiCredentials/custom_field/api_key

Process the template:

$ ksm interpolate config.env.template --output-file config.env

Result: config.env (with secure 0600 permissions)

# Database configuration
DB_HOST=db.example.com
DB_PORT=5432
DB_PASSWORD=MySecurePassword123

# API configuration
API_KEY=sk-1234567890abcdef

Shell Built-ins

Problem: The ksm exec command cannot execute shell built-ins like source:

$ ksm exec -- source .env
Error: No such file or directory: 'source'

Solution: Use ksm interpolate instead.

Example 1: Write to file (RECOMMENDED)

$ ksm interpolate secrets.env --output-file /tmp/secrets.env
$ source /tmp/secrets.env
$ rm /tmp/secrets.env

Example 2: Direct eval (requires --allow-unsafe-for-eval)

$ eval "$(ksm interpolate secrets.env --allow-unsafe-for-eval)"

Only use --allow-unsafe-for-eval if you fully trust all users with Keeper write access. See Security Features section.

Default Values and Transformations

Template with defaults and transforms:

# Use production values if available, otherwise defaults
DB_HOST=keeper://ProdDB/field/host:-localhost
DB_PORT=keeper://ProdDB/field/port:-5432

# Base64-encoded JWT secret
JWT_SECRET=keeper://Auth/field/secret|base64

# URL-encoded callback parameter
CALLBACK_URL=keeper://Config/field/callback|urlencode

# Combined: default + transformation
ENCODED_KEY=keeper://API/field/key:-default_value|base64

Process:

$ ksm interpolate app.env.template --output-file app.env

If secrets don't exist or are inaccessible, default values are used automatically. Transformations are applied to both secrets and default values.

Additional Usage Patterns

Process from stdin:

cat config.template | ksm interpolate > config.env

Process multiple files:

ksm interpolate *.template

In-place editing with backup:

ksm interpolate --in-place --backup-suffix .bak config.env

Dry run:

ksm interpolate --dry-run --verbose production.env.template