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