# Interpolate Command

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

{% hint style="danger" %}
**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`.
{% endhint %}

**Safe usage options:**

1. **RECOMMENDED** Write to file instead of eval:

   ```bash
   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:

   ```bash
   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`

```bash
# 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:**

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

**Result:** `config.env` (with secure 0600 permissions)

```bash
# 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`:

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

**Solution:** Use `ksm interpolate` instead.

**Example 1:** Write to file (RECOMMENDED)

```bash
$ 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`)

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

{% hint style="warning" %}
Only use `--allow-unsafe-for-eval` if you fully trust all users with Keeper write access. See Security Features section.
{% endhint %}

#### Default Values and Transformations

**Template with defaults and transforms:**

```bash
# 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:**

```bash
$ 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:**

```bash
cat config.template | ksm interpolate > config.env
```

**Process multiple files:**

```bash
ksm interpolate *.template
```

**In-place editing with backup:**

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

**Dry run:**

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/interpolate-command.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.