---
title: "ThunderPhone CLI"
description: "터미널에서 로그인하고, 음성 에이전트와 통화를 관리하며, MCP 클라이언트를 구성하고, 프로젝트를 스캐폴딩합니다."
---

CLI에는 Node.js 18.18 이상이 필요합니다. `npx`로 실행하거나 전역으로 설치하십시오.

```bash
npm install -g thunderphone
thunderphone --help
```

## 로그인

```bash
npx thunderphone login
thunderphone whoami --json
```

로그인하면 확인 코드가 출력되고 브라우저가 열리며 승인을 기다립니다.
헤드리스 머신에서는 `--no-browser`를 사용하고, 출력된 URL을 다른 환경에서 여십시오.
디바이스 로그인에는 API의 OAuth 디바이스 플로우가 배포되어 있어야 합니다. `THUNDERPHONE_API_KEY`의 조직 API
키로도 명령을 인증할 수 있으며, 저장된 로그인 자격 증명보다 우선 적용됩니다.

자격 증명은 `~/.config/thunderphone/credentials.json`에 프로필별로 저장되며 파일 모드는 `0600`입니다.
`XDG_CONFIG_HOME` 및 `THUNDERPHONE_CONFIG_DIR`가 디렉터리를 재정의합니다. 액세스 토큰은 자동으로 갱신되며 교체되는
갱신 토큰은 원자적으로 저장됩니다. 로그인 명령은 토큰을 절대 출력하지 않습니다.

```bash
thunderphone login --profile work
thunderphone agents list --profile work --json
thunderphone logout --profile work
```

`THUNDERPHONE_PROFILE`은 기본 프로필을 설정합니다. 로그아웃하면 로컬 자격 증명이 제거되지만
서버 권한 부여는 취소되지 않습니다. 기본 API는 `https://api.thunderphone.com`입니다.
다른 API를 사용하려면 `--api-base-url` 또는 `THUNDERPHONE_API_BASE_URL`을 사용하십시오. 한 프로필의 토큰은
다르게 구성된 API URL로 전송할 수 없습니다. 별도의 프로필로 해당 URL에 로그인하십시오.

## 명령

모든 명령은 `--json`을 허용합니다. 성공한 데이터는 stdout으로 출력되고, 오류는 0이 아닌 종료 코드와 함께 stderr로 출력됩니다.
`--json` 없이 실행하면 간결한 표 또는 필드 목록으로 출력됩니다.
JSON은 자격 증명 필드가 삭제된 API 응답 구조를 유지합니다. MCP 제공은 MCP 프로토콜을 위해 stdout을 예약합니다.

| 명령 | 용도 |
| --- | --- |
| `login [--no-browser] [--scope "scopes"]` | 디바이스 코드를 통해 인증합니다 |
| `logout`, `whoami` | 로컬 자격 증명을 제거하고 접근 가능한 조직을 나열합니다 |
| `agents list`, `agents get ID` | 에이전트를 조회합니다 |
| `agents create --file agent.json` | 에이전트를 생성합니다 |
| `agents update ID --file agent.json` | 에이전트 초안을 저장합니다 |
| `agents deploy ID`, `agents delete ID` | 초안을 배포하고 에이전트를 삭제합니다 |
| `numbers list` | 전화번호를 조회합니다 |
| `numbers provision --country US --area-code 415` | 미국 수신 번호를 개통합니다 |
| `numbers assign NUMBER_ID --agent ID` | 수신 에이전트를 할당합니다 |
| `sms send TO --from FROM --body TEXT --idempotency-key KEY` | 안전한 재실행 기능을 사용하여 고객이 연결한 통신사 번호로 SMS를 전송합니다 |
| `sms list [--limit N]`, `sms get UUID` | SMS 기록을 나열하거나 확인합니다 |
| `call TO --agent ID --from FROM [--wait]` | 발신 전화를 걸고 선택적으로 통화 기록을 기다립니다 |
| `calls list [--limit N] [--agent ID]` | 통화를 나열합니다(한도 1–200) |
| `calls get ID`, `calls transcript ID` | 단일 통화 또는 해당 통화 기록을 조회합니다 |
| `test run AGENT_ID [--scenario ID] --consent-to-charge` | 웹 채널을 사용하여 과금되는 저장된 시나리오를 실행합니다 |
| `test status RUN_ID [--agent ID]` | 배치를 확인하며, 에이전트를 제공하면 시나리오 세부 정보도 확인합니다 |
| `import VENDOR export.json` | 검토할 공급업체 JSON 가져오기를 준비합니다 |
| `imports get UUID`, `imports commit UUID` | 가져오기를 확인하고 검토 후 선택한 에이전트를 커밋합니다 |
| `mcp setup`, `mcp serve` | 클라이언트를 구성하고 stdio 브리지를 시작합니다 |
| `init [directory]` | 프로젝트 골격을 생성합니다 |

