Terminal Widget

Terminal Widget CLI

Download on the Mac App Store Download on the App Store

Use the Terminal Widget 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] [--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-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]

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

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-left / --caption-right footer text, and the optional --timestamp line; 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 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
  • --caption Show centered [min/max] caption below the active chart (or [n%] for styled/matrix/dot/stack progress modes); pairs with chart or progress updates
  • --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), 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 in the caption area; can be used with charts or progress, with or without --caption (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, Terminal Widget 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.
  • --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 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.
  • 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 Terminal Widget.
  • Updates the App Group JSON + prefs, then posts widget refresh notifications from CLI mode (without launching a new app instance).

Examples

These examples show script patterns where terminal-widget is useful as a live status surface for automation.

Quick background-gradient example:

terminal-widget --target widget3 --text "Gradient backdrop" --fg "#f8fafc" --bg "#020617" --bg-gradient-from "#0ea5e9" --bg-gradient-to "#8b5cf6" --bg-gradient-start ne
Example Terminal Widget layouts

Hostname

Output your machine hostname using Figlet and display it in a nicely-formatted widget.

hostname | figlet -f "Glenyn" | terminal-widget --target username --no-wrap --font menlo --fit-text --bg-gradient-from ea39f3 --bg-gradient-to 9d3b7f --bg-gradient-start nw --text-color d9e3e6
Hostname piped through Figlet and shown in a Terminal Widget with purple gradient background

Here’s a Fish command that removes the .local:

string replace ".local" "" (hostname) | figlet -f "Bloody" | terminal-widget --target username --no-wrap --font menlo --fit-text --bg-gradient-from "#ff0054" --bg-gradient-to "#390099" --bg-gradient-start nw --text-color d9e3e6
Glitched pixel-art “DARKNESS” text on a pink-to-purple gradient in a Terminal Widget

GitHub contributions graph

The contrib service at https://brettterpstra.com/contrib renders a PNG of a GitHub user’s contribution activity. Point --image at the generate URL and tune query parameters (months, theme, width, captions) there; only the username belongs in shell configuration.

#!/usr/bin/env bash
# Updates a Terminal Widget (--target github) with a contrib graph PNG.
set -euo pipefail

# GitHub login shown in the graph (contrib API generates a static PNG for this user).
GITHUB_USERNAME="ttscoff"

widget-github() {
  local contrib_root="https://brettterpstra.com/contrib"
  local graph_url="${contrib_root}/generate?username=${GITHUB_USERNAME}&months=5&theme=sunset&width=600&caption_year=0&caption_month=0&caption_day=0&download=0"

  terminal-widget --target github --image "${graph_url}" --padding 0 --bg 1d1128 --full-width "$@"
}

widget-github

Use launchd to run this script at the beginning of each week to update the chart.

GitHub contributions graph in a Terminal Widget using sunset theme and target github

GitHub contributions chart (smooth + JSON)

The same contrib service can return JSON (chart-data=1, json=1) so you can drive a native --chart (here smooth with --annotate) and use --caption-left / --caption-right for the visible date range. The example uses three weeks of daily counts; adjust weeks or swap CHART_FORMAT as needed.

#!/usr/bin/env bash
USERNAME="ttscoff"
CHART_FORMAT="smooth"
json=$(curl -SsL "https://brettterpstra.com/contrib/generate?username=${USERNAME}&chart-data=1&json=1&weeks=3")
startDate=$(echo "$json" | jq -r '.startDate / 1000 | strftime("%-m/%-d")')
endDate=$(echo "$json" | jq -r '.endDate / 1000 | strftime("%-m/%-d")')
user=$(echo "$json" | jq -r '.github.userLogin')
values=$(echo "$json" | jq -r '.values | join(",")')

/opt/homebrew/bin/terminal-widget --target github2 --chart "$values" --chart-format ${CHART_FORMAT} --font Menlo --bg 333333 --fg e0ff4f --caption --caption-left "$startDate" --caption-right "$endDate" --text "GitHub Contributions from $user" --annotate
GitHub contribution activity as a smooth Terminal Widget chart with left and right date captions

API health check

#!/usr/bin/env bash
set -euo pipefail

HEALTH_URL="https://billing.markedapp.com/api/health"

status="$(
  curl -fsS "$HEALTH_URL" | jq -r '.status // empty'
)"

