# CLI 參考 cmux 提供 CLI 工具和 Unix socket，用於程式化控制。每個指令都可以透過兩種介面使用。 ## Socket | 建構 | 路徑 | | --- | --- | | 正式版 | `/tmp/cmux.sock` | | 除錯版 | `/tmp/cmux-debug.sock` | | 標記的除錯版建構 | `/tmp/cmux-debug-.sock` | 使用 CMUX\_SOCKET\_PATH 環境變數覆寫。每次呼叫傳送一個以換行符結尾的 JSON 請求： ``` {"id":"req-1","method":"workspace.list","params":{}} // Response: {"id":"req-1","ok":true,"result":{"workspaces":[...]}} ``` JSON socket 請求必須使用 method 和 params。不支援舊版 v1 JSON 格式，例如 `{"command":"..."}`。 ## 存取模式 | 模式 | 說明 | 如何啟用 | | --- | --- | --- | | **Off** | 停用 socket | 設定 UI 或 CMUX\_SOCKET\_MODE=off | | **cmux processes only** | 只有在 cmux 終端機內啟動的程序才能連線。 | 設定 UI 中的預設模式 | | **allowAll** | 允許任何本機程序連線（不檢查血統關係）。 | 僅限環境變數覆寫：CMUX\_SOCKET\_MODE=allowAll | 在共用機器上，請使用「關閉」或「僅限 cmux 程序」模式。 ## CLI 選項 | 旗標 | 說明 | | --- | --- | | `--socket PATH` | 自訂 socket 路徑 | | `--json` | 以 JSON 格式輸出 | | `--window ID` | 指定特定視窗 | | `--workspace ID` | 指定特定工作區 | | `--surface ID` | 指定特定 surface | | `--id-format refs|uuids|both` | 控制 JSON 輸出中的識別碼格式 | ## 工作區指令 #### list-workspaces 列出所有開啟的工作區。 CLI ``` cmux list-workspaces cmux list-workspaces --json ``` Socket ``` {"id":"ws-list","method":"workspace.list","params":{}} ``` #### new-workspace 建立新的工作區。 CLI ``` cmux new-workspace ``` Socket ``` {"id":"ws-new","method":"workspace.create","params":{}} ``` #### select-workspace 切換到指定的工作區。 CLI ``` cmux select-workspace --workspace ``` Socket ``` {"id":"ws-select","method":"workspace.select","params":{"workspace_id":""}} ``` #### current-workspace 取得目前活躍的工作區。 CLI ``` cmux current-workspace cmux current-workspace --json ``` Socket ``` {"id":"ws-current","method":"workspace.current","params":{}} ``` #### close-workspace 關閉工作區。 CLI ``` cmux close-workspace --workspace ``` Socket ``` {"id":"ws-close","method":"workspace.close","params":{"workspace_id":""}} ``` ## 分割指令 #### new-split 建立新的分割窗格。方向：left、right、up、down。 CLI ``` cmux new-split right cmux new-split down cmux new-split down --command "npm run dev" ``` Socket ``` {"id":"split-new","method":"surface.split","params":{"direction":"right"}} {"id":"split-cmd","method":"surface.split","params":{"direction":"down","initial_input":"npm run dev\r"}} ``` #### list-panels 列出目前工作區中的所有 surface。 CLI ``` cmux list-panels cmux list-panels --json ``` Socket ``` {"id":"surface-list","method":"surface.list","params":{}} ``` #### list-pane-surfaces 列出目前聚焦窗格中的 surface。 CLI ``` cmux list-pane-surfaces cmux list-pane-surfaces --json ``` Socket ``` {"id":"pane-surfaces","method":"pane.surfaces","params":{}} ``` #### focus-panel 聚焦到指定的 surface。 CLI ``` cmux focus-panel --panel ``` Socket ``` {"id":"surface-focus","method":"surface.focus","params":{"surface_id":""}} ``` ## 輸入指令 #### send 向聚焦的終端機傳送文字輸入。 CLI ``` cmux send "echo hello" cmux send "ls -la\n" ``` Socket ``` {"id":"send-text","method":"surface.send_text","params":{"text":"echo hello\n"}} ``` #### send-key 傳送按鍵。按鍵：enter、tab、escape、backspace、delete、up、down、left、right。 CLI ``` cmux send-key enter ``` Socket ``` {"id":"send-key","method":"surface.send_key","params":{"key":"enter"}} ``` #### send --surface 向指定的 surface 傳送文字。 CLI ``` cmux send --surface "command" ``` Socket ``` {"id":"send-surface","method":"surface.send_text","params":{"surface_id":"","text":"command"}} ``` #### send-key --surface 向指定的 surface 傳送按鍵。 CLI ``` cmux send-key --surface enter ``` Socket ``` {"id":"send-key-surface","method":"surface.send_key","params":{"surface_id":"","key":"enter"}} ``` ## 通知指令 #### notify 傳送通知。 CLI ``` cmux notify --title "Title" --body "Body" cmux notify --title "T" --subtitle "S" --body "B" ``` Socket ``` {"id":"notify","method":"notification.create","params":{"title":"Title","subtitle":"S","body":"Body"}} ``` #### list-notifications 列出所有通知。 CLI ``` cmux list-notifications cmux list-notifications --json ``` Socket ``` {"id":"notif-list","method":"notification.list","params":{}} ``` #### clear-notifications 清除所有通知。 CLI ``` cmux clear-notifications ``` Socket ``` {"id":"notif-clear","method":"notification.clear","params":{}} ``` ## 側邊欄中繼資料指令 為任何工作區設定側邊欄中的狀態標籤、進度條和日誌項目。適用於建構腳本、CI 整合，以及需要一目了然顯示狀態的 AI 程式碼代理。 #### set-status 設定側邊欄狀態標籤。使用唯一的 key，讓不同的工具可以管理各自的項目。 CLI ``` cmux set-status build "compiling" --icon hammer --color "#ff9500" --priority 80 cmux set-status deploy "v1.2.3" --workspace workspace:2 ``` Socket ``` set_status build compiling --icon=hammer --color=#ff9500 --priority=80 --tab= ``` #### clear-status 依 key 移除側邊欄狀態項目。 CLI ``` cmux clear-status build ``` Socket ``` clear_status build --tab= ``` #### list-status 列出工作區的所有側邊欄狀態項目。 CLI ``` cmux list-status ``` Socket ``` list_status --tab= ``` #### set-progress 設定側邊欄中的進度條（0.0 到 1.0）。 CLI ``` cmux set-progress 0.5 --label "Building..." cmux set-progress 1.0 --label "Done" ``` Socket ``` set_progress 0.5 --label=Building... --tab= ``` #### clear-progress 清除側邊欄進度條。 CLI ``` cmux clear-progress ``` Socket ``` clear_progress --tab= ``` #### log 在側邊欄附加日誌項目。級別：info、progress、success、warning、error。 CLI ``` cmux log "Build started" cmux log --level error --source build "Compilation failed" cmux log --level success -- "All 42 tests passed" ``` Socket ``` log --level=error --source=build --tab= -- Compilation failed ``` #### clear-log 清除所有側邊欄日誌項目。 CLI ``` cmux clear-log ``` Socket ``` clear_log --tab= ``` #### list-log 列出側邊欄日誌項目。 CLI ``` cmux list-log cmux list-log --limit 5 ``` Socket ``` list_log --limit=5 --tab= ``` #### sidebar-state 傾印所有側邊欄中繼資料（cwd、git 分支、連接埠、狀態、進度、日誌）。 CLI ``` cmux sidebar-state cmux sidebar-state --workspace workspace:2 ``` Socket ``` sidebar_state --tab= ``` ## 工具指令 #### ping 檢查 cmux 是否正在執行且有回應。 CLI ``` cmux ping ``` Socket ``` {"id":"ping","method":"system.ping","params":{}} // Response: {"id":"ping","ok":true,"result":{"pong":true}} ``` #### capabilities 列出可用的 socket 方法和目前的存取模式。 CLI ``` cmux capabilities cmux capabilities --json ``` Socket ``` {"id":"caps","method":"system.capabilities","params":{}} ``` #### identify 顯示聚焦中的視窗/工作區/窗格/surface 情境。 CLI ``` cmux identify cmux identify --json ``` Socket ``` {"id":"identify","method":"system.identify","params":{}} ``` ## 環境變數 | 變數 | 說明 | | --- | --- | | `CMUX_SOCKET_PATH` | 覆寫 CLI 和整合所使用的 socket 路徑 | | `CMUX_SOCKET_ENABLE` | 強制啟用/停用 socket（1/0、true/false、on/off） | | `CMUX_SOCKET_MODE` | 覆寫存取模式（cmuxOnly、allowAll、off）。也接受 cmux-only/cmux\_only 和 allow-all/allow\_all | | `CMUX_WORKSPACE_ID` | 自動設定：目前工作區 ID | | `CMUX_SURFACE_ID` | 自動設定：目前 surface ID | | `TERM_PROGRAM` | 設定為 ghostty | | `TERM` | 設定為 xterm-ghostty | 舊版的 CMUX\_SOCKET\_MODE 值 full 和 notifications 仍然接受以保持相容性。 ## 偵測 cmux bash ``` # Prefer explicit socket path if set SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}" [ -S "$SOCK" ] && echo "Socket available" # Check for the CLI command -v cmux &>/dev/null && echo "cmux available" # In cmux-managed terminals these are auto-set [ -n "${CMUX_WORKSPACE_ID:-}" ] && [ -n "${CMUX_SURFACE_ID:-}" ] && echo "Inside cmux surface" # Distinguish from regular Ghostty [ "$TERM_PROGRAM" = "ghostty" ] && [ -n "${CMUX_WORKSPACE_ID:-}" ] && echo "In cmux" ``` ## 範例 ### Python 用戶端 python ``` import json import os import socket SOCKET_PATH = os.environ.get("CMUX_SOCKET_PATH", "/tmp/cmux.sock") def rpc(method, params=None, req_id=1): payload = {"id": req_id, "method": method, "params": params or {}} with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock: sock.connect(SOCKET_PATH) sock.sendall(json.dumps(payload).encode("utf-8") + b"\n") return json.loads(sock.recv(65536).decode("utf-8")) # List workspaces print(rpc("workspace.list", req_id="ws")) # Send notification print(rpc( "notification.create", {"title": "Hello", "body": "From Python!"}, req_id="notify" )) ``` ### Shell 腳本 bash ``` #!/bin/bash SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}" cmux_cmd() { printf "%s\n" "$1" | nc -U "$SOCK" } cmux_cmd '{"id":"ws","method":"workspace.list","params":{}}' cmux_cmd '{"id":"notify","method":"notification.create","params":{"title":"Done","body":"Task complete"}}' ``` ### 帶有通知的建構腳本 bash ``` #!/bin/bash npm run build if [ $? -eq 0 ]; then cmux notify --title "✓ Build Success" --body "Ready to deploy" else cmux notify --title "✗ Build Failed" --body "Check the logs" fi ``` Canonical: https://cmux.com/zh-TW/docs/api Documentation index: https://cmux.com/llms.txt