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

If you prefer Script Editor or AppleScript-based automation, see AppleScript Documentation.

Usage

terminal-widget [--target NAME] [--text "STRING"|--text -] [--no-wrap] [--ansi-mode auto|on|off] [--strip-colors] [--icon "SF_SYMBOL"] [--font "FONT NAME"] [--font-size POINTS] [--fit-text] [--fg COLOR] [--text-color COLOR] [--caption-color COLOR] [--title TEXT] [--title-alignment left|center|right] [--title-color COLOR] [--bg COLOR] [--alpha A] [--progress N --progress-format MODE --gradient-from COLOR --gradient-to COLOR --gradient-width N] [--chart "N N ..." --chart-format MODE --chart-height N[%] --neo-characters SET --base-zero|--base N --bar-radius N --chart-bar-style solid|glass] [--caption] [--caption-text TEXT] [--caption-left TEXT] [--caption-right TEXT] [--annotate] [--label-y] [--timestamp] [--image PATH_OR_URL] [--filter FILTER[:VALUE][,FILTER[:VALUE]...]] [--padding N|fill|--fullsize] [--theme|--mode system|light|dark] [--notify] [--no-notify] [--notify-once] [--json PATH|-] [--action-kind KIND --action-value VALUE|--clear-action]

terminal-widget completions [--shell fish|bash|zsh|all] [--name CMD] [--install] [--stdout]

Install CLI Command

If TerminalWidget.app is installed in /Applications, symlink terminal-widget into your user bin (no sudo required):

mkdir -p "$HOME/bin"
ln -sf /Applications/TerminalWidget.app/Contents/MacOS/TerminalWidget "$HOME/bin/terminal-widget"

You can create this symlink anywhere in your $PATH (for example ~/.local/bin, /opt/homebrew/bin, or /usr/local/bin).

If you prefer a shell function instead of a symlink, add one of these snippets:

# Bash (~/.bashrc or ~/.bash_profile)/Zsh (~/.zshrc)
terminal-widget() {
  /Applications/TerminalWidget.app/Contents/MacOS/TerminalWidget "$@"
}

# Fish (~/.config/fish/functions/terminal-widget.fish)
function terminal-widget
  /Applications/TerminalWidget.app/Contents/MacOS/TerminalWidget $argv
end

Shell Completions

Generate Fish, Bash, and Zsh completion scripts so you can tab-complete all terminal-widget flags and options.

• The command name in generated scripts defaults to the basename of the invoked binary ($0). Use --name CMD when a shell alias or function does not change argv[0] but completions should register under a different token.
• Without --install or --stdout, writes scripts into ./completions/ in the current directory: <name>.fish, <name>.bash, and _<name> (Zsh).
• --install auto-detects the current shell (or pass --shell) and writes to that shell’s user completion directory. Does not edit shell rc files.
• --stdout prints one shell’s script to stdout; requires a single --shell (fish, bash, or zsh, not all).

When invoked through the sandboxed app binary, --install cannot write to your shell configuration directory. Use --stdout and redirect it from your shell instead:

terminal-widget completions --shell fish --stdout > ~/.config/fish/completions/terminal-widget.fish

# Write scripts into ./completions for the current binary name
terminal-widget completions

# Install for the current shell (auto-detect)
terminal-widget completions --install

# Force shell + custom completion command name
terminal-widget completions --shell fish --name terminal-widget --install

terminal-widget completions --install
# then open a new Fish session (or source ~/.config/fish/completions/terminal-widget.fish)

Zsh users may need ~/.zsh/completions on fpath before compinit (for example fpath=(~/.zsh/completions $fpath) in ~/.zshrc). The CLI does not modify rc files for you.