발신 전화에는 발신이 활성화된 번호가 필요합니다. `THUNDERPHONE_FROM_NUMBER`는
`--from`을 제공할 수 있습니다. 고객 VoIP 번호는 계속해서 발신 전화를 지원합니다.
ThunderPhone에서 개통한 번호는 처음에는 수신 전용입니다. 조직 관리자는 전화번호 페이지에서
발신 통화를 요청할 수 있으며, 각 요청은 수동으로 검토됩니다. `--wait`의 기본값은
1시간 제한 시간입니다. 변경하려면 `--timeout SECONDS`를 설정합니다. 제한 시간이 지나면
통화를 종료하지 않고 대기만 중지됩니다.

SMS에도 연결된 Twilio 또는 Telnyx 계정의 SMS 지원 번호가 필요합니다.
ThunderPhone 소유 번호에서는 절대 전송되지 않습니다. 정확히 동일한 발신자, 수신자 및 본문을
재시도하는 경우에만 멱등성 키를 재사용합니다.

가져오기는 `vapi`, `retell`, `elevenlabs`, `bland`를 지원합니다. 두 번째 인수는
원격 공급업체 ID가 아니라 공급업체 JSON 내보내기 경로입니다. API는 매핑을
비동기적으로 준비합니다. `imports get UUID`로 이를 확인하고, 준비가 완료된 후
매핑된 필드와 경고를 검토한 경우에만 커밋합니다. [에이전트 가져오기](/ko/guides/import-agents)를 참조하세요.

## MCP 설정

```bash
thunderphone mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
thunderphone mcp setup --client codex --scope user --api-key-env THUNDERPHONE_API_KEY
thunderphone mcp setup --client claude-desktop --scope user
```

클라이언트: `claude-code`, `codex`, `cursor`, `vscode`, `gemini`, `claude-desktop`, 및
`windsurf`. 프로젝트 범위가 기본값입니다. Desktop과 Windsurf에는 사용자 범위가 필요합니다.
프로젝트에서 단일 클라이언트를 감지하려면 `--client`를 생략합니다. 감지가 모호한 경우
대화형으로 선택을 요청하며, 비대화형 세션에서는 지침과 함께 실패합니다.
설정은 작성한 파일을 출력하고 관련 없는 서버는 유지합니다. 기존 JSON은 유효한 엄격한 JSON이어야 합니다.
Codex TOML 값은 유지되지만 주석 형식은 변경될 수 있습니다.

설정은 직접 원격 HTTP를 우선 사용합니다. `--api-key-env`를 사용하면 키가 아닌 변수
참조를 작성합니다. 이 옵션이 없으면 직접 HTTP는 클라이언트의 OAuth 지원에 의존하며
CLI 자격 증명 파일을 사용하지 않습니다. 모든 stdio 지원 클라이언트에서 `thunderphone login`
자격 증명을 재사용하려면 다음을 사용합니다.

```json
{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": ["-y", "@thunderphone/mcp"]
    }
  }
}
```

래퍼는 먼저 `THUNDERPHONE_API_KEY`를 확인하고, 그다음 현재 CLI 프로필을 확인하며(필요한 경우
새로 고침), 이후 OAuth를 `mcp-remote`에 위임합니다. `THUNDERPHONE_MCP_URL`은
엔드포인트를 재정의합니다. 텔레메트리를 전송하지 않습니다. 독립형 설정은
`npx -y @thunderphone/mcp setup --client cursor`를 통해서도 사용할 수 있으며,
`@thunderphone/mcp`를 전역 설치한 후에는 `thunderphone-mcp setup`을 사용할 수도 있습니다.

## 프로젝트 만들기

```bash
npx create-thunderphone-agent my-receptionist
npx create-thunderphone-agent my-outbound --template python --agent-type outbound
# Equivalent:
thunderphone init my-receptionist --template node --agent-type receptionist
```

템플릿은 `node`와 `python`이며, 에이전트 유형은 `receptionist`, `outbound`, 그리고
`custom`입니다. 기본 에이전트는 명시적인 데모 정보를 포함한 영어/스페인어 치과 접수 에이전트입니다.
프로젝트에는 `agent.json`, 배포 스크립트, Claude Code, Cursor 및 VS Code용 MCP 구성,
에이전트 지침, `.env.example`, 그리고 README가 포함됩니다. 스캐폴딩은 오프라인으로 수행되며
비어 있지 않은 디렉터리에는 덮어쓰기를 거부합니다.

배포 전에 비즈니스 정보를 수정합니다. 생성된 README에 문서화된 대로 API 키, 연결된 발신자
번호 및 테스트 수신자를 내보냅니다. `npm run deploy` 또는 `python deploy.py`는 에이전트를
생성하거나 업데이트하고, 초안을 배포하며, 과금되는 테스트 전화를 겁니다. 스크립트는 API 키 인증을
사용하며, CLI와 stdio MCP 래퍼도 기기 로그인을 지원합니다. Python 스크립트에는 Python 3.9 이상이 필요합니다.