iOS Shortcuts

ZestSSH provides native App Intents for iOS Shortcuts, enabling you to trigger SSH commands, snippets, and connections from the Shortcuts app, Siri voice commands, or home screen widgets. These intents are available on iOS 16.0 and later.

Available Intents

ExecuteSSHCommandIntent — “Run SSH Command”

Executes a shell command on a saved SSH connection.

Parameters:

Parameter	Type	Required	Description
Connection Name	String	Yes	The label or ID of the saved connection
Command	String	Yes	The shell command to execute
Timeout	Int	No	Timeout in seconds (default: 30, range 5-300, stepper control)

Returns: A string result — either “Command sent to ZestSSH” on success or an error message.

RunSSHSnippetIntent — “Run SSH Snippet”

Runs a saved command snippet on a connection.

Parameters:

Parameter	Type	Required	Description
Connection Name	String	Yes	The label or ID of the saved connection
Snippet Name	String	Yes	The name of the saved snippet to run

Returns: A string result confirming the snippet was sent.

ConnectSSHIntent — “Connect via SSH”

Opens ZestSSH and initiates a connection to a saved server.

Parameters:

Parameter	Type	Required	Description
Connection Name	String	Yes	The label or ID of the saved connection

Returns: No value (opens the app).

How It Works

All three intents have openAppWhenRun set to true. When triggered, the intent:

1. Builds a zestssh:// URL with the parameters (e.g., zestssh://execute?connection=web1&command=uptime&timeout=30).
2. Stores the full intent payload as JSON in a shared UserDefaults suite (group.com.affluentlabs.zestssh) under the key pending_automation, so the Flutter side can access it.
3. Opens the URL via UIApplication.shared.open(), which launches ZestSSH.
4. ZestSSH picks up the automation request from the deep link and/or the shared UserDefaults, processes it, and executes the command.

The result string is returned to the Shortcuts app for use in subsequent shortcut steps.

Siri Phrases

ZestSSH registers Siri phrase suggestions via AppShortcutsProvider. Users can trigger actions by saying:

Run SSH Command:

• “Run SSH command with ZestSSH”
• “Execute command on server with ZestSSH”
• “Run command with ZestSSH”

Run SSH Snippet:

• “Run SSH snippet with ZestSSH”
• “Execute snippet with ZestSSH”

Connect via SSH:

• “Connect to server with ZestSSH”
• “SSH connect with ZestSSH”
• “Open SSH connection with ZestSSH”

When using Siri, iOS prompts for the required parameters (connection name, command, etc.) if they are not provided in the phrase.

Setting Up a Shortcut

Quick Method: Shortcuts App

1. Open the Shortcuts app on your iPhone or iPad.
2. Tap + to create a new shortcut.
3. Search for “ZestSSH” in the action library.
4. Select one of the three available actions (Run SSH Command, Run SSH Snippet, Connect via SSH).
5. Fill in the parameters.
6. Optionally add the shortcut to your home screen or assign it to a Siri phrase.

Example: Daily Server Check

1. Create a new shortcut named “Server Health”.
2. Add action: Run SSH Command (ZestSSH).
3. Set Connection Name to your server’s label (e.g., “production-web”).
4. Set Command to uptime && df -h / && free -h.
5. Set Timeout to 30.
6. Add action: Show Result to display the output.
7. Optionally add to a home screen widget for one-tap access.

Example: Quick Deploy

1. Create shortcut “Deploy Staging”.
2. Add action: Run SSH Command.
3. Connection Name: “staging”.
4. Command: cd /var/www/app && git pull origin develop && systemctl restart app.
5. Timeout: 120.
6. Add action: Show Notification with the result text.

Example: Run a Snippet

1. Create shortcut “Check Docker”.
2. Add action: Run SSH Snippet.
3. Connection Name: “docker-host”.
4. Snippet Name: “Running Containers”.

Automation Triggers

Combine ZestSSH shortcuts with iOS automation triggers in the Shortcuts app:

• Time of Day: run a health check every morning.
• Arrive/Leave Location: connect to the office server when arriving.
• Low Power Mode: check battery-draining services on your server.
• NFC Tag: tap an NFC tag to trigger a deployment.

Note: some automation triggers require confirmation on-screen before running.

Limitations

App must open: all ZestSSH intents set openAppWhenRun = true, meaning the app launches (at least briefly) to process the request. iOS does not allow background SSH connections from App Intents without the app being in the foreground. This is an iOS platform limitation.

No background execution: unlike Android intents which can run entirely in the background via a broadcast receiver, iOS requires the app to be active. The app opens, processes the command, and can return to the background afterward, but there will be a visible app switch.

No batch support: the iOS intents do not currently include a batch action. For multi-server operations, create multiple shortcut steps (one per server) or use a workflow URL: zestssh://workflow?name=NAME&key=KEY.

API key handling: the iOS intents use shared UserDefaults to pass data to the Flutter layer. The API key is included as part of the intent payload stored in the shared UserDefaults suite, and is validated at the Flutter layer when the deep link is processed.

Variable support: the Run SSH Snippet intent does not expose snippet variable parameters. Snippets with variables will run with empty/unresolved placeholders unless the variables have been pre-filled. For variable-dependent snippets, use the URL scheme approach instead: zestssh://snippet?connection=X&name=Y&var_HOST=Z&key=KEY.

Troubleshooting

• “ZestSSH” not appearing in Shortcuts: ensure you have launched ZestSSH at least once after installation. iOS discovers App Intents on first launch.
• Shortcut fails silently: check that the connection name matches exactly (including capitalization). The intent passes the name as-is to the URL scheme.
• Timeout errors: increase the timeout parameter for commands that take longer to complete. The default 30 seconds may not be enough for complex operations.