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

# CLI 명령 참조

> CLI의 명령과 JSON 출력, 인증·CI 설정을 찾아볼 수 있어요.

처음 설치하고 에이전트를 저장하는 순서는 [CLI](/docs/ai/cli)에서 확인하세요. 설치된 버전의 전체 명령과 옵션은 도움말로 확인할 수 있어요.

```bash theme={null}
vox --help
vox agent --help
vox manual --help
vox agent push --help
```

## 에이전트와 운영 명령

### 에이전트

에이전트를 만들고, 가져오고, 고치고, 배포해요. 대시보드에서 만든 에이전트도 `pull`로 가져와 파일로 관리할 수 있어요.

```bash theme={null}
vox agent add support_router --scaffold flow-router
vox agent import dashboard-export.json --agent support_router
vox agent set --agent main --data prompt.firstLine="안녕하세요. 무엇을 도와드릴까요?"
vox agent pull <agent-id> --agent main
vox agent push --agent main
vox agent versions --agent main
vox agent promote v3 --agent main --yes
```

### 플로우 편집

[플로우 에이전트](/docs/build/flow/overview)의 노드와 연결을 명령으로 고쳐요. 아래 `support_router`는 앞에서 만든 Flow 에이전트예요. `graph`로 전체 노드와 연결을 확인할 수 있어요.

```bash theme={null}
vox agent flow add-node check_account --agent support_router --type api --url https://api.example.com/check
vox agent flow connect --agent support_router --from intake --to check_account --condition "API 조회가 필요할 때"
vox agent flow set --agent support_router --node check_account --data api_configuration.timeout_seconds=20
vox agent flow graph --agent support_router --format outline
```

### 도구

에이전트가 통화 중에 부르는 [커스텀 도구](/docs/build/tools/api)를 파일로 관리해요. API 키 같은 비밀 값은 파일에 남지 않도록 참조 형태로만 적어요.

```bash theme={null}
vox tool init crm_lookup --url https://api.example.com/customers/lookup \
  --param "phone_number:string:고객 전화번호"
vox tool validate crm_lookup
vox tool push crm_lookup
vox agent attach tool main crm_lookup
```

### 지식 베이스

[지식 베이스](/docs/build/knowledge/overview)를 문서 단위로 정의하고 배포해요. 텍스트, 웹페이지, 저장소 안의 파일을 문서로 추가할 수 있어요.

```bash theme={null}
vox knowledge init product_faq --name "Product FAQ"
vox knowledge add-document product_faq docs --type webpage --url https://docs.tryvox.co
vox knowledge push product_faq
vox agent attach knowledge main product_faq
```

### 통화

터미널에서 바로 아웃바운드 통화를 걸고 결과를 확인해요. JSON 배열을 넘기면 여러 건을 차례로 발신해요.

```bash theme={null}
vox call create --from <발신번호> --to <수신번호> --agent <agent-id>
vox call list --status ended --agent <agent-id>
vox call get <call-id> --transcript
```

### 대량 발신

[대량 발신](/docs/operate/outbound/campaigns)(`campaign`)을 만들고 진행을 제어해요. 대상은 `--to`를 반복하거나 `call_to` 객체 배열 파일을 `--tasks`로 넘기세요.

```bash theme={null}
vox campaign create --name "9월 안내" --from <발신번호> --agent <agent-id> --tasks ./tasks.json
vox campaign list --status ongoing
vox campaign get <campaign-id>
vox campaign pause <campaign-id>
vox campaign resume <campaign-id>
vox campaign cancel <campaign-id> --yes
```

### 전화번호

보유 번호에 에이전트를 연결하고, [통신서비스 이용증명원](/docs/operate/deploy/phone/telecom-cert)을 발급하고, [발신표기번호](/docs/operate/deploy/phone/caller-id)를 등록해요.

```bash theme={null}
vox number list
vox number set-agent <number-id> --inbound-agent <agent-id>
vox number caller-id register --number 0212345678 --document ./certificate.pdf
vox number certificate request <number-id>
```

