Open in

ThunderPhone CLI

從終端機登入、管理語音智慧體與通話、設定 MCP 用戶端，以及建立專案骨架。

CLI 需要 Node.js 18.18 或更新版本。使用 npx 執行，或全域安裝：

npm install -g thunderphone
thunderphone --help

登入會顯示驗證碼、開啟瀏覽器，並等待授權。在無頭機器上使用 --no-browser，並在其他地方開啟顯示的 URL。裝置登入需要 API 已推出 OAuth 裝置流程。你也可以在 THUNDERPHONE_API_KEY 中設定組織 API 金鑰來驗證指令；其優先順序高於已儲存的登入憑證。

憑證會依設定檔儲存在 ~/.config/thunderphone/credentials.json，檔案權限為 0600。XDG_CONFIG_HOME 和 THUNDERPHONE_CONFIG_DIR 可覆寫該目錄。存取權杖會自動重新整理，輪替的重新整理權杖會以原子方式儲存。登入絕不會顯示權杖。

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 檢視，並僅在對應準備完成且你已檢閱對應欄位與警告後才提交。請參閱智慧體匯入。

MCP 設定

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 認證，請使用：

{
  "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 進行獨立設定。

建立專案

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 或更新版本。

ThunderPhone CLI

登入#

指令#

MCP 設定#

建立專案#

登入

指令

MCP 設定

建立專案