AppleScript — 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.

Command Reference

Use the command phrase shown here. Add the connection name or group tag in quotation marks.

start

Start Secure Pipes without showing its window.

tell application "Secure Pipes" to start

show

Show the Secure Pipes window.

tell application "Secure Pipes" to show

hide

Hide the window while Secure Pipes and its connections keep running.

tell application "Secure Pipes" to hide

shutdown

Quit Secure Pipes and stop active connections.

tell application "Secure Pipes" to shutdown

list connections

List saved connections.

tell application "Secure Pipes" to list connections

list connection groups

List tags used as connection groups.

tell application "Secure Pipes" to list connection groups

connect connection "Build Tunnel (Local Forward)"

Start a saved connection.

tell application "Secure Pipes" to connect connection "Build Tunnel (Local Forward)"

disconnect connection "Build Tunnel (Local Forward)"

Stop a saved connection.

tell application "Secure Pipes" to disconnect connection "Build Tunnel (Local Forward)"

connection status "Build Tunnel (Local Forward)"

Read the current connection state.

tell application "Secure Pipes" to connection status "Build Tunnel (Local Forward)"

connect group "engineering"

Start a group using its saved startup settings.

tell application "Secure Pipes" to connect group "engineering"

disconnect group "engineering"

Stop a group and its member connections.

tell application "Secure Pipes" to disconnect group "engineering"

Use a connection UUID for scripts that must keep working after renaming. Unique names and full names with their type are also supported; UUIDs also distinguish connections with duplicate names.

Remote Desktop

list remote desktops

List saved RDP/VNC profiles.

tell application "Secure Pipes" to list remote desktops

get remote desktop "<ID>"

Read a profile by ID; credentials are omitted.

tell application "Secure Pipes" to get remote desktop "DESKTOP-ID"

create remote desktop <JSON>

Create from name and values. Use hostProfileUUID for a preset host.

tell application "Secure Pipes" to create remote desktop "{\"name\":\"Office desktop\",\"values\":{\"hostProfileUUID\":\"PRESET-HOST-ID\",\"remoteDesktopType\":\"rdp\",\"remoteDesktopUsername\":\"alice\",\"remoteHost\":\"192.168.1.91\"}}"

tell application "Secure Pipes" to create remote desktop "{\"name\":\"Office VNC\",\"values\":{\"hostProfileUUID\":\"PRESET-HOST-ID\",\"remoteDesktopType\":\"vnc\",\"remoteDesktopVNCOpenMode\":\"screenSharing\"}}"

update remote desktop <JSON>

Update by id; name and values are optional.

tell application "Secure Pipes" to update remote desktop "{\"id\":\"DESKTOP-ID\",\"values\":{\"remoteDesktopOptions\":{\"screen mode id\":1,\"audiomode\":2}}}"

open remote desktop "<ID>"

Start the SSH tunnel if needed, then open the saved RDP/VNC client.

tell application "Secure Pipes" to open remote desktop "DESKTOP-ID"

delete remote desktop "<ID>"

Delete a disconnected profile by ID.

tell application "Secure Pipes" to 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.

Task plans

Create and control scheduled actions. Task-plan reads are redacted and never return passwords or private-key contents.

list task plans

List saved task plans as redacted JSON.

tell application "Secure Pipes" to list task plans

get task plan "work-start"

Read one task plan by ID as redacted JSON.

tell application "Secure Pipes" to get task plan "work-start"

create task plan <JSON>

Create a validated plan. Use connection or group IDs in actions; do not include credentials.

tell application "Secure Pipes"
    create task plan "{\"id\":\"work-start\",\"hour\":9,\"minute\":0,\"repeat\":2,\"actions\":[{\"type\":\"start_group\",\"id\":\"work\"}]}"
end tell

update task plan <JSON>

Update a saved plan by including its existing ID and the fields to change.

tell application "Secure Pipes"
    update task plan "{\"id\":\"work-start\",\"hour\":8,\"minute\":45,\"repeat\":2,\"actions\":[{\"type\":\"start_group\",\"id\":\"work\"}]}"
end tell

set task plan enabled "work-start"

Enable or disable a plan without changing its schedule. The parameter defaults to true.