if [[ "$status" == "ok" ]]; then
  terminal-widget \
    --target billingstatus \
    --icon checkmark.seal.fill \
    --background "#639992" \
    --foreground "#ffffff" \
    --text "Billing Server Healthy"
else
  terminal-widget \
    --target billingstatus \
    --icon xmark.seal.fill \
    --background "#ad343e" \
    --foreground "#ffffff" \
    --text "Billing Server Error"
fi

Network speed history chart (waveform)

Run Ookla speedtest CLI and convert results to waveform widgets. Requires the Ookla version, not the Homebrew version.

Add medium widgets with ids “download” and “upload” to use this, and edit the bin variables at the top to match your setup. This script can be run in the background using launchd.

Append each speed test result to a history file, then render the latest 20 samples:

#!/usr/bin/env bash
# Uses networkQuality, update terminal-widgets, output up/down speeds
set -e

LOGDIR="$HOME/logs"
LOGFILE="$LOGDIR/speed.csv"
mkdir -p "$LOGDIR"

widget_id_upload="upload"
widget_id_download="download"
chart_format="waveform"

# Run networkQuality
NQ_OUT=$(networkQuality -s 2>&1)
STATUS=$?
if [[ $STATUS -ne 0 ]]; then
	echo "networkQuality failed: $NQ_OUT" >&2
	exit $STATUS
fi

DOWNLOAD=$(echo "$NQ_OUT" | awk -F: '/Downlink capacity/ {print int($2+0)}')
UPLOAD=$(echo "$NQ_OUT" | awk -F: '/Uplink capacity/ {print int($2+0)}')
TIMESTAMP=$(date -Iseconds)
echo "$TIMESTAMP,$DOWNLOAD,$UPLOAD" >>"$LOGFILE"
# Keep only last 100 entries
tmpfile=$(mktemp)
tail -n 100 "$LOGFILE" >"$tmpfile"
mv "$tmpfile" "$LOGFILE"

# Update terminal-widgets for both download and upload
DOWN_VALS=($(tail -n 96 "$LOGFILE" | awk -F, '{print $2}'))
UP_VALS=($(tail -n 96 "$LOGFILE" | awk -F, '{print $3}'))
/opt/homebrew/bin/terminal-widget --base-zero --target ${widget_id_download}$ --text 'Download Speeds' --chart - --chart-format ${chart_format} --bg ffffff --fg 'rgb(237, 78, 195)' --text-color 222222 --caption --caption-color 888888 <<<"${DOWN_VALS[*]}" || true
/opt/homebrew/bin/terminal-widget --base-zero --target ${widget_id_upload} --text 'Upload Speeds' --chart - --chart-format ${chart_format} --bg ffffff --fg 'rgb(78, 155, 237)' --text-color 222222 --caption --caption-color 888888 <<<"${UP_VALS[*]}" || true

# Output up/down speeds to STDOUT
echo "⬇️ $DOWNLOAD"
echo "⬆️ $UPLOAD"

exit 0

Here’s a launchd example for the speedtest script. This assumes you’ve saved the script as speed-widget.sh, and you’ll need to update your path in the ProgramArguments. This job will run every 60 minutes, which can be adjusted in the StartInterval key.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>com.brettterpstra.speed</string>
	<key>ProgramArguments</key>
	<array>
		<string>/Users/ttscoff/scripts/speed-widget.sh</string>
	</array>
	<key>RunAtLoad</key>
	<true/>
	<key>StandardErrorPath</key>
	<string>/Users/ttscoff/logs/com.brettterpstra.speedtest.err</string>
	<key>StandardOutPath</key>
	<string>/Users/ttscoff/logs/com.brettterpstra.speedtest.out</string>
	<key>StartInterval</key>
	<integer>3600</integer>
