---
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；錯誤會輸出至 stderr，
並以非零結束代碼結束。未使用 `--json` 時，輸出會是精簡表格或欄位清單。
JSON 會保留 API 回應結構，並遮蔽憑證欄位。MCP 服務會保留 stdout 作 MCP 通訊協定之用。

| 指令 | 用途 |
| --- | --- |
| `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` | 指派入線智能體 |
| `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`。由 ThunderPhone 配置的號碼僅限入線使用。`--wait` 預設逾時時間
為一小時；使用 `--timeout SECONDS` 可更改設定。逾時只會停止等待，不會結束通話。

匯入功能支援 `vapi`、`retell`、`elevenlabs` 和 `bland`。第二個引數是供應商 JSON 匯出檔案的
路徑，並非遠端供應商 ID。API 會以非同步方式準備對應；
使用 `imports get UUID` 檢視，並只在準備完成及已檢閱對應欄位和警告後才提交。
請參閱[智能體匯入](/yue/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`。預設為專案範圍。桌面版及 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 或更高版本。