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

vox CLI는 에이전트를 코드처럼 다루는 개발 도구입니다. 에이전트 정의를 JSON 파일로 레포에 두고, 검증부터 배포까지 터미널에서 실행합니다. 편집한 파일은 git으로 리뷰하고, 언제든 재현하거나 롤백할 수 있습니다.

Claude Code, Codex 같은 코딩 에이전트와 함께 쓰도록 설계했습니다. 모든 명령이 `--json` 출력을 지원하므로, AI가 사람 도움 없이 에이전트를 만들고 고칠 수 있습니다.

## 설치

npm 또는 Homebrew로 설치하세요.

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @vox-ai/cli
  ```

  ```bash Homebrew theme={null}
  brew install vox-public/tap/vox
  ```
</CodeGroup>

새 버전이 나오면 `vox upgrade`가 현재 설치 방식에 맞는 업그레이드 명령을 안내합니다.

## 시작하기

```bash theme={null}
# 브라우저에서 vox.ai 계정으로 로그인
vox auth login

# 로그인 확인
vox auth whoami

# 첫 에이전트 프로젝트 생성
vox init --agent main --type flow
```

`vox init`은 `agents/main/agent.json` 소스 파일을 만듭니다. 이 파일을 편집한 뒤 아래 루프로 배포하세요.

```mermaid theme={null}
flowchart LR
    A[agent.json 편집] --> B[vox doctor]
    B --> C[vox agent validate]
    C --> D[vox agent diff]
    D --> E[vox agent push]
    E --> F[vox agent version save]
    F --> G[vox agent promote]
```

`doctor`는 로컬 파일의 흔한 실수를 잡고, `validate`는 서버 검증을 실행합니다. `diff`로 원격과의 차이를 확인한 뒤 `push`로 저장하세요. 프로덕션 반영은 `version save`와 `promote`로 분리되어 있어, 실수로 운영 중인 에이전트를 바꾸지 않습니다.

## 무엇을 할 수 있나요

<AccordionGroup>
  <Accordion title="에이전트">
    에이전트를 만들고, 가져오고, 수정하고, 배포합니다. 대시보드에서 만든 에이전트도 `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
    ```
  </Accordion>

  <Accordion title="플로우 편집">
    [플로우 에이전트](/docs/build/flow/overview)의 노드와 연결을 명령으로 편집합니다. `graph`는 전체 플로우를 다이어그램으로 보여줍니다.

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

  <Accordion title="도구">
    에이전트가 통화 중 호출하는 [커스텀 도구](/docs/build/tools/api)를 파일로 관리합니다. API 키 같은 비밀 값은 파일에 남지 않도록 reference 형태로만 적습니다.

    ```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 --node lookup_customer
    ```
  </Accordion>

  <Accordion title="지식 베이스">
    [지식 베이스](/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 --node conversation
    ```
  </Accordion>

  <Accordion title="통화">
    터미널에서 바로 아웃바운드 통화를 실행하고 결과를 확인합니다. 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
    ```
  </Accordion>

  <Accordion title="전화번호">
    보유 번호에 에이전트를 연결하고, [발신표기번호](/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
    ```
  </Accordion>

  <Accordion title="음성과 모델">
    사용할 수 있는 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
    ```
  </Accordion>

  <Accordion title="채팅 테스트">
    전화를 걸지 않고 터미널에서 에이전트와 대화해 봅니다. `--input`을 반복하면 멀티턴 시나리오를 한 번에 검증하고, `--voice`는 마이크로 실제 음성 대화를 실행합니다.

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

  <Accordion title="워크스페이스 동기화">
    원격 워크스페이스 전체를 레포로 가져오거나, 로컬과 원격이 얼마나 어긋났는지 확인합니다. 워크스페이스가 여러 개라면 하나의 레포에서 전환하며 관리할 수 있습니다.

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

## 코딩 에이전트와 함께 쓰기

vox CLI의 핵심 사용법은 AI에게 맡기는 것입니다. `vox init`을 실행하면 Claude Code와 Codex가 자동으로 인식하는 스킬 파일이 프로젝트에 생성됩니다. 이후 코딩 에이전트에게 자연어로 요청하면, AI가 CLI를 호출해 에이전트를 만들고 검증하고 배포합니다. 클라이언트별 연결 방법은 [Claude Code·Codex에서 CLI 설치](/docs/ai/clients)에서 확인하세요.

```plaintext theme={null}
치과 예약 확인 에이전트 만들어줘.
환자 이름과 예약 시간을 확인하고, 변경이 필요하면 담당자에게 연결해줘.
만들고 나서 vox chat으로 예약 변경 시나리오까지 테스트해줘.
```

AI가 참고할 설계 가이드도 CLI 안에 들어 있습니다.

```bash theme={null}
vox guide coding-agent --brief --json   # 코딩 에이전트용 운영 계약
vox agent plan --task "택배 배송 조회 인바운드 플로우" --json
vox agent create --task "택배 배송 조회 인바운드 플로우" --json
vox docs search "글로벌 노드" --json
```

`agent create --task`는 요청 의도를 분류해 인사, 조회, 성공·실패 안내, 상담사 연결까지 갖춘 초안을 한 번에 만듭니다.

## JSON 출력

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

```bash theme={null}
vox agent list --json | jq '.data[].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` | 새 버전 알림 끄기            |
| `DO_NOT_TRACK=1`           | 익명 사용 텔레메트리 끄기        |

<Note>
  공식 배포 빌드는 명령 이름, 종료 코드 같은 익명 사용 데이터만 수집합니다. 프롬프트, 파일 내용, 토큰, 조직명은 수집하지 않습니다. `DO_NOT_TRACK=1` 또는 `vox config set settings.telemetry disabled`로 끌 수 있습니다.
</Note>

***

<Accordion title="연관 검색어">
  CLI, vox CLI, @vox-ai/cli, command line, 커맨드라인, 터미널, agent as code, 코딩 에이전트, Claude Code, Codex, 에이전트 배포, vox init, vox push
</Accordion>