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

# nora vars

> Flow 수준 변수. `{{name}}` 플레이스홀더 선언, 업데이트, 제거

Flow 변수는 Flow가 선언하는, 이름 있는 입력. 블록이 `{{name}}`으로 보간. 런타임 호출자가 값을 정함(API 페이로드, 채팅 UI, 스케줄로). 변수가 입력을 선언할 한 곳과 보간할 한 곳을 줌.

## 명령

| 명령                        | 설명                             |
| ------------------------- | ------------------------------ |
| `vars list`               | 활성 Flow의 선언된 변수 나열.            |
| `vars set <name> [flags]` | 변수 추가 또는 업데이트(기존에 shallow 병합). |
| `vars delete <name>`      | 변수 제거.                         |

변수 이름이 위치 인자, 예: `topic`, `customer_email`.

## `vars list`

```bash theme={null}
nora vars list
```

선언된 모든 변수를 한 줄에 하나씩 출력: 이름, 타입, 소스, 필수, 기본.

구조화 출력은 `--json`을 붙임.

## `vars set`

```bash theme={null}
nora vars set customer_email --source form --type string --required
```

### 플래그

| 플래그                      | 값                                                | 목적                                |
| ------------------------ | ------------------------------------------------ | --------------------------------- |
| `--source`               | `form`, `body_path`, `fixed`                     | 런타임에 값이 오는 곳.                     |
| `--type`                 | `string`, `number`, `boolean`, `object`, `array` | 타입 강제 + 검증.                       |
| `--label <text>`         |                                                  | 사람용 라벨(채팅 폼).                     |
| `--description <text>`   |                                                  | 한 줄 힌트.                           |
| `--path <a.b.c>`         |                                                  | `body_path` 소스: 트리거 본문의 JSONPath. |
| `--fixed-value <v>`      |                                                  | `fixed` 소스: 하드코딩 값.               |
| `--default-value <json>` |                                                  | 없을 때 기본. JSON 리터럴.                |
| `--required`             |                                                  | 안 정하면 실행 실패.                      |

넘긴 플래그만 기존 변수에 업데이트됨. set은 shallow 병합이지 replace가 아님. 필드를 초기화하려면 변수를 지우고 다시 만듦.

### 소스 설명

* **`form`** 채팅 트리거의 폼 UI에 뜸. 사용자가 채움.
* **`body_path`** 요청 본문의 JSON 경로에서 뽑음(웹훅과 API 트리거). `--path`로 지정.
* **`fixed`** 하드코딩. 실행마다 같은 값. 상수와 기능 플래그에 좋음.

## `vars delete`

```bash theme={null}
nora vars delete customer_email
```

선언 제거. `{{customer_email}}`을 참조하는 블록이 런타임에 실패. 먼저 감사할 것.

## 흔한 레시피

### 필수 사용자 입력 선언

```bash theme={null}
nora vars set topic \
  --source form \
  --type string \
  --label "What topic?" \
  --description "한 단어 주제 (예: 'billing')" \
  --required
```

채팅 트리거 폼에 필수 필드로 뜸.

### 웹훅 본문에서 뽑기

웹훅이 `{ "customer": { "email": "..." } }`를 POST 하면:

```bash theme={null}
nora vars set customer_email \
  --source body_path \
  --path customer.email \
  --type string \
  --required
```

블록이 `{{customer_email}}`을 보간하면 뽑은 값을 봄.

### 기능 플래그 스위치

```bash theme={null}
nora vars set enable_experimental_prompt \
  --source fixed \
  --type boolean \
  --fixed-value false \
  --description "assistant 프롬프트의 variant B를 켜는 토글"
```

준비되면 `vars set --fixed-value true`로 뒤집음. 블록 편집 없고, 재배포 없음(설정 스코프 변경이 바로 라이브).

### 한꺼번에 스냅샷·복원

`vars list --json`이 구조화돼 있어, vars를 git에 남기고 다른 워크스페이스에 다시 적용 가능:

```bash theme={null}
# 내보내기
nora vars list --json > vars.json

# 다른 워크스페이스에 다시 적용 (하나씩 루프)
jq -c '.[]' vars.json | while read v; do
  name=$(echo "$v" | jq -r '.name')
  # 구조화 필드를 --set-* 플래그로 다시 옮김
  # (한꺼번에는 보통 API로 스크립트 짜는 편이 쉬움)
done
```

간단치 않은 대량 이전은 `flows snapshot`/`apply`가 변수도 함께 옮김.

## 변수가 나타나는 곳

* **블록 콘텐츠** 텍스트 필드가 `{{name}}` 보간을 받는 어디든.
* **트리거 입력** 웹훅 `input_path`가 변수로 매핑됨. API 트리거가 받음.
* **채팅 폼 UI** `--source form` 변수가 실행 시작에 필드로 그려짐.
* **스케줄 트리거** `--source fixed` 값이 모든 스케줄 실행에 박힘.

## 변수와 버전 스코프

변수는 Flow에 속함(draft + published 함께). 변수 이름 변경은 Draft 편집. 라이브로 하려면 배포. `--fixed-value` 변경은 재배포 없이 바로 적용됨.