tell application "Secure Pipes" to set task plan enabled "work-start" enabled false
tell application "Secure Pipes" to set task plan enabled "work-start" enabled true

run task plan "work-start"

Run a saved plan immediately and return its JSON execution result.

tell application "Secure Pipes" to run task plan "work-start"

delete task plan "work-start"

Delete a saved plan by ID.

tell application "Secure Pipes" to delete task plan "work-start"

The JSON model supports repeat values 0–6, custom weekdays, ISO 8601 or YYYY-MM-DD date ranges, and validated actions. Use list connections and list connection groups first to obtain IDs.

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.

list proxy rules

List rules in order with their ID, name, enabled state, action and scenario IDs.

tell application "Secure Pipes" to list proxy rules

list scenarios

List scenarios, including Universal, with their ID, name and active state.

tell application "Secure Pipes" to list scenarios

current scenario

Show the name of the currently active scenario.

tell application "Secure Pipes" to current scenario

switch scenario "Office"

Switch by ID or unique name and reconnect affected connections under the selected rules.

tell application "Secure Pipes" to switch scenario "Office"

enable proxy rule "Work websites"

Enable a rule by ID or unique name.

tell application "Secure Pipes" to enable proxy rule "Work websites"

disable proxy rule "Work websites"

Disable a rule without deleting it.

tell application "Secure Pipes" to disable proxy rule "Work websites"

set rule scenarios "Work websites" scenarios {"Office", "Travel"}

Replace a rule's scenario assignments. Use Universal to make the rule universal.

tell application "Secure Pipes" to set rule scenarios "Work websites" scenarios {"Office", "Travel"}

create scenario "Travel"

Create a scenario with a unique name and return its ID.

tell application "Secure Pipes" to create scenario "Travel"

rename scenario "Travel" to "Mobile work"

Rename a scenario while keeping its rule assignments.

tell application "Secure Pipes" to rename scenario "Travel" to "Mobile work"

delete scenario "Travel"

Delete a scenario without deleting its rules. Rules with no remaining scenario become universal.

tell application "Secure Pipes" to delete scenario "Travel"

Combined example

tell application "Secure Pipes"
    set savedRules to list proxy rules
    set savedScenarios to list scenarios
    set selectedScenario to current scenario
    switch scenario "Office"
    enable proxy rule "Work websites"
    disable proxy rule "Work websites"
    set rule scenarios "Work websites" scenarios {"Office", "Travel"}
    set rule scenarios "Work websites" scenarios {}
    set newScenarioID to create scenario "Travel"
    rename scenario newScenarioID to "Mobile work"
    delete scenario newScenarioID
end tell

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.

list proxy servers

List configured proxy servers with their ID, name, type and endpoint, without credentials.

tell application "Secure Pipes" to list proxy servers

transparent proxy status

Show the transparent proxy's running state, system extension state and version match.

tell application "Secure Pipes" to transparent proxy status

initialize transparent proxy

Install or repair the system extension. macOS may request approval; this does not start the transparent proxy.

tell application "Secure Pipes" to initialize transparent proxy

start transparent proxy

Start the transparent proxy with the current routing rules after its extension is ready.

tell application "Secure Pipes" to start transparent proxy

stop transparent proxy

Stop the transparent proxy. Network sharing depends on this service.

tell application "Secure Pipes" to stop transparent proxy

network sharing status

Show sharing and gateway states. Modes are effective values while running and saved values while stopped.

tell application "Secure Pipes" to network sharing status

set sharing modes "both"

Choose proxy, gateway, both or off for the next manual start. Stop sharing before changing modes.

tell application "Secure Pipes" to set sharing modes "both"

start network sharing

Start the selected modes with the saved address, port and authentication settings. Confirmation may be required.

tell application "Secure Pipes" to start network sharing

stop network sharing

Stop the gateway and shared proxy listener. The transparent proxy remains running.

tell application "Secure Pipes" to stop network sharing

Combined example

tell application "Secure Pipes"
    set servers to list proxy servers
    set proxyState to transparent proxy status
    initialize transparent proxy
    start transparent proxy
    set sharing modes "both"
    set sharingState to network sharing status
    start network sharing
    stop network sharing
    stop transparent proxy
end tell

Connections, activity and logs

