截圖使用英文介面，圖表隨指南語言切換。控制項名稱可能因您選擇的應用程式語言而異。
spcli — 命令參考
使用與 Mac App 自動化頁面一致的命令說明及可複製範例，涵蓋既有命令與 2.0.17 新增命令。
以下章節同步自 Mac App 內建自動化資料，包含逐項說明及完整指令碼。執行前請替換範例名稱與 ID。範例可能修改實際連線及設定，請勿一次執行整頁。
遠端桌面
spcli list remote-desktops --json
列出已儲存的 RDP/VNC 連線。
spcli list remote-desktops --json
spcli get-remote-desktop "<ID>"
依 ID 讀取連線，不傳回認證資料。
spcli get-remote-desktop "DESKTOP-ID"
spcli create-remote-desktop <JSON>
提供 name 和 values 建立連線。使用 hostProfileUUID 參照預設主機。
spcli create-remote-desktop '{"name":"Office desktop","values":{"hostProfileUUID":"PRESET-HOST-ID","remoteDesktopType":"rdp","remoteDesktopUsername":"alice","remoteHost":"192.168.1.91"}}'
spcli create-remote-desktop '{"name":"Office VNC","values":{"hostProfileUUID":"PRESET-HOST-ID","remoteDesktopType":"vnc","remoteDesktopVNCOpenMode":"screenSharing"}}'
spcli update-remote-desktop <JSON>
依 id 更新；name 和 values 為選填。
spcli update-remote-desktop '{"id":"DESKTOP-ID","values":{"remoteDesktopOptions":{"screen mode id":1,"audiomode":2}}}'
spcli open-remote-desktop "<ID>"
必要時先啟動 SSH 通道，再開啟已選的 RDP/VNC 用戶端。
spcli open-remote-desktop "DESKTOP-ID"
spcli delete-remote-desktop "<ID>"
依 ID 刪除未連線的遠端桌面連線。
spcli delete-remote-desktop "DESKTOP-ID"
允許寫入使用者名稱，但不會讀取既有使用者名稱。SSH 密碼和身分檔案請在 Secure Pipes 中設定；遠端桌面密碼請在用戶端輸入。
關於 spcli
spcli 是隨 Secure Pipes 附帶的命令列工具，可直接在終端機控制 Secure Pipes，方便你在 shell 指令碼、別名或排程工作中啟動、停止和檢視已儲存的連線。
spcli 使用相同的 AppleScript 命令和自動化權限。啟動網路共享時可能開啟現有確認視窗。
安裝 spcli
spcli 隨 Secure Pipes 一起打包，但在安裝前不會出現在你的 PATH 中。請在「偏好設定」>「一般」中「備份」下方的命令列工具這一行進行安裝或移除。
點擊「安裝 spcli」。Secure Pipes 會將 spcli 連結到 PATH 中的目錄，例如 /usr/local/bin 或 /opt/homebrew/bin。
如果該目錄需要權限，請完成一次性的管理員授權。
開啟新的終端機視窗，執行 spcli --help 確認已可用。
如需移除，請在同一行點擊「解除安裝 spcli」。
檢查安裝
spcli --version
spcli --help
命令參考
輸入 spcli，再加上指令。連線名稱和群組標籤請以引號括住。
spcli start
啟動 Secure Pipes，但不顯示視窗。
spcli start
spcli show
顯示並啟用 Secure Pipes 視窗。
spcli show
spcli hide
隱藏 Secure Pipes 視窗，連線會繼續執行。
spcli hide
spcli shutdown
結束 Secure Pipes 並停止作用中的連線。
spcli shutdown
spcli list connections
列出已設定的連線。加上 --json 可取得機器可讀的輸出。
spcli list connections
spcli list groups
列出做為連線群組的標籤。加上 --json 可取得機器可讀的輸出。
spcli list groups
spcli connect "<connection>"
啟動已儲存的連線。
spcli connect "Build Tunnel (Local Forward)"
spcli disconnect "<connection>"
停止已儲存的連線。
spcli disconnect "Build Tunnel (Local Forward)"
spcli status "<connection>"
顯示連線的目前狀態。
spcli status "Build Tunnel (Local Forward)"
spcli connect-group "<group>"
依已儲存的啟動設定啟動群組。
spcli connect-group "engineering"
spcli disconnect-group "<group>"
停止群組及其成員連線。
spcli disconnect-group "engineering"
spcli list task-plans
列出任務計畫，不返回憑證資料。
spcli list task-plans --json
spcli create-task-plan '<JSON>'
從 JSON 建立經驗證的任務計畫。連線與群組使用 ID，勿包含憑證資料。
spcli create-task-plan '{"id":"work-start","hour":9,"minute":0,"repeat":2,"actions":[{"type":"start_group","id":"work"}]}'
spcli update-task-plan '<JSON>'
以既有 ID 及要儲存的欄位更新計畫。
spcli update-task-plan '{"id":"work-start","hour":8,"minute":45,"repeat":2,"actions":[{"type":"start_group","id":"work"}]}'
spcli enable-task-plan "<ID>"
啟用、停用既有計畫，或立即執行以測試。
spcli enable-task-plan "work-start"
spcli disable-task-plan "work-start"
spcli run-task-plan "work-start"
選項
--json
讓支援的指令輸出機器可讀的 JSON。
--help
顯示完整的用法說明。
--version
顯示 spcli 版本。
結束碼
0 表示成功，1 表示 Secure Pipes 回報錯誤，2 表示用法無效，3 表示找不到 Secure Pipes 或自動化權限遭拒，4 表示無法傳送 Apple Event。
規則與使用場景
修改規則或切換場景時，可使用 ID 或唯一名稱。切換場景會中斷作用中的連線，然後重新連線。刪除場景不會刪除規則；沒有其他所屬場景的規則會變為通用規則。
spcli list rules
依順序列出規則的 ID、名稱、啟用狀態、動作和關聯場景 ID。
spcli list rules --json
spcli list scenarios
列出場景（包括通用場景）的 ID、名稱及是否正在使用。
spcli list scenarios --json
spcli current-scenario
顯示目前使用場景的名稱。
spcli current-scenario
spcli switch-scenario "Office"
依 ID 或唯一名稱切換場景，並依新規則重新連線受影響的連線。
spcli switch-scenario "Office"
spcli enable-rule "Work websites"
依 ID 或唯一名稱啟用規則。
spcli enable-rule "Work websites"
spcli disable-rule "Work websites"
停用規則，但不刪除規則。
spcli disable-rule "Work websites"
spcli set-rule-scenarios "Work websites" "Office" "Travel"
取代規則關聯的場景。指定 Universal 可將其設為通用規則。
spcli set-rule-scenarios "Work websites" "Office" "Travel"
spcli create-scenario "Travel"
使用唯一名稱建立場景，並傳回其 ID。
spcli create-scenario "Travel"
spcli rename-scenario "Travel" "Mobile work"
重新命名場景，保留現有規則關聯。
spcli rename-scenario "Travel" "Mobile work"
spcli delete-scenario "Travel"
刪除場景，但保留規則。未關聯其他場景的規則將變為通用規則。
spcli delete-scenario "Travel"
綜合範例
spcli list rules --json
spcli list scenarios --json
spcli current-scenario
spcli switch-scenario "Office"
spcli enable-rule "Work websites"
spcli disable-rule "Work websites"
spcli set-rule-scenarios "Work websites" "Office" "Travel"
spcli set-rule-scenarios "Work websites" Universal
spcli create-scenario "Travel"
spcli rename-scenario "Travel" "Mobile work"
spcli delete-scenario "Mobile work"
代理與網路共享
共享沿用已儲存的位址、連接埠和驗證設定。啟動時會視需要開啟現有確認視窗；閘道模式仍需風險確認和 macOS 授權。
spcli list proxy-servers
列出代理伺服器的 ID、名稱、類型和位址，不包含驗證資訊。
spcli list proxy-servers --json
spcli transparent-proxy-status
查看透明代理的執行狀態、系統延伸功能狀態及版本是否相符。
spcli transparent-proxy-status --json
spcli initialize-transparent-proxy
安裝或修復系統延伸功能。macOS 可能要求核准；此命令不會啟動透明代理。
spcli initialize-transparent-proxy
spcli start-transparent-proxy
系統延伸功能就緒後，依目前路由規則啟動透明代理。
spcli start-transparent-proxy
spcli stop-transparent-proxy
停止透明代理。網路共享依賴此服務執行。
spcli stop-transparent-proxy
spcli sharing-status
查看共享和閘道狀態。執行時顯示實際生效的模式，停止時顯示已儲存的模式。
spcli sharing-status --json
spcli set-sharing-modes both
選擇下次手動啟動時的代理模式、閘道模式、兩者同時啟用或全部關閉。變更前須停止共享。
spcli set-sharing-modes both
spcli start-sharing
依所選模式及已儲存的位址、連接埠和驗證設定啟動共享。可能需要確認。
spcli start-sharing
spcli stop-sharing
停止閘道及共享代理監聽器。透明代理會繼續執行。
spcli stop-sharing
綜合範例
spcli list proxy-servers --json
spcli transparent-proxy-status --json
spcli initialize-transparent-proxy
spcli start-transparent-proxy
spcli set-sharing-modes both
spcli sharing-status --json
spcli start-sharing
spcli stop-sharing
spcli stop-transparent-proxy
連線、活動與日誌
使用清單傳回的 ID 精確查詢；詳細資料以 JSON 文字傳回。
spcli group-status "engineering"
查看群組結果及各成員的連線狀態。
spcli group-status "engineering" --json
spcli connect-and-wait "Build Tunnel" 30
等待連線就緒；失敗或逾時會傳回錯誤。
spcli connect-and-wait "Build Tunnel" 30
spcli preview-route
預測目前情境下的本機規則比對；不測試實際連通性。
spcli preview-route example.com 443 com.apple.Safari TCP --json
spcli test-proxy
測試已儲存的代理伺服器，傳回結果、原因及耗時。
spcli test-proxy "proxy-id" --json
spcli list proxy-flows
查看代理活動；LAN 查看共享，ALL 查看兩者。
spcli list proxy-flows --json
spcli list sharing-flows
查看網路共享連線。
spcli list sharing-flows --json
spcli end-flow
依 ID 關閉一條已連線的流。
spcli end-flow "flow-id"
spcli list logs
查看最近最多 200 筆已遮蔽敏感資訊的日誌，最新的在前。
spcli list logs --json
spcli log-detail
依 ID 查看近期日誌的完整紀錄。
spcli log-detail "log-id" --json
終端機範例
將 spcli 與常用 shell 工具組合，編寫你自己的自動化流程。
列出連線
spcli list connections
輸出範例
Build Tunnel (Local Forward), Debug DB (Remote Forward), Dev Box SOCKS (SOCKS Proxy)
啟動連線並等待就緒
spcli connect "Build Tunnel (Local Forward)"
until [ "$(spcli status "Build Tunnel (Local Forward)")" = "connected" ]; do sleep 1; done
echo "Tunnel is up"
連線也可能停留在 authentication failed、unknown host key、host key changed、invalid 或 error 狀態，因此在依賴它之前請先檢查狀態。
啟動或停止連線群組
spcli connect-group "engineering"
spcli disconnect-group "engineering"
以 JSON 讀取狀態
spcli status "Build Tunnel (Local Forward)" --json
輸出範例
{ "connection" : "Build Tunnel (Local Forward)", "status" : "connected" }
自動化權限
終端機第一次執行 spcli 時，macOS 會詢問是否允許終端機控制 Secure Pipes。請在「系統設定」>「隱私權與安全性」>「自動化」中允許。
完整 spcli 說明（與軟體一致，英文）
spcli — control Secure Pipes from the command line
Usage: spcli <command> [arguments]
Application:
spcli start Start Secure Pipes without showing its window
spcli show Show and activate the Secure Pipes window
spcli hide Hide Secure Pipes windows
spcli shutdown Quit Secure Pipes immediately
Connections and groups:
Connection arguments accept a UUID, unique name or full display name.
spcli list connections [--json] List configured connections
spcli connect "<connection>" Start a connection
spcli disconnect "<connection>" Stop a connection
spcli status "<connection>" [--json]
Show the status of a connection
spcli wait "<connection>" [seconds]
Wait until connected (1-45 seconds)
spcli connect-and-wait "<connection>" [seconds]
Start and wait for a ready connection
spcli list remote-desktops [--json] List RDP/VNC profiles (redacted)
spcli get-remote-desktop "<ID>" [--json]
spcli create-remote-desktop '<JSON>' Create name/values; preset host supported
spcli update-remote-desktop '<JSON>' Update id/name/values
spcli open-remote-desktop "<ID>" Start tunnel and open client
spcli delete-remote-desktop "<ID>" Delete disconnected profile
spcli list groups [--json] List connection groups
spcli group-status "<group>" [--json]
Show the status of a group
spcli connect-group "<group>" Start all connections in a group
spcli disconnect-group "<group>" Stop all connections in a group
Rules and scenarios:
spcli list rules [--json] List proxy rules and scenario assignments
spcli preview-route <host> <port> <bundle-id> [TCP|UDP] [--json]
Predict the current local rule decision
spcli enable-rule "<name|ID>" Enable a proxy rule
spcli disable-rule "<name|ID>" Disable a proxy rule
spcli set-rule-scenarios "<rule>" "<scenario>" ["<scenario>" ...]
Replace assignments; Universal clears them
spcli list scenarios [--json] List usage scenarios (ID, name, active state)
spcli current-scenario Show the active usage scenario
spcli switch-scenario "<name|ID>"
Switch scenario; active connections reconnect
spcli create-scenario "<name>" Create a usage scenario
spcli rename-scenario "<old>" "<new>"
Rename a scenario
spcli delete-scenario "<name|ID>"
Delete a scenario; orphaned rules become universal
Task plans:
spcli list task-plans [--json] List scheduled plans (redacted)
spcli get-task-plan "<ID>" [--json]
Read one scheduled plan
spcli create-task-plan '<JSON>' Create a validated task plan
spcli update-task-plan '<JSON>' Update a plan; JSON must include id
spcli delete-task-plan "<ID>" Delete a scheduled plan
spcli enable-task-plan "<ID>" Enable a plan
spcli disable-task-plan "<ID>" Disable a plan
spcli run-task-plan "<ID>" Run a plan immediately
JSON repeat: 0 once, 1 daily, 2 weekdays,
3 custom weekdays, 4 app launch, 5 app quit,
6 custom dates; dates are ISO 8601 or YYYY-MM-DD
Proxies and sharing:
spcli list proxy-servers [--json] List proxy servers without credentials
spcli test-proxy <name|ID> [--json]
Test a proxy server
spcli transparent-proxy-status [--json]
Show transparent proxy and extension state
spcli initialize-transparent-proxy
Install or repair the system extension
spcli start-transparent-proxy Start the transparent proxy
spcli stop-transparent-proxy Stop the transparent proxy
spcli sharing-status [--json] Show sharing, gateway and mode states
spcli set-sharing-modes <proxy|gateway|both|off>
Select network sharing modes
spcli start-sharing Start the selected sharing modes
spcli stop-sharing Stop gateway and network sharing
Activity and logs:
spcli list flows [--json] List proxy and sharing connections
spcli list proxy-flows [--json] List transparent proxy connections
spcli list sharing-flows [--json] List network sharing connections
spcli end-flow <flow-id> End a connected flow
spcli list logs [--json] Show the 200 newest redacted logs
spcli log-detail <log-id> [--json]
Show the complete recent log record
Options:
--json Machine-readable JSON output for supported commands
--help Show this help
--version Show the spcli version
Exit codes:
0 success 1 Secure Pipes reported an error 2 invalid usage
3 application not found / not launchable / Automation permission denied
4 Apple Event send, timeout, or reply failure
基於 Secure Pipes 2.0.17 · 更新於 2026 年 11 月 9 日