### 위젯

웹사이트 [위젯](/docs/operate/deploy/widget/overview)을 만들고 게시해요. `list`, `get`, `create`, `update`, `delete`, `publish`, `unpublish` 명령 7개가 있고, `get --snippet`은 설치 코드를 출력해요.

```bash theme={null}
vox widget create --agent-id <agent-id> --mode chat --branding '{"title":"상담"}'
vox widget publish <id>
vox widget get <id> --snippet
vox widget list
```

### 보이스와 모델

쓸 수 있는 LLM과 [보이스](/docs/build/voice/voice-select)를 조회하고, 보이스를 복제해요.

```bash theme={null}
vox llm list
vox voice list
vox voice clone --file ./sample.wav --name "상담사 A" --language ko
```

### 채팅 테스트

전화를 걸지 않고 터미널에서 에이전트와 대화해 봐요. `--input`을 반복하면 여러 턴 대화 시나리오를 한 번에 검증하고, `--voice`는 마이크로 실제 음성 대화를 해요.

```bash theme={null}
vox chat --agent main --input "안녕하세요"
vox chat --agent main \
  --input "예약을 변경하고 싶어요" \
  --input "예약번호는 A-100입니다" \
  --json
vox chat --agent main --voice
```

### 워크스페이스 동기화

원격 워크스페이스 전체를 저장소로 가져오거나, 로컬과 원격이 얼마나 어긋났는지 확인해요. 워크스페이스가 여럿이면 저장소 하나에서 오가며 관리할 수 있어요.

```bash theme={null}
vox sync status
vox sync bootstrap --all --dry-run
vox org list --tree
vox org switch agency/brand-a
```

### 워크스페이스 관리

[워크스페이스](/docs/workspace/overview) 정보와 통화 사용량·한도, 멤버, 청구서, [인증 상태](/docs/workspace/verification)를 조회하고 [하위 워크스페이스](/docs/workspace/sub-organizations)를 만들거나 삭제해요. 하위 워크스페이스는 `--sub-org`로 지정하세요.

```bash theme={null}
vox org get
vox org usage --sub-breakdown
vox org members --all
vox org invoice list --since 2026-01-01
vox org invoice get <invoice-id>
vox org verification status
vox org create --name "브랜드 A"
vox org delete --sub-org <id> --yes
```

### 메뉴얼

메뉴얼은 에이전트별 `agents/<agent>/manuals/<local-name>/manual.json` 파일로 관리해요. `agent push`와 별도로 `manual push`를 실행해야 원격 에이전트에 메뉴얼이 저장돼요.

```bash theme={null}
vox manual init main reservation --name "예약 안내" --trigger "예약을 문의할 때"
vox manual list --agent main
vox manual validate main reservation
vox manual push --agent main --dry-run
vox manual push --agent main
vox manual diff main reservation
vox manual status main reservation
vox manual pull --agent main
```

`manual diff`는 원격에서 가져오거나 한 번 저장한 메뉴얼에 쓸 수 있어요. `manual push`는 해당 에이전트의 메뉴얼 전체를 반영해요. 원격에서 메뉴얼이 바뀌어 `REMOTE_CHANGED`가 나오면 `manual pull`로 변경을 가져와 검토하세요. `manual pull --force`는 에이전트 전체 메뉴얼의 로컬 수정을 버릴 수 있어요.

## 저장과 프로덕션 지정

| 명령 | 결과 |
| - | - |
| `vox agent push` | 에이전트의 현재 설정을 저장해요. |
| `vox manual push --agent main` | 에이전트의 메뉴얼을 저장해요. |
| `vox agent version save` | 원격의 현재 설정을 버전으로 저장해요. 로컬 수정은 먼저 push하세요. |
| `vox agent promote <version> --yes` | 저장한 버전을 프로덕션에 지정해요. |