Run terminal-widget completions --help for all subcommand flags.

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)
• --no-wrap Truncate long lines with an ellipsis instead of soft-wrapping; explicit line breaks are preserved (each line truncates independently)
• --ansi-mode MODE ANSI rendering for text (auto default, on, or off)
• --strip-colors Strip ANSI escape sequences from text before display
• --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)
• --font-size POINTS Base text size in points (> 0). Also acts as a minimum floor when full-width text fitting is enabled.
• --fit-text Scale text to fit widget width and height for text-only and text+icon layouts. This enables full-width text fitting behavior without enabling image fill mode.
• --foreground COLOR Text/icon color (alias: --fg). Accepts RRGGBB, #RRGGBB, rgb(r,g,b), or rgba(r,g,b,a). Comma-separated values use the first for text and icons and the full list as per-series colors for grouped sparkline/bar charts (up to four series).
• --text-color COLOR Color for the main --text line and default table cell styling; omit to use --foreground/theme.
• --caption-color COLOR Color for chart/progress captions ([min/max], [n%]), --caption-text, --caption-left / --caption-right footer text, and the optional --timestamp line; omit to use --foreground/theme.
• --title-color COLOR Color for --title; omit to use --foreground/theme.
• --background COLOR Widget background color (alias: --bg). Accepts RRGGBB, #RRGGBB, rgb(r,g,b), or rgba(r,g,b,a).
• --bg-gradient-from COLOR Background gradient start color. Accepts the same formats as --bg.
• --bg-gradient-to COLOR Background gradient end color. Accepts the same formats as --bg. Legacy alias: --bg-gradent-to.
• --bg-gradient-start DIR Background gradient start direction (n, s, e, w, nw, ne, sw, se). End point is automatically the opposite direction. Also accepts aliases top, right, bottom, left, topleft, topright, bottomleft, bottomright.
• --alpha A Override alpha channel for --foreground/--background/--text-color/--caption-color/--title-color this update (0.0...1.0).
• --progress N Integer 0-100 for a progress bar; omit to hide the bar on this update
• --progress-format bar|matrix|dots|stack|circle|watch|gradient|gradient-horizontal|gradient-vertical Progress style (default bar; gradient aliases to gradient-horizontal).
• --gradient-from COLOR Gradient start color for gradient progress formats. Uses the same color formats as --fg and --bg.
• --gradient-to COLOR Gradient end color for gradient progress formats. Uses the same color formats as --fg and --bg.
• --gradient-width N Gradient thickness in points (1-2048): width for vertical gradients, height for horizontal gradients.
• --chart VALUES Chart series values separated by spaces or commas. For grouped sparkline/bar columns, use slash-separated series (for example 0 1 5 2/1 2 5 3 draws two side-by-side sub-bars per column, up to four series). Use low-high pairs for rangebar. JSON input (via --json or structured refresh) may use a nested numeric array (for example [[0,1,5],[1,2,5]]). Omit to clear. Max 128 points per series.
• --base-zero Force chart y-axis scaling to start at 0 (alias for --base 0).
• --base N Force chart y-axis scaling to start at numeric baseline N instead of the series minimum.
• --chart-height N[%] Override chart height. Use a positive point value (for example 50) or percent of available chart area (for example 80%). Default behavior is 100%.
• --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
  • rangebar: contiguous range bars from low-high pairs such as 1-3,2-3,1-4
• --neo-characters katakana|ascii|binary Character set for neo chart format (default katakana).
• --bar-radius N Corner radius percentage for bar-shaped charts (0-100, default 0). Applies when chart format resolves to sparkline/bar or rangebar.
• --chart-bar-style solid|glass Optional bar/cell/ring appearance. glass adds a gradient “liquid glass” look to vertical bars, matrix cells, and circle progress rings. Valid with --chart and formats sparkline (or bar), waveform, rangebar, matrix, or delta, or with --progress and --progress-format circle (no chart data required for circle glass). Grouped slash syntax requires sparkline/spark/bar format. Default is solid / omitted. —|—|
• --table PATH|- Render tabular data from .csv, .tsv, or .json file path, or - to read from stdin
• --no-header Disable table header styling
• --grid MODE Table separators/striping mode:
  • none no grid lines (header divider still renders when header is enabled)
  • row (alias: horizontal) horizontal lines only
  • column (alias: vertical) vertical lines only
  • both horizontal + vertical lines
  • zebra alternating row and column striping
  • zebra-row alternating row striping only
  • zebra-column alternating column striping only
• --table-layout MODE Table column sizing mode:
  • auto content-measured widths (default)
  • equal uniform column widths based on available table width
• --zebra-opacity VALUE Zebra opacity scale for zebra grid modes:
  • Decimal values (0.0...1.0) are interpreted directly
  • Integer values (0...100) are interpreted as percentages
  • Default: 0.75