</dict>
</plist>

Time Machine status and backup progress

Show current Time Machine state, including percent complete while a backup is running:

#!/usr/bin/env bash
set -euo pipefail

status_raw="$(tmutil status 2>/dev/null || true)"

if grep -q "Running = 1;" <<<"$status_raw"; then
  # tmutil reports Percent as a fraction (0.0..1.0), not 0..100.
  # Parse robustly, round to nearest integer, and clamp for widget progress.
  percent="$(
    awk '
      /Percent =/ {
        gsub(/;/, "", $3)
        p = $3 + 0
        v = int((p * 100) + 0.5)
        if (v < 0) v = 0
        if (v > 100) v = 100
        print v
        found = 1
      }
      END {
        if (!found) print 0
      }
    ' <<<"$status_raw"
  )"
  percent="${percent:-0}"

  terminal-widget \
    --target timemachine \
    --icon arrow.trianglehead.counterclockwise \
    --text "Time Machine Backing Up (${percent}%)" \
    --progress "$percent" \
    --foreground "#d9f2ff" \
    --background "#1f3b56"
else
  terminal-widget \
    --target timemachine \
    --icon checkmark.arrow.trianglehead.clockwise \
    --text "Time Machine Idle" \
    --foreground "#d7ffe3" \
    --background "#244730"
fi

Run this script on an interval with a launchd user agent so the widget stays current. Save your script somewhere stable (for example ~/bin/timemachine-widget.sh), then create:

~/Library/LaunchAgents/com.terminalwidget.timemachine.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.terminalwidget.timemachine</string>

  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>/Users/YOUR_USER/bin/timemachine-widget.sh</string>
  </array>

  <key>StartCalendarInterval</key>
  <dict>
    <key>Minute</key>
    <integer>10</integer>
  </dict>

  <key>RunAtLoad</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/com.terminalwidget.timemachine.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/com.terminalwidget.timemachine.err</string>
</dict>
</plist>

Load it with:

launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.terminalwidget.timemachine.plist

For editing and troubleshooting launch agents/daemons, LaunchControl from soma-zone is usually the easiest way to manage launchd jobs.

Capture real command progress (rsync -> --progress)

Some commands emit percent progress to stderr/stdout. You can parse that and continuously update a widget:

#!/usr/bin/env bash
set -euo pipefail

SRC="${1:-$HOME/Downloads/}"
DST="${2:-$HOME/Backup/Downloads/}"

terminal-widget --target syncjob --icon arrow.triangle.2.circlepath --text "Sync starting" --progress 0

rsync -ah --info=progress2 "$SRC" "$DST" 2>&1 | while IFS= read -r line; do
  if [[ "$line" =~ ([0-9]{1,3})% ]]; then
    pct="${BASH_REMATCH[1]}"
    terminal-widget \
      --target syncjob \
      --icon arrow.triangle.2.circlepath \
      --text "Syncing ${pct}%" \
      --progress "$pct" \
      --foreground "#eaf6ff" \
      --background "#1f2a44"
  fi
done

terminal-widget \
  --target syncjob \
  --icon checkmark.circle.fill \
  --text "Sync complete" \
  --progress 100 \
  --foreground "#d9ffe7" \
  --background "#1b3a2f"

Configure a widget tap action

Actions are stored with the target, so later display updates keep the same tap/click behavior until you change or clear it:

terminal-widget \
  --target deploy \
  --text "Open deploy dashboard" \
  --icon arrow.up.right.square \
  --action-kind open-url \
  --action-value "https://example.com/deploys"

terminal-widget \
  --target backup \
  --text "Run backup shortcut" \
  --icon externaldrive.fill \
  --action-kind run-shortcut \
  --action-value "Start Backup"

terminal-widget --target deploy --clear-action

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

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"

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