Terminal Widget

Terminal Widget CLI

Use the Terminal Widget command-line tool to update widgets from scripts, shell commands, and automation.

Usage

terminal-widget [--target NAME] [--text "STRING"] [--icon "SF_SYMBOL"] [--font "FONT NAME"] [--fg COLOR] [--bg COLOR] [--alpha A] [--progress N] [--sparkline "N N ..."] [--image PATH_OR_URL] [--padding N|--fullsize] [--command "CMD"] [--theme|--mode system|light|dark]

Options

  • --target NAME Widget to update (matches Edit Widget “Target name”). If omitted, uses the last target written (.lastTarget), else the first registered widget name (widget1, widget2, …), else widget1.
  • --text STRING Text line (shown above the progress bar when both are set)
  • --icon SF_SYMBOL SF Symbol name; shown before text, or before the progress bar, or alone centered if nothing else is set
  • --font "FONT NAME" Installed system font name used for text rendering (omitting --font resets to default)
  • --foreground COLOR Text/icon color (alias: --fg). Accepts RRGGBB, #RRGGBB, rgb(r,g,b), or rgba(r,g,b,a).
  • --background COLOR Widget background color (alias: --bg). Accepts RRGGBB, #RRGGBB, rgb(r,g,b), or rgba(r,g,b,a).
  • --alpha A Override alpha channel for --foreground/--background this update (0.0...1.0).
  • --progress N Integer 0-100 for a progress bar; omit to hide the bar on this update
  • --sparkline VALUES Bar sparkline: numbers separated by spaces or commas (alias: --spark). Y-axis is min…max of the series; bar height uses 101 levels. Omit to clear. Max 128 points.
  • --image IMAGE_PATH Absolute/relative image path or an http(s) image URL
  • --padding N Widget content padding in points (0-64). Useful to reduce margins around images.
  • --fullsize Shortcut for --padding 0 (edge-to-edge content)
  • --command COMMAND Run command and use its stdout as text
  • --theme MODE system, light, or dark
  • --mode MODE Alias for --theme (system, light, or dark)
  • --help Show this help

Notes

  • If both --text and --command are supplied, --command output wins.
  • If --text is omitted and stdin is piped, stdin is used as text.
  • Omitting both --text and --command clears the widget text line (for example: terminal-widget --progress 50 only updates the bar).
  • --command runs with zsh -lc (login env + Homebrew paths). Fish functions are not visible; use a script on PATH or --text.
  • Icon-only: pass --icon with no --text, --command, --image, --progress, or --sparkline to show a centered symbol.
  • Omit --foreground/--background on a later update to reset those colors to theme defaults.
  • --padding and --fullsize persist in payload until changed again for that target.
  • Updates the App Group JSON + prefs, then notifies the app via SIGUSR1 and terminalwidget:///update?sync=1&target=....

Command Examples

terminal-widget --target widget1 --text "Deploy complete" --icon "checkmark.circle.fill" --fg "#22c55e"
terminal-widget --target widget2 --command "pmset -g batt | head -1"
terminal-widget --target widget3 --image "https://picsum.photos/800/400" --fullsize
terminal-widget --target widget1 --progress 67 --text "Rendering"
terminal-widget --target widget1 --sparkline "5 12 8 21 34 55 89"

URL Scheme Examples

terminalwidget://update?target=widget1&text=Backup%20Complete&icon=externaldrive.fill
terminalwidget://update?target=widget2&progress=42&text=Syncing
terminalwidget://update?target=widget3&image=https%3A%2F%2Fpicsum.photos%2F640%2F360&padding=0
terminalwidget://update?target=widget1&sparkline=4,8,15,16,23,42
terminalwidget://update?target=widget2&theme=dark&fg=%23ffffff&bg=%23111417