Terminal Widget

Widget Types, Modes, and Examples

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.

Tip: Use one dedicated screenshot target (for example widget1) and point all your test widgets at it.

Screenshot Slots

  • macOS screenshot slot: Desktop widgets (small + medium + large)
  • iOS / iPadOS screenshot slot: Home Screen or Lock Screen widgets
  • watchOS screenshot slot: watchOS complication/widget view

Example output for each widget style:

  • text-basic widget screenshot
  • text-icon widget screenshot
  • icon-text-fill widget screenshot
  • icon-only widget screenshot
  • progress-bar widget screenshot
  • progress-matrix widget screenshot
  • progress-dots widget screenshot
  • chart-sparkline widget screenshot
  • chart-graph widget screenshot
  • chart-waveform widget screenshot
  • chart-area widget screenshot
  • chart-lollipop widget screenshot
  • chart-strip widget screenshot
  • chart-radial widget screenshot
  • chart-delta widget screenshot
  • chart-threshold widget screenshot
  • chart-smooth widget screenshot
  • chart-sine widget screenshot
  • chart-peak widget screenshot
  • chart-matrix widget screenshot
  • chart-annotate widget screenshot
  • foreground-background widget screenshot
  • light-mode widget screenshot
  • image-full-width widget screenshot
  • fullsize-area widget screenshot
  • icon-inline widget screenshot

iOS/iPadOS/watchOS

  • iPhone icon-only trio widget screenshot
  • iPhone foreground/background variants widget screenshot
  • iPhone fullsize contrast widget screenshot
  • iPhone icon inline mix widget screenshot
  • iPhone image showcase widget screenshot
  • iPhone mode showcase widget screenshot
  • iPhone chart matrix and annotate widget screenshot
  • iPhone chart styles C widget screenshot
  • iPhone chart styles B widget screenshot
  • iPhone chart styles A widget screenshot
  • iPhone chart core widget screenshot
  • iPhone progress trio widget screenshot
  • iPhone text trio widget screenshot

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"

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"

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

Chart Widgets

Chart mode uses --chart "N N ..." with --chart-format.

Starter Example

terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5 10 6" --chart-format sparkline

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

Chart Annotation (--annotate)

--annotate overlays point/bar labels for sparkline, graph, and waveform chart families.

terminal-widget --target widget1 --chart "5 12 8 21 13 34" --chart-format graph --annotate

Styling and Layout Flags

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

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