---
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` | 指派來電智慧體 |
| `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` 預設為一小時逾時；可設定 `--timeout SECONDS` 變更。逾時會停止等待，
但不會結束通話。

SMS 也需要你已連線的 Twilio 或 Telnyx 帳戶中具備 SMS 功能的號碼。
系統絕不會使用 ThunderPhone 擁有的號碼傳送。只有在重試完全相同的寄件者、
收件者與訊息內容時，才能重複使用冪等性金鑰。

匯入支援 `vapi`、`retell`、`elevenlabs` 與 `bland`。第二個引數是供應商 JSON
匯出檔的路徑，不是遠端供應商 ID。API 會非同步準備對應；使用 `imports get UUID`
檢視，並僅在對應準備完成且你已檢閱對應欄位與警告後才提交。請參閱
[智慧體匯入](/zh-Hant/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` 會覆寫
端點。它不會傳送遙測資料。安裝 `@thunderphone/mcp` 全域套件後，也可透過
`npx -y @thunderphone/mcp setup --client cursor` 或 `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 或更新版本。