Use IDs from list commands for precise lookups. Details are returned as JSON text.

group status "engineering"

Read the group result and each member's state.

tell application "Secure Pipes" to group status "engineering"

wait for connection "Build Tunnel" timeout 30

Wait until a connection is ready; failure or timeout returns an error.

tell application "Secure Pipes" to wait for connection "Build Tunnel" timeout 30

preview route "example.com" port 443

Predict the local rule in the current scenario; this does not test connectivity.

tell application "Secure Pipes" to preview route "example.com" port 443 application "com.apple.Safari" transport "TCP"

test proxy server "proxy-id"

Test a saved proxy and return success, reason and duration.

tell application "Secure Pipes" to test proxy server "proxy-id"

list active flows "PROXY"

Read proxy activity; use LAN for sharing or ALL for both.

tell application "Secure Pipes" to list active flows "PROXY"

list active flows "LAN"

Read network sharing activity.

tell application "Secure Pipes" to list active flows "LAN"

end active flow "flow-id"

Close one connected flow by its ID.

tell application "Secure Pipes" to end active flow "flow-id"

list recent logs

Read up to 200 recent redacted logs, newest first.

tell application "Secure Pipes" to list recent logs

log detail "log-id"

Read a complete recent log record by ID.

tell application "Secure Pipes" to log detail "log-id"

Terminal Examples

Run one AppleScript command from Terminal with osascript. macOS may ask you to allow Terminal to control Secure Pipes.

List connection groups

osascript -e 'tell application "Secure Pipes" to list connection groups'

Example result

engineering, on-call

Group membership follows connection tags. Starting a group uses its saved order, parallel or sequential mode, and failure policy.

Start or stop a group

osascript -e 'tell application "Secure Pipes" to connect group "engineering"'
osascript -e 'tell application "Secure Pipes" to disconnect group "engineering"'

Inspect and control a connection

osascript -e 'tell application "Secure Pipes" to list connections'
osascript -e 'tell application "Secure Pipes" to connection status "Build Tunnel (Local Forward)"'
osascript -e 'tell application "Secure Pipes" to connect connection "Build Tunnel (Local Forward)"'

Run from Terminal

Save the file, then pass its path to osascript:

osascript ~/Scripts/Connect\ Tunnel.applescript

Run from Script Files

Save an example with the .applescript extension, then run it in Script Editor or with osascript.

Connect by name

Replace the example with a name returned by list connections.

on run
    -- Leave this blank to skip opening a URL after connecting.
    set postConnectURL to ""
    -- Get the saved connections.
    tell application "Secure Pipes"
        set availableConnections to list connections
    end tell
    if (count of availableConnections) is 0 then return

    set selectedConnection to choose from list availableConnections
    if selectedConnection is false then return
    set targetConnection to item 1 of selectedConnection

    -- Start the selected connection and wait up to 90 seconds.
    tell application "Secure Pipes"
        connect connection targetConnection
        set currentState to "connecting"
        repeat with attempt from 1 to 90
            set currentState to connection status targetConnection
            if currentState is "connected" then exit repeat
            if currentState is "authentication failed" or currentState is "unknown host key" or currentState is "host key changed" or currentState is "invalid" or currentState is "error" then exit repeat
            delay 1
        end repeat
    end tell
    -- Open the URL only if the connection comes up.
    if currentState is "connected" and postConnectURL is not "" then
        open location postConnectURL
    end if
    return currentState
end run

Choose and connect a group

Lists available tags, lets you choose one, and starts every connection in that group.

on run
    -- Get the groups saved in Secure Pipes.
    tell application "Secure Pipes"
        set availableGroups to list connection groups
    end tell
    -- Let the user know if there are no groups to choose from.
    if (count of availableGroups) is 0 then
        display dialog "No tagged connection groups are available." buttons {"OK"}
        return
    end if

    -- Ask which group to start.
    set selectedGroup to choose from list availableGroups
    if selectedGroup is false then return
    set targetGroup to item 1 of selectedGroup

    tell application "Secure Pipes"
        connect group targetGroup
    end tell
end run

Automation permission

When macOS asks, allow the app running the script, such as Terminal or Script Editor, to control Secure Pipes in System Settings under Privacy & Security > Automation.