截图使用英文界面，图表随指南语言切换。控件名称可能因您选择的应用语言而异。
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 日