• --no-grid Alias for --grid none
• --title TEXT Optional single-line title at the top of chart, text, image, or progress widgets (inside padding; reduces main content height). GitHub :emoji: shortcodes expand like --text. Line breaks collapse to spaces; max 200 characters.
• --title-alignment MODE Horizontal alignment for --title: left, center (default), or right.
• --caption Show centered [min/max] caption below the active chart (or [n%] for bar progress when not using --caption-text); pairs with chart or progress updates
• --caption-text TEXT Custom footer text below widget content (replaces auto [min/max] or [n%]; implies --caption, so you do not need both). Works on any widget type with content (text, image, chart, progress, etc.). GitHub :emoji: shortcodes expand like --text. Line breaks are collapsed to spaces; max 200 characters.
• --caption-left TEXT Bottom-left label on the chart/progress footer (single line; line breaks are collapsed to spaces). Requires --chart (or a legacy chart flag) or --progress. Independent of --caption; layout scales and truncates so left, optional center (--caption or --caption-text), and right share one row.
• --caption-right TEXT Bottom-right label on the chart/progress footer (same rules as --caption-left).
• --annotate Show small value labels above chart points/bars (chart-only).
• --label-y Draw a left y-axis with five tick labels (high … low) for numeric charts (sparkline, graph, waveform, matrix, rangebar, and related chart families)
• --timestamp Show a short local “last updated” time at the bottom on any widget type when no chart/progress footer already shows it; pairs with --caption / --caption-text on charts and progress (time is taken from the update, not from WidgetKit refresh)
• --image IMAGE_PATH Absolute/relative image path or an http(s) image URL
  • ~ is accepted and expanded to your home directory.
  • When running the app-bundled CLI, macOS sandbox rules can block direct reads from Desktop/Documents/Downloads. If that happens, copy the image into ~/Library/Group Containers/group.brettterpstra.TerminalWidget/ and pass an absolute path.
• --filter FILTER[:VALUE][,FILTER[:VALUE]...] Apply one or more image filters (requires --image):
  • grayscale (aliases: gray, mono)
  • sepia[:0-100] (default intensity 100)
  • negative (aliases: invert, inverted)
  • pixelate[:1-200] (alias: pixellate, default scale 8)
  • blur[:0-100] (default radius 8)
  • alpha[:0-100] image opacity percent (0 transparent, 100 opaque). alpha=VALUE is also accepted.
  • Chain filters by repeating --filter and/or using comma-separated lists. Filters are applied in order.
  • --image cannot be combined with chart data (--chart or legacy chart flags); the CLI rejects that combination.
• --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)
• --theme MODE system, light, or dark
• --mode MODE Alias for --theme (system, light, or dark)
• --notify Persist notify-on-change for this widget target: when display content changes on this Mac or device, TerminalWidget posts a local Notification Center alert (setting is stored in the widget payload and syncs via iCloud so each device can notify itself after it applies updates). Also applies to the current update. On iOS and iPadOS, notification permission must be enabled for TerminalWidget in Settings.
• --no-notify Turn off persisted notify-on-change for this target.
• --notify-once Post a local notification only if this update changes display content; does not change the persisted notify setting.
• --json SOURCE Load widget fields from structured JSON. Use - for stdin, a file path, or an http(s) URL. Any explicit CLI flags override keys from the JSON document.
• --action-kind KIND Persist a widget tap/click action for this target. Values: open-url, open-app, run-shortcut, run-command, refresh (re-fetch --action-value on tap). Alias: --tap-action.
• --action-value VALUE Value for --action-kind: a URL (including the refresh endpoint for refresh), macOS bundle identifier, Shortcut name, or shell command. Alias: --tap-action-value.
• --clear-action Remove the persisted widget tap/click action for this target.
• --verbose Print debug/status output and manual test URL
• --help Show this help

Notes

