> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therefrain.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 変数

> 手順書のテンプレート変数の定義と解決。

## 概要

変数を使って手順書をパラメータ化できます。`variables` セクションで定義し、ステップの値で `{{variableName}}` 構文で参照します。

## 定義

```yaml theme={null}
variables:
  email:
    source: prompt
    description: "ログイン用メールアドレス"
    required: true
  password:
    source: prompt
    description: "ログインパスワード"
    required: true
    sensitive: true
  baseUrl:
    source: fixed
    value: "https://staging.example.com"
  timestamp:
    source: expression
    expression: "{{Date.now()}}"
  region:
    source: env
    envKey: "AWS_REGION"
```

## 変数フィールド

| フィールド         | 型              | デフォルト   | 説明                         |
| ------------- | -------------- | ------- | -------------------------- |
| `source`      | VariableSource | —       | 変数の解決方法（下記参照）              |
| `description` | string         | —       | 人が読める説明                    |
| `required`    | boolean        | `true`  | 実行前に解決が必要か                 |
| `sensitive`   | boolean        | `false` | ログやレポートで値をマスク              |
| `value`       | string         | —       | 静的な値（`fixed` ソース用）         |
| `expression`  | string         | —       | テンプレート式（`expression` ソース用） |
| `envKey`      | string         | —       | 環境変数名（`env` ソース用）          |

## 変数ソース

| ソース          | 説明                            | 使用例                                    |
| ------------ | ----------------------------- | -------------------------------------- |
| `prompt`     | 実行時にユーザーに入力を求める（CLI のみ）       | ログイン認証情報                               |
| `fixed`      | ハードコードされた静的値                  | ベース URL、定数                             |
| `context`    | コンテキスト Markdown ファイルから AI が抽出 | `--context` で記述された値                    |
| `env`        | 環境変数から読み込み                    | `AWS_REGION`, `APP_URL`                |
| `expression` | テンプレート式を評価                    | `{{Date.now()}}`, `{{captured_value}}` |
| `data`       | CSV/JSON データファイルから読み込み（バッチ実行） | 行ごとの値                                  |

## 解決優先順位

実行時、変数は **secrets > data > context > env > expression > fixed > prompt** の優先順位で解決されます。最初にマッチした値が使用されます。

各ソースの詳細は[変数とシークレット: 解決優先順位](/ja/guides/variables-and-secrets#解決優先順位)を参照してください。

<Note>
  SDK モードでは `prompt` ソースは使用できません。未解決の必須変数はエラーになります。
</Note>

## ステップでの変数の使用

`{{variableName}}` で任意の文字列フィールドから変数を参照できます：

```yaml theme={null}
steps:
  - ordinal: 0
    description: "{{baseUrl}} に遷移"
    action:
      type: navigate
      url: "{{baseUrl}}/login"
    url: "{{baseUrl}}/login"
    riskLevel: low
    requiresConfirmation: false
  - ordinal: 1
    description: "メールアドレスを入力"
    action:
      type: input
      value: "{{email}}"
      selector:
        tagName: input
        inputType: email
    url: "{{baseUrl}}/login"
    riskLevel: low
    requiresConfirmation: false
```

## 機密変数

`sensitive: true` を設定すると、ログやレポートに値が表示されなくなります：

```yaml theme={null}
variables:
  password:
    source: prompt
    description: "ログインパスワード"
    sensitive: true
```

`--secrets`（CLI）または `secrets` オプション（SDK）で渡した値は自動的に sensitive として扱われます。

## `data` ソースによるバッチ実行

`--data` 使用時は、`dataSource` で変数名と CSV/JSON カラムをマッピングします：

```yaml theme={null}
variables:
  email:
    source: data
    description: "CSV からのユーザーメールアドレス"
  name:
    source: data
    description: "CSV からのユーザー名"

dataSource:
  mapping:
    email: "Email"      # CSV カラムヘッダー
    name: "Full Name"   # CSV カラムヘッダー
```

```bash theme={null}
npx @refrainai/cli execute -- \
  --runbook ./flow.yaml \
  --data ./users.csv
```

手順書はデータの各行に対して1回ずつ実行され、各行の値で変数が設定されます。