# TerminalWidget CLI

> Command-line and URL scheme documentation for TerminalWidget.

Source: https://terminalwidget.app/cli

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

<div class="doc-callout" role="note">

**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](https://terminalwidget.app/integrations.md#getting-started).

</div>

If you prefer Script Editor or AppleScript-based automation, see [AppleScript Documentation](https://terminalwidget.app/applescript.md).

## Usage

```text
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 --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]
```

```text
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):

```bash
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
# Bash (~/.bashrc or ~/.bash_profile)/Zsh (~/.zshrc)
terminal-widget() {
  /Applications/TerminalWidget.app/Contents/MacOS/TerminalWidget "$@"
}
```

```fish
# 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:

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

```bash
# 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
```

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

| Shell | Install path |
| --- | --- |
| 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).
- `--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 (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`
- `--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.
  - 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](https://terminalwidget.app/widgets.md#svg-diagrams)).
- `--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.
- `--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.
- 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. 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](https://terminalwidget.app/widgets.md#launcher-buttons-buttons-in-json) for the full field reference.
- `--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.
- 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](https://terminalwidget.app/recipes) index, including launchd scheduling notes and copy-paste scripts.

- [Browse recipes](https://terminalwidget.app/recipes)
- [Submit your own recipe](https://terminalwidget.app/recipes/submit)

## 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](https://terminalwidget.app/widgets.md#emoji--tables).

```bash
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 --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 --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 "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 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:

```bash
# 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]`):

```bash
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](https://terminalwidget.app/url-scheme.md).

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