• Piping: Run commands in your normal shell, then pipe stdout into the widget with --text -. That keeps your PATH, aliases, and shell functions available, and avoids sandbox limits that apply when the bundled terminal-widget binary runs subprocesses on your behalf.
• --text - reads text from stdin.
• --no-wrap truncates each line with tail ellipsis instead of soft-wrapping; newline-separated lines stay separate.
• --ansi-mode auto parses ANSI only when escape codes are present; --ansi-mode on always parses; --ansi-mode off leaves text untouched.
• --strip-colors removes ANSI control sequences (useful when command output includes terminal color codes but you want plain text).
• --chart - reads chart values from stdin.
• --table - reads table data from stdin.
• --json - reads a full structured widget document from stdin; explicit CLI options override JSON fields.
• Legacy stdin modes are still accepted: --sparkline -, --graph -, --waveform -, and --matrix -.
• If neither --text - nor --chart - nor --json - is used, piped stdin defaults to text when --text is omitted.
• Omitting --text (and not piping stdin as text) clears the widget text line (for example: terminal-widget --progress 50 only updates the bar).
• Icon-only: pass --icon with no --text, --image, --progress, or chart flags to show a centered symbol.
• Omit --foreground/--background/--text-color/--caption-color/--title-color on a later update to reset those colors to theme defaults.
• --text, --icon, --title, and --caption-text accept GitHub-style :shortcode: emoji aliases (for example :rocket: → 🚀), same as table cell strings in --table input.
• --padding fill enables image fill mode: portrait images fill width/crop height, landscape images fill height/crop width.
• Without --image, --padding fill/--full-width enables full-width text scaling (with a built-in inset) for text-only and text+icon layouts.
• --fit-text enables the same text fitting behavior for text-only and text+icon layouts, but without changing image fill behavior.
• --filter requires --image.
• --progress-format requires --progress.
• Grouped slash chart literals (0 1 2/3 4 5) require --chart-format sparkline, spark, or bar.
• --chart-bar-style glass with circle progress requires --progress-format circle (chart values optional).
• --gradient-from, --gradient-to, and --gradient-width require --progress.
• --padding and --fullsize persist in payload until changed again for that target.
• If only one of --bg-gradient-from/--bg-gradient-to is set, the other side falls back to --bg for that update (or the current theme default when --bg is omitted).
• Widget actions persist in payload until changed or cleared. iOS can open URLs and run Shortcuts by URL scheme; macOS also supports launching apps by bundle identifier and running shell commands through TerminalWidget.
• Updates the App Group JSON + prefs, then posts widget refresh notifications from CLI mode (without launching a new app instance).

Examples

Script and Shortcut recipes that update TerminalWidget live are published in the Recipes index, including launchd scheduling notes and copy-paste scripts.

• Browse recipes
• Submit your own recipe

GitHub emoji shortcodes

These fields expand :name: aliases to emoji (for example :rocket: → 🚀, :+1: → 👍):

• --text and piped/command stdin used as text
• --icon
• --title and --caption-text
• Table cells in --table CSV/TSV/JSON input

:emoji: does not apply to --caption-left, --caption-right, or chart numeric literals.

Command Examples

For screenshot-ready emoji/table capture commands, see Widgets Gallery and Modes.

