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] [--chart "N N ..." --chart-format MODE] [--caption] [--image PATH_OR_URL] [--padding N|fill|--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
  • --chart VALUES Chart series values separated by spaces or commas. Omit to clear. Max 128 points.
  • --chart-format MODE Chart style (default: sparkline):
    • sparkline (aliases: spark, bar): bar sparkline scaled min..max
    • graph (alias: line): connected line with point markers
    • waveform (alias: wave): centered mirrored bars interpolated between values
    • area: line graph with area fill under the curve
    • lollipop: stems from baseline with dots at values
    • strip (alias: dot): dot/strip plot with no connecting line
    • radial: circular/radial connected plot
    • delta: positive/negative bars showing change between adjacent points
    • threshold: line graph with threshold guide line
    • smooth: smoothed curve interpolation
    • sine: half-sine interpolation between points
    • peak: line graph with peak point emphasized
    • matrix: heatmap matrix values mapped to foreground alpha
  • --caption Show centered [min/max] caption below the active chart
  • --image IMAGE_PATH Absolute/relative image path or an http(s) image URL
  • --full-width Alias for --padding fill (kept for compatibility)
  • --padding N|fill Widget content padding in points (0-64), or fill for orientation-aware image fill/crop mode
  • --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)
  • --verbose Print debug/status output and manual test URL
  • --help Show this help

Notes

  • If both --text and --command are supplied, --command output wins.
  • --text - reads text from stdin.
  • --chart - reads chart values from stdin.
  • Legacy stdin modes are still accepted: --sparkline -, --graph -, --waveform -, and --matrix -.
  • If neither --text - nor --chart - is used, piped stdin defaults to text when --text is omitted.
  • 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 chart flags to show a centered symbol.
  • Omit --foreground/--background on a later update to reset those colors to theme defaults.
  • --padding fill enables image fill mode: portrait images fill width/crop height, landscape images fill height/crop width.
  • --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 --chart "5 12 8 21 34 55 89" --chart-format sparkline
terminal-widget --target widget1 --chart "5 12 8 21 34 55 89" --chart-format sine --caption
terminal-widget --target widget1 --chart "0 2 8 3 5 1 0 9" --chart-format matrix
echo "Build complete" | terminal-widget --target widget1
---|---|
cat values.txt | terminal-widget --target widget1 --chart - --chart-format radial

Use the same data with different --chart-format values to compare styles quickly:

# Base sample data
DATA="1 4 9 3 8 2 7 5 10 6"

terminal-widget --target widget1 --chart "$DATA" --chart-format sparkline
terminal-widget --target widget1 --chart "$DATA" --chart-format graph
terminal-widget --target widget1 --chart "$DATA" --chart-format waveform
terminal-widget --target widget1 --chart "$DATA" --chart-format area
terminal-widget --target widget1 --chart "$DATA" --chart-format lollipop
terminal-widget --target widget1 --chart "$DATA" --chart-format strip
terminal-widget --target widget1 --chart "$DATA" --chart-format radial
terminal-widget --target widget1 --chart "$DATA" --chart-format delta
terminal-widget --target widget1 --chart "$DATA" --chart-format threshold
terminal-widget --target widget1 --chart "$DATA" --chart-format smooth
terminal-widget --target widget1 --chart "$DATA" --chart-format sine
terminal-widget --target widget1 --chart "$DATA" --chart-format peak
terminal-widget --target widget1 --chart "$DATA" --chart-format matrix

Add --caption to any chart command to show [min/max] below the chart.

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&chart=4,8,15,16,23,42&chartFormat=peak&caption=1
terminalwidget://update?target=widget2&theme=dark&fg=%23ffffff&bg=%23111417