Terminal Widget Shortcuts

Use Terminal Widget’s App Intents in Shortcuts.app for native automation that does not require shell commands or manual URL encoding.

Shortcuts.app showing TerminalWidget actions and the Update TerminalWidget configuration options

Available Shortcuts Actions

Terminal Widget exposes intent actions for common update types:

Render Widget: full payload action (text, icon, progress, chart, image, colors, theme, layout)
Render Text: quick text/icon update
Render Chart: chart update with format options
Render Progress: progress update with style options
Render Image: image update with optional filters/layout controls
Render Table: table render from CSV/TSV/JSON data source

These map to the same validation/rendering pipeline used by CLI, AppleScript, and URL scheme updates.

On Render Widget (Update Terminal Widget), optional Label Y adds a left y-axis to numeric charts, and Timestamp shows the last CLI/URL update time in the caption area (with or without Caption). Chart accepts space-separated numbers, slash-separated grouped sparkline/bar series (for example 0 1 5 2/1 2 5 3, up to four series), rangebar low-high pairs, or JSON (flat or nested numeric arrays). Use Chart Format sparkline/bar for grouped slash input. Comma-separated Foreground colors use the first value for text/icons and the rest for series colors. Chart Bar Style Glass applies to sparkline/bar, waveform, range bar, matrix, and delta charts, and to circle progress rings when Progress Format is Circle (chart data not required for circle glass). Render Chart and Render Progress expose the same chart and bar-style fields where applicable (progress can use Caption for [n%] and Timestamp for the update time). Optional Notify on change persi

On Render Widget, optional action fields can assign what happens when the widget is tapped or clicked:

Action Kind: open-url, open-app, run-shortcut, or run-command
Action Value: the URL, macOS bundle identifier, Shortcut name, or shell command
Clear Action: removes the saved tap/click action for the target

Actions are saved with the target payload and sync through iCloud. On macOS, all four action kinds are supported. On iOS, URL and Shortcut actions are supported; synced macOS-only app and shell actions fall back to the normal widget open/update behavior.

Build Your First Shortcut

Open Shortcuts.app and create a new shortcut.
Add the Render Widget action from Terminal Widget.
Set Target (for example widget1).
Fill any fields you want to update (Text, Icon, Progress, etc.).
Run the shortcut and confirm the widget refreshes.

Passing Data Into Actions

Shortcuts variables can drive any field in the action.

From Input Prompt

Add Ask for Input (Prompt: Widget text).
Add Render Text.
Set Target to widget1.
Set Text to Provided Input.

From Dictionary/Data

Build a Dictionary with keys like target, text, progress.
Add Get Dictionary Value actions.
Feed each result into Render Widget parameters.

From Web/API Data

Add Get Contents of URL.
Parse JSON fields (for example status or numeric metrics).
Convert/format values if needed.
Pass results into Render Widget, Render Chart, or Render Progress.

Pattern Examples

Trigger: Time of Day automation
Actions:
1. Get Contents of URL (status endpoint)
2. Get Dictionary Value (message, progress)
3. Render Widget (target: widget1, text from message, progress from progress)

Trigger: run from Share Sheet, Finder Quick Action, or manual run
Actions:
1. Run Script over SSH or Get File metadata
2. conditional branch (If)
3. Render Text with icon set to success/failure symbol

Trigger: schedule every 15 minutes
Actions:
1. fetch metrics
2. build list of numbers
3. join numbers as chart input
4. Render Chart with chosen chart format and optional caption. Use rangebar with values like 1-3 2-3 1-4 for range bars.

Trigger: manual or scheduled
Actions:
1. Render Chart with Chart set to 0 1 5 2/1 2 5 3, Chart Format Bar or Sparkline, optional Foreground #cc0000,#00cc00,#0000cc, optional Annotation and Chart Bar Style Glass.

Circle Progress with Glass Ring

Actions:
1. Render Progress with Progress 72, Progress Format Circle, Chart Bar Style Glass, optional Caption.

Trigger: manual run from Shortcuts
Actions:
1. Add Render Widget
2. Set Target to widget1
3. Set Text and Icon for the visible widget state
4. Set Action Kind to open-url
5. Set Action Value to the destination URL

Use run-shortcut with a Shortcut name to make the widget run another Shortcut when tapped. Use open-app with a macOS bundle identifier or run-command with a shell command for macOS-only launcher widgets.

Data Formatting Notes

Progress expects 0...100.
Chart values should be numeric and in display order. For grouped sparkline/bar columns, separate series with / (for example 10 20 30/12 18 25); use Chart Format sparkline or bar. Up to four series and 128 points per series.
Chart Bar Style Glass works with sparkline/bar, waveform, range bar, matrix, delta charts, and with Progress Format Circle (no chart field needed for circle glass).
Foreground comma-separated lists: first color for text/icons, remaining colors for grouped chart series.
Colors accept hex/rgb/rgba style values.
Table input should point to readable CSV/TSV/JSON content.
Images can be local files or remote URLs.
Action Kind accepts open-url, open-app, run-shortcut, or run-command.
Action Value must match the kind: URL for open-url, bundle identifier for open-app, Shortcut name for run-shortcut, or shell command for run-command.

If optional fields are omitted, those values are left unchanged (or reset by intent defaults where applicable).

Mixing with URL Scheme and CLI

You can combine integrations in one workflow:

Use Shortcuts for user input and scheduling.
Use URL scheme links for quick launcher-style actions.
Use CLI in shell-centric workflows (build scripts, cron, CI agents).

Related docs:

iOS Shortcuts

All Shortcut actions are also available on iOS.