spcli — Command Reference
Use the same command descriptions and copyable examples as Automation in the Mac app. The references include existing commands and additions in 2.0.17.
The sections below are synchronized from the Mac app’s bundled automation reference, including each command’s explanation and complete script examples. Replace demonstration names and IDs before running commands. Examples can change real connections and settings; do not run the entire page as a script.
Remote Desktop
spcli list remote-desktops --json
List saved RDP/VNC profiles.
spcli list remote-desktops --json
spcli get-remote-desktop "<ID>"
Read a profile by ID; credentials are omitted.
spcli get-remote-desktop "DESKTOP-ID"
spcli create-remote-desktop <JSON>
Create from name and values. Use hostProfileUUID for a preset host.
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>
Update by id; name and values are optional.
spcli update-remote-desktop '{"id":"DESKTOP-ID","values":{"remoteDesktopOptions":{"screen mode id":1,"audiomode":2}}}'
spcli open-remote-desktop "<ID>"
Start the SSH tunnel if needed, then open the saved RDP/VNC client.
spcli open-remote-desktop "DESKTOP-ID"
spcli delete-remote-desktop "<ID>"
Delete a disconnected profile by ID.
spcli delete-remote-desktop "DESKTOP-ID"
Usernames may be written but are never returned. Set SSH passwords and identity files in Secure Pipes; enter desktop passwords in the client.
About spcli
spcli is a small command-line tool included with Secure Pipes. It drives Secure Pipes straight from Terminal, so you can start, stop, and check saved connections from shell scripts, aliases, or scheduled tasks.
spcli uses the same AppleScript commands and Automation permission. Starting network sharing may open the existing approval window.
Install spcli
spcli is bundled with Secure Pipes but is not on your PATH until you install it. Use the command-line tool row under Backup in Preferences > General.
Click Install spcli. Secure Pipes links spcli into a folder on your PATH, such as /usr/local/bin or /opt/homebrew/bin.
If that folder needs permission, approve the one-time administrator prompt.
Open a new Terminal window and run spcli --help to confirm it is available.
To remove it later, click Uninstall spcli in the same row.
Check the install
spcli --version
spcli --help
Command Reference
Type spcli, then a command. Put connection and group names in quotation marks.
spcli start
Start Secure Pipes without showing its window.
spcli start
spcli show
Show and activate the Secure Pipes window.
spcli show
spcli hide
Hide the Secure Pipes windows while connections keep running.
spcli hide
spcli shutdown
Quit Secure Pipes and stop active connections.
spcli shutdown
spcli list connections
List the configured connections. Add --json for machine-readable output.
spcli list connections
spcli list groups
List the tags used as connection groups. Add --json for machine-readable output.
spcli list groups
spcli connect "<connection>"
Start a saved connection.
spcli connect "Build Tunnel (Local Forward)"
spcli disconnect "<connection>"
Stop a saved connection.
spcli disconnect "Build Tunnel (Local Forward)"
spcli status "<connection>"
Show the current state of a connection.
spcli status "Build Tunnel (Local Forward)"
spcli connect-group "<group>"
Start a group using its saved startup settings.
spcli connect-group "engineering"
spcli disconnect-group "<group>"
Stop a group and its member connections.
spcli disconnect-group "engineering"
spcli list task-plans
List scheduled task plans without returning credentials.
spcli list task-plans --json
spcli create-task-plan '<JSON>'
Create a validated task plan from JSON. Use IDs for connections and groups; do not include credentials.
spcli create-task-plan '{"id":"work-start","hour":9,"minute":0,"repeat":2,"actions":[{"type":"start_group","id":"work"}]}'
spcli update-task-plan '<JSON>'
Update a task plan by including its existing ID and the fields to save.
spcli update-task-plan '{"id":"work-start","hour":8,"minute":45,"repeat":2,"actions":[{"type":"start_group","id":"work"}]}'
spcli enable-task-plan "<ID>"
Enable or disable a saved plan, or run it immediately for a test.
spcli enable-task-plan "work-start"
spcli disable-task-plan "work-start"
spcli run-task-plan "work-start"
Options
--json
Machine-readable JSON for supported commands.
--help
Show the full usage text.
--version
Show the spcli version.
Exit codes
0 success, 1 Secure Pipes reported an error, 2 invalid usage, 3 Secure Pipes not found or Automation permission denied, 4 the Apple Event could not be sent.
Rules and scenarios
Use an ID or a unique name for rule changes and scenario switching. Switching scenarios closes and reconnects active connections. Deleting a scenario keeps its rules; rules with no other scenario become universal.
spcli list rules
List rules in order with their ID, name, enabled state, action and scenario IDs.
spcli list rules --json
spcli list scenarios
List scenarios, including Universal, with their ID, name and active state.
spcli list scenarios --json
spcli current-scenario
Show the name of the currently active scenario.
spcli current-scenario
spcli switch-scenario "Office"
Switch by ID or unique name and reconnect affected connections under the selected rules.
spcli switch-scenario "Office"
spcli enable-rule "Work websites"
Enable a rule by ID or unique name.
spcli enable-rule "Work websites"
spcli disable-rule "Work websites"
Disable a rule without deleting it.
spcli disable-rule "Work websites"
spcli set-rule-scenarios "Work websites" "Office" "Travel"
Replace a rule's scenario assignments. Use Universal to make the rule universal.
spcli set-rule-scenarios "Work websites" "Office" "Travel"
spcli create-scenario "Travel"
Create a scenario with a unique name and return its ID.
spcli create-scenario "Travel"
spcli rename-scenario "Travel" "Mobile work"
Rename a scenario while keeping its rule assignments.
spcli rename-scenario "Travel" "Mobile work"
spcli delete-scenario "Travel"
Delete a scenario without deleting its rules. Rules with no remaining scenario become universal.
spcli delete-scenario "Travel"
Combined example
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"
Proxy and network sharing
Sharing uses the saved address, port and authentication settings. Starting it opens the existing approval window when needed. Gateway mode keeps its risk confirmation and macOS authorization.
spcli list proxy-servers
List configured proxy servers with their ID, name, type and endpoint, without credentials.
spcli list proxy-servers --json
spcli transparent-proxy-status
Show the transparent proxy's running state, system extension state and version match.
spcli transparent-proxy-status --json
spcli initialize-transparent-proxy
Install or repair the system extension. macOS may request approval; this does not start the transparent proxy.
spcli initialize-transparent-proxy
spcli start-transparent-proxy
Start the transparent proxy with the current routing rules after its extension is ready.
spcli start-transparent-proxy
spcli stop-transparent-proxy
Stop the transparent proxy. Network sharing depends on this service.
spcli stop-transparent-proxy
spcli sharing-status
Show sharing and gateway states. Modes are effective values while running and saved values while stopped.
spcli sharing-status --json
spcli set-sharing-modes both
Choose proxy, gateway, both or off for the next manual start. Stop sharing before changing modes.
spcli set-sharing-modes both
spcli start-sharing
Start the selected modes with the saved address, port and authentication settings. Confirmation may be required.
spcli start-sharing
spcli stop-sharing
Stop the gateway and shared proxy listener. The transparent proxy remains running.
spcli stop-sharing
Combined example
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
Connections, activity and logs
Use IDs from list commands for precise lookups. Details are returned as JSON text.
spcli group-status "engineering"
Read the group result and each member's state.
spcli group-status "engineering" --json
spcli connect-and-wait "Build Tunnel" 30
Wait until a connection is ready; failure or timeout returns an error.
spcli connect-and-wait "Build Tunnel" 30
spcli preview-route
Predict the local rule in the current scenario; this does not test connectivity.
spcli preview-route example.com 443 com.apple.Safari TCP --json
spcli test-proxy
Test a saved proxy and return success, reason and duration.
spcli test-proxy "proxy-id" --json
spcli list proxy-flows
Read proxy activity; use LAN for sharing or ALL for both.
spcli list proxy-flows --json
spcli list sharing-flows
Read network sharing activity.
spcli list sharing-flows --json
spcli end-flow
Close one connected flow by its ID.
spcli end-flow "flow-id"
spcli list logs
Read up to 200 recent redacted logs, newest first.
spcli list logs --json
spcli log-detail
Read a complete recent log record by ID.
spcli log-detail "log-id" --json
Terminal examples
Combine spcli with ordinary shell tools to script your workflows.
List connections
spcli list connections
Example result
Build Tunnel (Local Forward), Debug DB (Remote Forward), Dev Box SOCKS (SOCKS Proxy)
Start a connection and wait for it
spcli connect "Build Tunnel (Local Forward)"
until [ "$(spcli status "Build Tunnel (Local Forward)")" = "connected" ]; do sleep 1; done
echo "Tunnel is up"
A connection can also settle on authentication failed, unknown host key, host key changed, invalid, or error, so check the status before relying on it.
Start or stop a group
spcli connect-group "engineering"
spcli disconnect-group "engineering"
Read status as JSON
spcli status "Build Tunnel (Local Forward)" --json
Example result
{ "connection" : "Build Tunnel (Local Forward)", "status" : "connected" }
Automation permission
The first time Terminal runs spcli, macOS asks you to let Terminal control Secure Pipes. Allow it in System Settings under Privacy & Security > Automation.
Full spcli help (English, as in the app)
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
Based on Secure Pipes 2.0.17 · Updated November 9, 2026