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

# 파이핑·시크릿

> 시크릿 값·파일 본문·stdin 을 CLI 에 안전하게 공급하는 방법.

많은 CLI 명령이 될 수 있는 콘텐츠 받음:

* 민감 (API 키, 토큰, DB URL).
* 큼 (멀티라인 프롬프트, 마크다운 노트, JSON 페이로드).
* 다른 프로세스에서 옴 (이전 명령의 출력).

CLI 가 모든 서브커맨드에 걸쳐 일관된 입력 신택스 지원.

## 세 입력 모드

CLI 가 시크릿·파일·파이프 될 수 있는 값 수용하는 곳에서 인식:

* `?` — **인터랙티브 프롬프트**. 시크릿 필드는 마스킹 입력, 아니면 노출.
* `-` — **stdin 에서 한 줄 읽기**. 파이프 친화.
* `@<path>` — **파일에서 읽기**. 전체 파일 콘텐츠가 값 됨.
* 다른 어떤 값 — **리터럴로 사용**, 시크릿 필드에 셸 히스토리 경고.

예:

```bash theme={null}
# 인터랙티브 프롬프트
nora tools headers add t_api --name Authorization --value ?

# 이전 명령에서 파이프
echo -n "$MY_TOKEN" | nora providers set openai --stdin

# 파일에서
nora agents update ag_1 --set-prompt-file prompts/support.md

# 리터럴 (시크릿에 피함)
nora tools headers add t_api --name Authorization --value "Bearer sk-..."
```

## 어느 필드가 어느 모드 수용

대부분 비시크릿 필드 (이름, 설명, 프롬프트) 가 파일 기반 입력에 `@<path>` 수용. 시크릿 민감 필드 (`--api-key`, `--auth-value`, 헤더 값, DB URL) 도 마스킹 프롬프트에 `?`, stdin 에 `-` 수용.

의심되면 `<command> --help` 가 각 플래그의 특정 입력 계약 표시.

## 다른 CLI 에서 값 읽기

리터럴 넘길 수 있는 곳 어디든 서브셸 넘길 수 있음:

```bash theme={null}
nora providers set openai --stdin <<< "$(vault read -field=key secret/nora/openai)"

nora tools headers add t_api \
  --name Authorization \
  --value "Bearer $(aws secretsmanager get-secret-value --secret-id nora/api --query SecretString --output text)"
```

## 멀티라인 콘텐츠 넘김

멀티라인 어떤 것이든 `@file` — 프롬프트, 노트 본문, JSON 페이로드:

```bash theme={null}
nora agents update ag_1 --set-prompt-file prompts/support-v3.md

nora memory notes upsert sp_wiki \
  --path playbooks/refunds.md \
  --body @refunds.md
```

또는 heredoc + stdin:

```bash theme={null}
cat <<'PROMPT' | nora agents update ag_1 --set-prompt -
너는 지원 어시스턴트야.
결제·환불·계정 이슈 질문에 답해.

확신이 없으면 명시적으로 말해.
PROMPT
```

주의: 모든 명령이 이 특정 플래그에 `-` 지원하는 건 아님 — `--help` 가 확인.

## 시크릿과 셸 히스토리

명령줄에 리터럴로 시크릿 넘김이 셸 히스토리에 씀. 위험할 뿐 아니라 — 종종 보안 정책 위반.

증상:

```bash theme={null}
# 나쁨 — 이게 ~/.bash_history / ~/.zsh_history 에 감
nora providers set openai sk-abc123...
```

수정:

```bash theme={null}
# 좋음 — 하나:
nora providers set openai --env OPENAI_API_KEY       # env var
nora providers set openai --stdin < ~/.nora/openai   # 파일 (0600 권한 있음)
echo "$OPENAI_API_KEY" | nora providers set openai --stdin
nora providers set openai --stdin                    # 인터랙티브 프롬프트 (붙여넣기)
```

CLI 가 시크릿 모양 리터럴 감지하면 경고하지만 거부 안 함 — 이유 있으면 오버라이드 가능.

## nora 명령 간 파이핑

많은 명령이 `--json` 지원하므로 조합:

```bash theme={null}
# 모든 superseded 문서 삭제 (확인과 함께)
nora documents list --json | \
  jq -r '.[] | select(.superseded) | .id' | \
  xargs -n1 nora documents delete
```

```bash theme={null}
# 언퍼블리시 draft 있는 모든 Flow 배포
nora flows list --json | \
  jq -r '.[] | select(.draft_differs_from_published) | .slug' | \
  while read slug; do
    nora flows publish "$slug" --note "배치 배포 $(date +%Y-%m-%d)"
  done
```

## jq 로 복잡 구조 읽기

대부분 `--json` 출력이 배열이나 객체. 흔한 패턴:

```bash theme={null}
# 첫 agent 블록의 ID
nora flows get support | jq -r '.blocks[] | select(.kind=="agent") | .id' | head -n1

# 트레이스 비용 합
nora traces list --from 2026-07-01 --json | jq '[.[].cost_cents] | add / 100'

# 중첩 필드로 필터
nora agents sources list ag_1 --json | jq '.[] | select(.preset=="high-precision")'
```

## CI 용 환경변수

CLI 가 auth 와 워크스페이스 컨텍스트용 env var 읽음:

```yaml theme={null}
env:
  NORA_TOKEN: ${{ secrets.NORA_TOKEN }}
  NORA_TENANT: ${{ vars.NORA_WORKSPACE }}
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
```

그 다음 명령이:

```bash theme={null}
nora providers set openai --env OPENAI_API_KEY
nora flows publish support --note "$GIT_COMMIT_MSG"
```

명령줄에 자격증명 없음, 디스크에 상태 안 쓰임.

## 인용 룰

Bash 와 zsh 가 셸 값의 특수 문자에 다르게 인용 처리. 값이 공백·`$`·`!`·`#` 담으면:

```bash theme={null}
# 안전: 작은따옴표가 모든 것 리터럴 보존
nora agents update ag_1 --set-prompt '너는 $friendly 야.'

# 또는 인용 완전 우회 위해 --set-prompt-file 사용
nora agents update ag_1 --set-prompt-file prompt.md
```

보간 많은 JSON 페이로드: `jq -c` 로 JSON 파일을 한 줄로 압축:

```bash theme={null}
nora retrieval presets upsert my-preset \
  --name "내 프리셋" \
  --config "$(jq -c . preset.json)"
```

## Exit 코드

CLI 가 표준 Unix exit 코드 따름:

* `0` — 성공.
* `1` — 일반 에러.
* `2` — 오용 (나쁜 플래그, 누락 필수 인자).
* `4` — 인증 안 됨.
* `8` — 권한 거부 (auth OK 지만 역할 부족).
* `16` — 서버 에러 (플랫폼의 5xx).
* `64` — 명령 없음 또는 형식 잘못.

CI 가 exit 코드로 게이트 가능:

```bash theme={null}
if ! nora flows publish support --note "$MSG"; then
  echo "배포 실패"
  exit 1
fi
```

## 뭔가 작동 안 할 때

* 전체 요청/응답 보려고 `--verbose` 켬.
* 워크스페이스와 토큰 확인 위해 `nora auth status`.
* 고정된 Flow 확인: `nora flows current`.
* CI 에서 exit 코드 echo: `nora flows publish support; echo "Exit: $?"`.