`<version>`에는 `version save` 결과의 `v1`, `v2` 같은 값을 넣으세요. 운영 중인 에이전트를 바꾸기 전에 대상과 변경 내용을 확인하세요.

## 코딩 에이전트 지침

```bash theme={null}
vox guide coding-agent --brief --json
vox agent skills status
vox agent skills refresh
vox agent plan --task "택배 배송 조회 인바운드 플로우" --json
vox agent create --task "택배 배송 조회 인바운드 플로우" --json
vox docs search "글로벌 노드" --json
```

`agent plan`은 설계안을, `agent create --task`는 요청에 맞는 초안을 만들어요. `skills refresh`는 CLI가 관리하는 `.claude/skills/vox-ai/SKILL.md`와 `.codex/skills/vox-ai/SKILL.md`를 갱신해요. 이 파일을 직접 수정하면 갱신할 때 덮어쓸 수 있어요. 처음부터 만들지 않으려면 `vox init --no-agent-skills`를 쓰세요.

## JSON으로 결과 받기

모든 명령이 `--json`을 지원해요. 스크립트나 CI에서 결과를 파싱해 쓰세요.

```bash theme={null}
vox agent list --json | jq '.data.items[].name'
vox call get <call-id> --json | jq '.data.transcript'
vox agent diff --check   # 변경이 있으면 exit 1
```

## 인증과 프로필 관리하기

로그인은 OAuth만 지원하고, 토큰은 OS 키체인에 저장돼요. API 키를 파일에 남기지 않아요.

```bash theme={null}
vox auth login                 # 프로필 추가
vox auth switch                # 계정·워크스페이스 전환
vox auth whoami                # 현재 로그인 확인
vox auth logout                # 로그아웃
```

CI처럼 브라우저를 열 수 없는 환경에서는 환경 변수로 토큰을 넣으세요.

| 환경 변수 | 용도 |
| - | - |
| `VOX_OAUTH_ACCESS_TOKEN` | 저장된 로그인 대신 쓸 액세스 토큰 |
| `VOX_ORGANIZATION_ID` | 명령을 적용할 워크스페이스 |
| `VOX_NO_UPDATE_NOTIFIER=1` | 새 버전 알림 끄기 |

토큰은 CI의 비밀 변수에 보관하세요. 환경 변수로 준 토큰이 만료되면 새 토큰으로 교체해야 해요.

### 사용 정보 수집

공식 배포 빌드는 CLI 사용 정보와 로그인 계정 정보를 늘 수집해요. PostHog로 보내는 항목은 사용자 ID, 이메일, 이름, 프로필, install ID, 마지막 로그인 시각, 현재·기본 워크스페이스 정보, 명령 실행 정보예요. 프롬프트, 파일 경로와 내용, 명령 인자 값, 토큰, 시크릿, 메시지 내용, 고객 데이터는 수집하지 않아요. 공식 배포 빌드는 텔레메트리 수집을 끌 수 없어요.

## 오류와 예외

* **인증 오류**: `vox auth whoami`로 계정과 워크스페이스를 확인하고, 다시 로그인이 필요하면 `vox auth login`을 실행하세요.
* **처음 저장하기 전 `diff` 오류**: 새 항목에는 원격 연결 정보가 없어 `AGENT_BINDING_NOT_FOUND`나 `MANUAL_BINDING_NOT_FOUND`가 나와요. 검증 후 처음 저장하고, 그다음 수정부터 `diff`로 비교하세요.
* **원격과 로컬 차이**: `vox sync status`와 `vox agent diff`로 확인하세요. 원격 변경을 가져올 때는 로컬 수정과 비교하세요.
* **업데이트**: `vox upgrade`로 현재 설치 방식에 맞는 업데이트 명령을 확인하세요.

## 관련 문서

* [CLI](/docs/ai/cli): 설치와 첫 에이전트 저장
* [에이전트 버전 관리](/docs/build/versioning): 버전과 프로덕션 동작
* [메뉴얼](/docs/build/manuals/overview): 업무별 응대 절차 구성


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.