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

Available Shortcuts Actions

TerminalWidget 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 TerminalWidget), optional Title, Title Alignment (Left, Center, Right; default Center when Title is set), Title Color, and Caption Text accept GitHub :emoji: shortcodes (for example :rocket:, :white_check_mark:), same as Text and Icon. Caption Text implies Caption and replaces auto [min/max] or [n%] text. Optional Label Y adds a left y-axis to numeric charts, and Timestamp shows the last CLI/URL update time at the bottom (with or without Caption / Caption Text). 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,

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

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

Passing Data Into Actions

Shortcuts variables can drive any field in the action.

From Input Prompt

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

From Dictionary/Data

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

From Web/API Data

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

Pattern Examples

Daily Status Widget

• 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)

Build Result Widget

• 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

Chart Snapshot Widget

• 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.

Grouped Sparkline Widget

• 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.

Launcher Widget

• 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:

• Recipes
• URL Scheme Documentation
• CLI Documentation
• AppleScript Documentation

iOS Shortcuts

All Shortcut actions are also available on iOS.

On iPhone and iPad, open TerminalWidget once after install and allow notifications in Settings > Notifications > TerminalWidget. The app relies on push notifications to pull iCloud widget updates in the background; without permission, Home Screen widgets may not refresh until you open the app. The same permission is required for notify-on-change alerts.