Use this page as a visual checklist for every widget style. Each section includes sample commands you can run as-is, plus screenshot slots for macOS, iOS/iPadOS, and watchOS.
Click a screenshot to zoom and you’ll see the command that generated it (with TARGET where the widget ID should go) beneath it.
macOS Widget Gallery
Example output for each widget style:
iOS/iPadOS/watchOS
watchOS
Screenshots coming soon.
Text Widgets
Text mode is active when you provide --text or --command without chart/progress-only output.
Basic Text
terminal-widget --target widget1 --text "Build complete"
Text + Icon
terminal-widget --target widget1 --text "API healthy" --icon "checkmark.seal.fill"
Text vs caption colors (--text-color, --caption-color)
Use --foreground for icons, charts, and progress visuals. Optionally set --text-color so the main --text line (and table defaults) differ from --foreground, and --caption-color for [min/max], [n%], and --timestamp lines.
terminal-widget --target widget1 --text "Queues" --foreground "#64748b" --text-color "#2dd4bf" --progress 55 --caption --timestamp --caption-color "#fbbf24" --bg "#0f172a"
Single-Line Truncation (--no-wrap)
terminal-widget --target widget1 --text "This is a very long line that truncates instead of wrapping in the widget" --no-wrap
Terminal Output (terminal-output)
cal -A 1 | terminal-widget --target widget1 --text - --font menlo --bg "333333" --fg "#e1c245" --no-wrap
Icon-Only Widget
When no --text, --progress, --chart, --image, or --command is present, the icon is centered and scaled.
terminal-widget --target widget1 --icon "terminal.fill"
ANSI Text (--ansi-mode, --strip-colors)
Use ANSI escape sequences for foreground/background color blocks in text mode, or strip them when you want plain text.
printf '\033[30;47m black on white \033[0m \033[97;44m white on blue \033[0m' | terminal-widget --target widget1 --text - --ansi-mode on
printf '\033[31mred text\033[0m' | terminal-widget --target widget1 --text - --strip-colors
Progress Widgets
Progress mode uses --progress 0..100. Add --progress-format to choose a visual style.
bar (default)
terminal-widget --target widget1 --text "Syncing assets" --progress 42 --progress-format bar
matrix
terminal-widget --target widget1 --text "Compile queue" --progress 74 --progress-format matrix --caption
dots
terminal-widget --target widget1 --text "Packaging release" --progress 92 --progress-format dots --caption
stack
terminal-widget --target widget1 --text "Layer sync" --progress 68 --progress-format stack --caption
gradient / gradient-horizontal
gradient is an alias for gradient-horizontal.
terminal-widget --target widget1 --text "Transfer queue" --progress 52 --progress-format gradient --gradient-from "#4fd1ff" --caption
gradient-vertical
Use --gradient-width to render a narrower vertical progress bar.
terminal-widget --target widget1 --text "Build queue" --progress 63 --progress-format gradient-vertical --gradient-from "rgba(126,240,168,0.95)" --gradient-width 32 --caption
circle
terminal-widget --target widget1 --text "Build Progress" --progress 72 --progress-format circle --fg "#7ee081" --caption --bg "#2a1f44"
macOS gallery slot progress-circle matches the command above (capture-macos-widgets.sh --only progress-circle).
watch (clock-style arc)
terminal-widget --target widget1 --text "Build time" --progress 58 --progress-format watch --fg "#a78bfa" --caption --bg "#1e293b"
macOS gallery slot progress-watch matches the command above (capture-macos-widgets.sh --only progress-watch).
Chart Widgets
Chart mode uses --chart "N N ..." with --chart-format. rangebar uses low-high pairs instead of single numeric values.
Grouped sparkline/bar (/ series)
Use slash-separated segments for side-by-side sub-bars per column (up to four series). Pair with comma-separated --foreground for per-series colors.
terminal-widget --target widget1 --chart "0 1 5 2/1 2 5 3/2 3 4 1" --chart-format bar --bar-radius 20 --fg "#ee9b00,#e9d8a6,#94d2bd" --annotate --bg "#001219"
macOS gallery slot chart-grouped matches the command above (capture-macos-widgets.sh --only chart-grouped). iOS interactive scene chart-grouped uses the same slash syntax on all three widget targets.
Starter Example
terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5 10 6" --chart-format sparkline
Bar radius (--bar-radius)
Use --bar-radius 0..100 to round sparkline bar corners, or range bar column corners in rangebar mode.
terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5 10 6" --chart-format sparkline --bar-radius 45
terminal-widget --target widget1 --chart "1-3,2-4,1-5" --chart-format rangebar --bar-radius 40
Chart bar style (--chart-bar-style)
Use --chart-bar-style glass with bar-like formats (sparkline, waveform, rangebar, matrix, delta) for a gradient “liquid glass” bar/cell treatment (default is solid). The same flag applies to circle progress rings (--progress-format circle) without chart data.
terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5 10 6" --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"
macOS gallery slot chart-rangebar-glass matches the range bar example above (run capture-macos-widgets.sh --only chart-rangebar-glass after placing widgets).
All Chart Modes
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
terminal-widget --chart "5-6,1-6,1-5,1.5-4,1-5" --chart-format rangebar --target widget1 --bg "ffffff" --fg "ca4fae"
Range Bar
rangebar draws each bar as one contiguous inclusive range. The y axis starts at 0 and scales to the highest range endpoint plus one.
terminal-widget --chart "5-6,1-6,1-5,1.5-4,1-5" --chart-format rangebar --target widget1 --bg "ffffff" --fg "ca4fae"
Chart Annotation (--annotate)
--annotate overlays point/bar labels for sparkline, graph, waveform, and rangebar chart families.
terminal-widget --target widget1 --chart "5 12 8 21 13 34" --chart-format graph --annotate
terminal-widget --target widget1 --chart "5 12 8 21 13 34" --chart-format sparkline --annotate
Gallery captures for bar-style annotations use slug chart-annotate-bars (capture-macos-widgets.sh / capture-ios-widgets-interactive.sh --only chart-annotate-bars).
Y axis labels (--label-y) and update time (--timestamp)
--label-y adds a left axis with five labels spanning the chart’s value range (and 0…max+1 for rangebar). --timestamp shows a short local “last updated” line in the caption block; it can be combined with --caption or used alone. Both apply to the same chart/progress update that sets the payload (not the WidgetKit refresh schedule).
terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5 10 6" --chart-format sparkline --label-y --caption
terminal-widget --target widget1 --chart "5 12 8 21 13 34" --chart-format graph --caption --timestamp
terminal-widget --target widget1 --text "Syncing" --progress 42 --caption --timestamp
Styling and Layout Flags
Emoji + Tables
Use these exact commands when capturing the new screenshot slots:
Emoji Icon + Background (emoji-icon-bg)
terminal-widget --target widget1 --icon :x: --bg "#ff5f5f"
Table with Zebra Grid (table-grid-zebra)
terminal-widget --target widget1 --table ~/status/status.csv --grid zebra --zebra-opacity 60 --mode dark
Table with Row + Column Grid (table-grid-both)
terminal-widget --target widget1 --table ~/status/status.csv --grid both --mode dark
Table with Header Rule Only (table-grid-none)
terminal-widget --target widget1 --table ~/status/status.csv --grid none --mode dark
Optional STDIN Variant
cat ~/status/status.csv | terminal-widget --target widget1 --table -
Foreground / Background (--foreground, --background, aliases --fg, --bg)
These set text/icon/chart/progress foreground and widget background colors for this payload.
terminal-widget --target widget1 --text "Night mode test" --icon "moon.stars.fill" --fg "#dbeafe" --bg "#0b1220"
Full-size (--fullsize, alias for --padding 0)
Useful for edge-to-edge charts/images and dense visual widgets.
terminal-widget --target widget1 --chart "2 6 4 9 7 3 8 5" --chart-format area --fullsize
Image + Full Width (--image + --full-width)
Use a remote image source and fill mode for edge-to-edge image rendering.
terminal-widget --target widget1 --image "https://picsum.photos/400/400" --full-width
Image Filters (--filter)
Apply built-in filters to images. You can pass one filter, repeat --filter, or provide a comma-separated filter chain.
terminal-widget --target widget1 --image "https://picsum.photos/640/640" --filter sepia:35
terminal-widget --target widget1 --image "https://picsum.photos/640/640" --filter grayscale
terminal-widget --target widget1 --image "https://picsum.photos/640/640" --filter "sepia:25,blur:8"
Icon Behavior (--icon)
--icon is inline with text/progress/chart, or centered if icon-only mode is active.
terminal-widget --target widget1 --text "CPU 62%" --icon "cpu.fill" --chart "58 61 66 62 64 62" --chart-format strip