TerminalWidget

TerminalWidget CLI

Download on the Mac App Store Download on the App Store

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

Add a widget first. Updates only appear on widgets you place yourself (Desktop or Home Screen) after you set Edit Widget → Target name to match --target. See Integrations → Getting Started.

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

Looking for ready-made CLI recipes? The Widgets page has screenshot-matched examples for every mode — text, progress, charts, tables, and especially launcher button JSON. Scroll past the image gallery to the command sections below.

Usage

terminal-widget [--target NAME] [--clear|--clear-buttons] [--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[,N...] --progress-format MODE --progress-layout LAYOUT --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] [--table PATH|-] [--no-header] [--grid MODE] [--table-layout auto|equal|fill] [--table-align left,center,right] [--center-table] [--caption] [--caption-text TEXT] [--caption-left TEXT] [--caption-right TEXT] [--annotate] [--label-y] [--timestamp] [--image PATH_OR_URL|--background-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)

Install paths by shell:

  • Fish: ~/.config/fish/completions/NAME.fish
  • Zsh: ~/.zsh/completions/_NAME
  • Bash: ~/.local/share/bash-completion/completions/NAME (extensionless)

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.
  • --clear Delete this target’s payload file, per-target images, and App Group mirror entry; when iCloud sync is enabled, also deletes that target’s cloud record. Other targets and the instance registry are untouched. Does not seed a demo payload. Incompatible with content/update flags (including --clear-buttons).
  • --clear-buttons Remove launcher buttons from this target; keep all other content. Requires an existing payload. Incompatible with --clear and with content flags that set buttons in the same invocation.
  • --text STRING Text line (shown above the progress bar when both are set). Supports CommonMark-style markdown links [label](url) on macOS and iOS widgets (tappable; see Notes).
  • --command COMMAND Run a shell command and use its stdout as the widget text. If both --text and --command are set, --command wins. Prefer piping from your own shell (… \| terminal-widget --text -) when you need your full PATH, aliases, and functions.
  • --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. Uses the same 10pt inset as --padding fill and vertically centers the scaled block, 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[,N...] One 0-100 percentage, or comma-separated percentages for quad4; omit to hide progress on this update.
  • --progress-format bar|matrix|dots|stack|circle|watch|quadrant|quad4|gradient|gradient-horizontal|gradient-vertical Progress style (default bar; quad-4 aliases to quad4; gradient aliases to gradient-horizontal).
  • --progress-layout LAYOUT Quadrant groups for quad4. Use comma-separated quadrants or clockwise ranges such as 1,2,3,4, 1-2,3-4, or 1-4. Defaults to 1,2,3,4 and is rejected for other progress formats.
  • --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. For pie, use label:value[:color] tokens (for example CPU:45 Memory:30 Disk:25). JSON input (via --json or structured refresh) may use a nested numeric array (for example [[0,1,5],[1,2,5]]), named series objects (for example [{"name":"CPU","values":[1,2,3]}]), or a slices array for pie. Omit to clear. Max 128 points per series (keeps the newest when over the cap).
  • --append VALUES Append chart columns or text lines to the existing target. Chart append uses the same syntax as --chart (including slash-grouped columns and rangebar low-high pairs) and must match the existing chart shape. Text append joins with a newline. Preserves settings not overridden by this update. Incompatible with --chart, --text/--command, --table, and --image.
  • --limit N Keep the last N chart columns or text lines in storage. Persists on the target until changed. 0 clears the soft limit (charts still hard-capped at 128 newest points). Works with --chart, --text, and --append, or alone to re-truncate existing data.
  • --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
    • series (aliases: lines, multiline): overlapping line charts with shared Y scaling; use slash-separated groups like grouped sparklines (1 2 3/4 5 6). Legend labels default to Series 1, Series 2, … unless you pass --chart-series-labels or JSON series: [{name, values}, …].
    • pie: pie chart from label:value[:color] tokens (for example CPU:45 Memory:30 Disk:25) or JSON slices array
  • --chart-key auto|inline|left|bottom|external|none Legend placement for series and pie charts (default auto). For pie on medium and extra large widgets, auto/inline/left show a side legend to the left of the pie (scaled to fill that column). For series, auto/bottom show the legend under the chart. external hides the legend on the main widget (pair with --key-target). A prior --chart-key external is not preserved when you update chart data without --chart-key — omit the flag (or use auto/inline) to show the legend again.
  • --chart-series-labels LIST Comma-separated legend labels for series charts. Order matches slash-separated groups in --chart (for example CPU,Memory,Disk for three series). Also accepted in JSON as chartSeriesLabels (string or array) or per-series name/label on objects in a series array.
  • --key-target NAME Write legend rows to a second widget target (for example cpu-key). Use auto to expand to {current-target}-key. Requires chart data that produces a legend (series or pie). Often used with --chart-key external. The key widget’s Edit Widget → Target name must match exactly. External key widgets inherit --fg, --bg, gradient, and padding from the main chart update; legend text scales to fill the key widget like --fit-text.
  • --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/slice appearance. glass adds a gradient “liquid glass” look to vertical bars, matrix cells, pie slices, and circle progress rings. Valid with --chart and formats sparkline (or bar), waveform, rangebar, matrix, pie, 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). Extra space stays after the last column instead of stretching every cell. Use --center-table to split that leftover space on both sides.
    • fill content-measured widths stretched proportionally to fill the widget (the previous auto behavior).
    • equal uniform column widths based on available table width
  • --table-align LIST Per-column table text alignment: comma-separated left, center, or right (aliases l/c/r, leading/trailing, centre). Too few values repeat the last for remaining columns; extra values are ignored. Default is all left. A fresh --table without --table-align writes that default (it does not keep a previous alignment).
  • --center-table With --table-layout auto, center the content-sized table horizontally in the widget instead of leaving leftover space after the last column. Horizontal rules span the table, not the full widget. Ignored for equal and fill. A fresh --table without --center-table writes the default (left-aligned table block).
  • --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.
    • On Mac, local paths outside the app sandbox need an Image folder grant in Terminal Widget (Info/Debug → Add image folder…), or a one-time file chooser when the app can prompt. Full Disk Access does not grant arbitrary paths to the sandboxed app. If neither applies, copy the image into ~/Library/Group Containers/group.brettterpstra.TerminalWidget/ and pass an absolute path.
    • SVG tip: WidgetKit’s SVG parser is not full WebKit. Convert <text> / <tspan> to outlined paths before display, or labels that look fine in Safari may be missing in the widget. Inkscape CLI: inkscape in.svg --export-text-to-path --export-plain-svg --export-filename=out.svg (see SVG diagrams).
  • --background-image IMAGE_PATH Use an absolute/relative image path or http(s) URL as a full-bleed background behind text, icons, progress, charts, or tables. It cannot be combined with --image. Padding insets the foreground only; the photo always fills the widget. Use --filter alpha:0-100 to fade the backdrop so --bg shows through.
  • --filter FILTER[:VALUE][,FILTER[:VALUE]...] Apply one or more filters to --image or --background-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); --background-image can (including with --table).
  • --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. Image keys are image or backgroundImage (background-image); they are mutually exclusive. Table keys include tableAlign (string or array) and tableCenter / center-table (boolean; auto layout only).
  • --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.
  • --auto-update KIND Enable Mac host auto-update for this target: shortcut or image-url (off / false clears). Pair with --auto-update-value and optionally --auto-update-interval.
  • --auto-update-value VALUE Shortcut name or http(s) image URL for --auto-update.
  • --auto-update-interval SECS Seconds between auto-updates (minimum 60).
  • --clear-auto-update Remove the persisted auto-update recipe for this target.
  • --background When used without a color value, do not launch TerminalWidget or open its refresh URL (quiet update). Prefer --background-mode when you also pass --bg / --background COLOR in the same command.
  • --background-mode Unambiguous alias for bare --background (skip LaunchServices handoff).
  • --strict-local-open Fail if local open handoff fails (URL scheme / app launch diagnostics). Useful when debugging tap actions and Continuity handoff.
  • --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.
  • --append - reads append 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. A --background-image may still be present.
  • 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. Scaling uses a 10pt inset (same as --padding fill) and centers the fitted block. Fit-text scaling is skipped when --text contains any markdown links so link hit targets stay correct.
  • Markdown links in --text (and append/JSON text) and in --table cell strings (CSV/TSV/JSON, including headers) use [label](url). Labels may include spaces; URLs need a scheme (https://…, mailto:…, etc.). Relative/schemeless URLs and unbalanced markup stay literal. Tapping a link opens that URL; taps on non-link areas still use --action-kind / the whole-widget action. Links are not parsed in --title or --caption-text. Quote CSV cells when the URL contains commas.
  • JSON may include a buttons array (max 12) of launcher buttons. Each button uses { "label", "color", "action-type", "action-value" } and may include an optional icon (an SF Symbol name or :emoji: shortcode), plus optional border fields (border, border-color, border-width 0-12, border-radius 0-48). Buttons render in a footer grid under any content (or alone). When any button has an icon, every button reserves a left gutter so icons and labels line up. action-type matches --action-kind values. Layout: optional root button-columns / buttonColumns is "smart"|"auto"|1|2|3 (small widgets stay 1 column; omit to leave previous mode). Root border defaults: button-border (e.g. "2px #0f0aff"), button-border-color, button-border-width, button-border-radius; per-button border fields override. Borderless when no border color/width is set; color alone implies width 1; omitted radius defaults to 8. On iOS, open-app and run-command are shown muted and do not run. Clear the footer with "buttons": [] (merges onto the previous payload and keeps text, charts, images, and other fields), --clear-buttons, or --json '{"buttons":[]}'; omit buttons to leave previous buttons. See Widgets for the full field reference.
  • --filter requires --image or --background-image. Use --filter alpha:40 to fade a background image behind foreground content.
  • --progress-format requires at least one --progress value. --progress-layout additionally requires --progress-format quad4.
  • Grouped slash chart literals (0 1 2/3 4 5) require --chart-format sparkline, spark, bar, or series/lines/multiline.
  • --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.
  • Widget taps with no configured --action-kind / action do nothing (Terminal Widget does not open).
  • Local image paths for --image follow the same Mac Image folder grants and file-chooser fallback described above. AppleScript and Shortcuts image updates use the same rules.
  • 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.

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.

Full list of GitHub-style shortcodes: Emoji cheat sheet (same aliases GitHub documents for Markdown).

Command Examples

For screenshot-ready CLI examples (text, progress, charts, tables, button JSON), see Widgets Gallery and Modes — especially launcher buttons and emoji + tables.

terminal-widget --target widget1 --text "Deploy complete" --icon "checkmark.circle.fill" --fg "#22c55e"
terminal-widget --target widget1 --text "Status: [Docs](https://terminalwidget.app) · [Support](https://terminalwidget.app/support)"
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 --background-image "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?auto=format&fit=crop&w=1600&q=80" --filter alpha:40 --bg 0f172a --fg "#f8fafc" --title "Today" --text "Austin 84" --caption-text "Clear" --icon sun.max.fill
terminal-widget --target widget1 --background-image "https://images.unsplash.com/photo-1506905925346-21bda4d32df4?auto=format&fit=crop&w=1600&q=80" --filter alpha:35 --bg 0f172a --fg "#7dd3fc" --chart "4 8 15 16 23 42" --text "Throughput"
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 --text "Sleep score" --progress 85 --progress-format quadrant --fg "#7dd3fc" --caption --bg "#0f172a"
terminal-widget --target widget1 --progress 92,74,55,38 --progress-format quad4 --progress-layout 1,2,3,4 --chart-series-labels "Build,Test,Ship,Docs" --chart-key inline --caption --caption-text "Sprint goals" --fg "#38bdf8,#4ade80,#fbbf24,#f87171" --bg "#0f172a" --caption-color "#94a3b8"
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 --limit 20
terminal-widget --target widget1 --append "90 91" --limit 20
terminal-widget --target widget1 --append "3/4"
terminal-widget --target widget1 --append "2-5 3-6"
terminal-widget --target widget1 --text "line 1" --limit 50
terminal-widget --target widget1 --append "line 2"
terminal-widget --target widget1 --limit 10
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 "1 2 3 4/5 6 7 8/9 10 11 12" --chart-format series --chart-series-labels "CPU,Memory,Disk" --fg "#f87171,#4ade80,#60a5fa" --bg "#0f172a"
terminal-widget --target widget1 --chart-format series --chart '{"series":[{"name":"CPU","values":[1,4,9,3]},{"name":"Memory","values":[2,5,8,4]},{"name":"Disk","values":[6,7,5,2]}]}' --fg "#f87171,#4ade80,#60a5fa" --bg "#0f172a"
terminal-widget --target widget1 --chart "CPU:45:#f87171 Memory:30:#4ade80 Disk:25:#60a5fa" --chart-format pie --chart-key inline --bg "#0f172a" --fg "#e2e8f0"
terminal-widget --target cpu --chart "CPU:45 Memory:30 Disk:25" --chart-format pie --chart-key external --key-target cpu-key --bg "#0f172a" --fg "#e2e8f0"
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 --clear
terminal-widget --target widget1 --clear-buttons
terminal-widget --target widget1 --json '{"buttons":[]}'
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 zebra --table-layout fill --mode dark
terminal-widget --target widget1 --table ~/status/status.csv --grid zebra --table-align left,right,center --mode dark
terminal-widget --target widget1 --table ~/status/status.csv --grid zebra --table-layout auto --center-table --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