# interpolateコマンド

### `interpolate` コマンド

**説明:** テンプレートに書かれたKeeper表記法を、ボルト上のシークレット実値に置き換えます。`interpolate` コマンドは表記法の参照を含むファイルを読み、ボルトから値を取り出して参照を実値に差し替えます。デプロイやCI/CD、シェル用の環境変数ファイルなど、安全に構成ファイルを用意する用途向けです。

**パラメータ:**

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

**オプション:**

| オプション                     | 短縮形  | 説明                                                                |
| ------------------------- | ---- | ----------------------------------------------------------------- |
| `INPUT_FILE`              |      | 入力テンプレート。未指定時は標準入力から読み取り                                          |
| `--output-file PATH`      | `-o` | 標準出力ではなく指定ファイルへ書き出し                                               |
| `--in-place`              | `-w` | インプレース編集 (元ファイルを上書き)                                              |
| `--backup-suffix SUFFIX`  | `-b` | `-w` 使用時のバックアップ拡張子 (既定: `.bak`)                                   |
| `--dry-run`               | `-n` | 変更せず置換内容のみ表示                                                      |
| `--verbose`               | `-v` | 置換ごとの詳細出力                                                         |
| `--continue`              | `-C` | エラーが出ても処理継続                                                       |
| `--validate`              |      | 表記法がすべて解決済みであることの検証                                               |
| `--allow-unsafe-for-eval` |      | **\[危険]** `eval` / `source` 用にシェルメタ文字を含むシークレットを許可 (インジェクションリスクあり) |

**共通フラグ:** `--profile-name`, `--ini-file`, `--color/--no-color`, `--cache/--no-cache`

***

### Keeper表記法の形式

`interpolate` コマンドは、既定値や変換を伴う拡張Keeper表記法に対応します。

**基本的な表記:**

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

**既定値付き（シェル風の `:-` 構文）:**

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

**変換付き（パイプ `|` 演算子）:**

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

**利用できる変換:** `base64`, `base64url`, `urlencode`, `urlencodeplus`, `upper`, `lower`, `trim`, `sha256`, `md5`

***

### セキュリティ上の挙動

{% hint style="danger" %}
**重大: シェルインジェクション対策**

既定では、`eval` や `source` と併用したときのコマンドインジェクションを防ぐため、改行、バッククォート、`$`, `;`, `|`, `&`, `>`, `<` などのシェルメタ文字を含むシークレットは受け付けません。
{% endhint %}

**安全な使い方:**

1. **推奨:** ファイルへ書き出してから `source` する。

   ```bash
   ksm interpolate secrets.env --output-file /tmp/secrets.env
   source /tmp/secrets.env && rm /tmp/secrets.env
   ```
2. **危険:** Keeperへの書き込み権限を持つユーザーをすべて信頼できる場合に限り、`--allow-unsafe-for-eval` を使う。

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

**その他のセキュリティ機能:**

* 出力ファイルは権限 `0600` (所有者のみ読み書き)
* 原子書き込みで途中状態のファイルを避ける
* `.gitignore` に含まれないファイルに対するGitの警告
* パストラバーサル対策

***

### 例

#### 基本的なファイル処理

**テンプレート:** `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
```

**テンプレートを処理:**

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

**結果:** `config.env` (権限 `0600`、所有者のみ読み書き)

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

# API configuration
API_KEY=sk-1234567890abcdef
```

#### シェル組み込みコマンド

**課題:** `ksm exec` では `source` などのシェル組み込みコマンドは実行できません。

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

**解決:** 代わりに `ksm interpolate` を使います。

**例1:** ファイルへ書き出す (推奨)

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

**例2:** 直接 `eval`（`--allow-unsafe-for-eval` が必要）

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

{% hint style="warning" %}
`--allow-unsafe-for-eval` は、Keeperへの書き込み権限を持つユーザーをすべて信頼できる場合にのみ使ってください。「セキュリティ上の挙動」をご参照ください。
{% endhint %}

#### 既定値と変換

**既定値と変換を含むテンプレート:**

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

**実行例**

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

シークレットが存在しないか参照できないときは、既定値が自動的に使われます。変換は取得値と既定値の両方に適用されます。

#### その他の使い方

**標準入力から処理:**

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

**複数ファイルを処理:**

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

**バックアップ付きインプレース編集:**

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

**ドライラン (変更なしで内容確認):**

```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/keeperpam/jp/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.