terminal-widget --target widget1 --text "Deploy complete" --icon "checkmark.circle.fill" --fg "#22c55e"
terminal-widget --target widget1 --text "A very long status message that should stay on one line and truncate with an ellipsis" --no-wrap
echo -e "Hello\nWorld" | figlet -f "Bloody" | terminal-widget --target widget1 --text - --font menlo --no-wrap --fit-text --bg-gradient-from ea39f3 --bg-gradient-to 9d3b7f --bg-gradient-start nw --text-color d9e3e6
pmset -g batt | head -1 | terminal-widget --target widget2 --text -
terminal-widget --target widget3 --image "https://picsum.photos/800/400" --fullsize
terminal-widget --target widget3 --image "https://picsum.photos/800/400" --filter sepia:35
terminal-widget --target widget3 --image "https://picsum.photos/800/400" --filter grayscale --filter blur:8
terminal-widget --target widget3 --image "https://picsum.photos/800/400" --filter "sepia:20,blur:10"
terminal-widget --target widget1 --progress 67 --text "Rendering"
terminal-widget --target widget1 --progress 67 --progress-format gradient-horizontal --gradient-from "#22d3ee" --gradient-to "#9333ea" --gradient-width 18 --text "Deploying"
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 sparkline --chart-height 55%
terminal-widget --target widget1 --chart "5 12 8 21 34 55 89" --chart-format sparkline --bar-radius 45
terminal-widget --target widget1 --chart "5 12 8 21 34 55 89" --chart-format sparkline --base-zero
terminal-widget --target widget1 --chart "0 1 5 2/1 2 5 3" --chart-format bar --fg "#cc0000,#00cc00,#0000cc" --annotate
terminal-widget --target widget1 --chart "5 12 8 21 34 55 89" --chart-format sparkline --chart-bar-style glass --bar-radius 35
terminal-widget --target widget1 --progress 72 --progress-format circle --chart-bar-style glass --fg "#4a9eff" --caption
terminal-widget --chart "6-8,1-8,1-6,2-4,1-6" --chart-format rangebar --chart-bar-style glass --bar-radius 40 --target widget1 --bg "ffffff" --fg "ca4fae" --text "TerminalWidget" --text-color "#5ac5fa"
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
terminal-widget --target widget1 --chart "3 6 2 8 5 9 4" --chart-format neo --neo-characters ascii --annotate
terminal-widget --chart "5-6,1-6,1-5,1.5-4,1-5" --chart-format rangebar --target widget1 --bg "ffffff" --fg "ca4fae"
terminal-widget --target widget1 --icon :x: --bg "#ff5f5f"
terminal-widget --target widget1 --text "Deploy :rocket: :+1:" --icon :smiley:
terminal-widget --target widget1 --text "Build queue" --title ":chart_with_upwards_trend: Throughput" --title-alignment center --title-color "#a78bfa" --caption-text "Updated :clock3:" --timestamp --bg "#0f172a" --fg "#94a3b8"
terminal-widget --target widget1 --chart "5 12 8 21 13 34" --chart-format graph --title "Weekly trend" --caption-text ":white_check_mark: On track" --caption-color "#94a3b8" --fg "#e2e8f0" --bg "#0f172a"
terminal-widget --target widget1 --table /Users/ttscoff/Desktop/Code/terminal-widget/status.csv
terminal-widget --target widget1 --table ~/status/status.csv --grid zebra --table-layout auto --mode dark
terminal-widget --target widget1 --table ~/status/status.csv --grid zebra --zebra-opacity 0.4 --table-layout auto --mode dark
terminal-widget --target widget1 --table ~/status/status.csv --grid zebra --zebra-opacity 60 --table-layout auto --mode dark
terminal-widget --target widget1 --table ~/status/status.csv --grid both --table-layout equal --mode dark
terminal-widget --target widget1 --table ~/status/status.csv --grid none --mode dark
echo "Build complete" | terminal-widget --target widget1
cal | terminal-widget --target cal --text -
figlet -f doom "$(users | head -n 1)" | terminal-widget --target username --text -
ls -G /Applications | head -n 12 | terminal-widget --target ansi --text - --ansi-mode auto
printf '\033[30;47m black/white \033[0m \033[97;44m white/blue \033[0m\n' | terminal-widget --target ansi-bg --text - --ansi-mode on
git status --short | terminal-widget --target plain --text - --strip-colors
terminal-widget --target widget1 --chart - --chart-format radial < values.txt
cat /Users/ttscoff/Desktop/Code/terminal-widget/status.csv | terminal-widget --target widget1 --table -

Chart Gallery

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 sparkline --chart-height 55%
terminal-widget --target widget1 --chart "$DATA" --chart-format sparkline --bar-radius 45
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
terminal-widget --chart "5-6,1-6,1-5,1.5-4,1-5" --chart-format rangebar --target widget1 --bg "ffffff" --fg "ca4fae"
terminal-widget --chart "6-8,1-8,1-6,2-4,1-6" --chart-format rangebar --chart-bar-style glass --bar-radius 40 --target widget1 --bg "ffffff" --fg "ca4fae" --text "TerminalWidget" --text-color "#5ac5fa"

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

History-style range labels on a chart footer (with centered [min/max]):

terminal-widget --target widget1 --chart "5 8 6 12 9 15 11" --chart-format graph --caption \
  --caption-left "5/4/26 08:00" --caption-right "5/5/26 15:00" --caption-color "#94a3b8"

.fish`>URL Scheme Examples

For complete URL parameter documentation, behavior notes, and more ready-to-paste examples, see URL Scheme Documentation.

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=widget1&chart=5,8,6,12&chartFormat=graph&caption=1&captionLeft=Start&captionRight=Now
terminalwidget://update?target=widget2&theme=dark&fg=%23ffffff&bg=%23111417