# 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).

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

**Looking for ready-made CLI recipes?** The [Widgets](https://terminalwidget.app/widgets.md#text-widgets) page has screenshot-matched examples for every mode — text, progress, charts, tables, and especially [launcher button JSON](https://terminalwidget.app/widgets.md#launcher-buttons-buttons-in-json). Scroll past the image gallery to the command sections below.

</div>

## 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[,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]
```

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

- Generated scripts register the basename of the invoked binary (`$0`) plus its casing counterpart, so `TerminalWidget` and `terminal-widget` both tab-complete. That covers shell functions and aliases, which keep the real binary name in `argv[0]`.
- `--name CMD` adds another token to register and is repeatable. The first `--name` value also names the generated files.
- 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 + register an extra command name (repeatable)
terminal-widget completions --shell fish --name tw --install
```

```fish
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.

## Diagnostics

Inspect recent failures and warnings without digging through Console.app. On each device, the host app and widget extension append to one bounded event log in that device’s App Group container. The log is **device-local**: your Mac does not show iPhone events, and your phone does not show Mac CLI or menu-bar app events.

**Mac:** read the log with the `log` subcommand, **Info/Debug → Recent events** in the menu bar app, or a **`twdiags`** widget.

**iPhone and iPad:** add a widget whose **Target name** is `twdiags`. There is no Info/Debug panel and no `terminal-widget log` on device — the widget is the viewer.

### Diagnostics widget (`twdiags`)

Name any widget’s **Target name** `twdiags` (case-insensitive) and it shows recent diagnostic events from **that device** as its text. No special payload is written for that target: the timeline provider substitutes the log into the target’s existing styling, so normal flags still apply for colors, fonts, and background.

**Setup**

1. Add a Terminal Widget on the Desktop or Home Screen.
2. Open **Edit Widget** and set **Target name** to `twdiags`.
3. On Mac, optionally style it from the CLI:

```bash
terminal-widget --target twdiags --bg 111111 --fg 00ff88 --font Menlo --font-size 9
```

On iPhone and iPad, style the widget with Shortcuts, the URL scheme, or a Mac update that syncs styling via iCloud — the log text always comes from the local device.

The widget shows the newest matching events (default: warn and error, up to 12 lines). On iOS, appending an event does not itself refresh the widget; the display updates when WidgetKit rebuilds the timeline, including after updates that request a widget reload.

**What you will see**

Each line is one event: timestamp, level, optional target, and message.

On **Mac**, typical codes include failed launcher commands (`action.command_exit`), missing apps (`action.app_not_found`), image failures (`image.*`), save/sync problems (`save.failed`, `cloud.*`), and reload/timeline pairing (`reload.requested`, `timeline.built`).

On **iOS**, events come from Shortcuts and URL-scheme updates, CloudKit pull/push/subscribe failures, button/tap action failures, image fetch/copy/render misses, save failures, and the same reload/timeline pairing (`reload.requested`, `timeline.built`). The pairing events are `info` level, so the default `warn` threshold hides them until `TerminalWidgetDiagnosticsLevel` is set to `info`.

**Notes**

- A widget that already used the target name `twdiags` for something else will be taken over by the diagnostics view.
- The diagnostics widget does not log its own timeline builds, so it will not flood itself with `timeline.built` noise.
- Content such as charts, progress, and images on a `twdiags` target is cleared when the log is rendered; only text styling fields are kept.
- Each device keeps its own log file; iCloud widget sync does not mirror diagnostics history across Mac and iPhone.

### `terminal-widget log` (Mac only)

```bash
terminal-widget log [--level error|warn|info] [--target NAME] [--limit N] [--follow] [--json] [--clear]
```

- `--level LEVEL` Minimum severity to show: `error`, `warn`, or `info` (default `info`).
- `--target NAME` Only events for this widget target.
- `--limit N` Newest N matching events.
- `--follow` Stream new matching events until interrupted.
- `--json` Emit one JSON object per line instead of the human-readable one-line format.
- `--clear` Wipe the entire log. Cannot be combined with `--target`, `--level`, `--limit`, or `--follow`.

Examples:

```bash
# Recent events (info and above)
terminal-widget log

# Warnings and errors for one target
terminal-widget log --level warn --target cpu --limit 20

# Watch live while tapping a broken launcher button
terminal-widget log --follow --level warn
```

### Preferences

Two App Group preferences control what the `twdiags` widget shows (the `log` command has its own `--level` / `--limit` flags):

- `TerminalWidgetDiagnosticsLevel` — minimum level for `twdiags` (`error`, `warn`, or `info`; default `warn`)
- `TerminalWidgetDiagnosticsLineCount` — how many lines `twdiags` renders (clamped to 1…100; default 12)

On Mac, you can set them from a shell:

```bash
defaults write group.brettterpstra.TerminalWidget TerminalWidgetDiagnosticsLevel -string info
defaults write group.brettterpstra.TerminalWidget TerminalWidgetDiagnosticsLineCount -int 20
```

The `defaults write` example is Mac-only. iPhone and iPad have no diagnostics settings UI; the same App Group keys are honored if set, and otherwise use `warn` and 12 lines. At the default `warn` level, `reload.requested` and `timeline.built` are recorded but hidden from `twdiags`; set the level to `info` to display them.

### Info/Debug (Mac only)

Open the menu bar app → **Info/Debug**. The panel lists **Recent events** with severity colors, and **Copy cloud diagnostics** includes that history on the clipboard. iPhone and iPad do not have this panel; use a `twdiags` widget on the Home Screen instead.

### Privacy

The log can include file paths, command text, and captured stderr. Those lines appear on the `twdiags` widget (Mac and iOS) and in Info/Debug on Mac. On Mac, clear the log with `terminal-widget log --clear` when you do not want that history kept.

## 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`. The reserved name `twdiags` (case-insensitive) turns the widget into a [diagnostics log view](#diagnostics-widget-twdiags) instead of normal content.
- `--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](https://terminalwidget.app/widgets.md#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. Deleting a Desktop/Home Screen widget does **not** clear auto-update; the Mac menu-bar app keeps firing while it is open (and iCloud can restore the recipe after reinstall). Use this flag, Shortcuts **Clear Auto-Update**, or Info/Debug → Auto-update.
- `--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](https://terminalwidget.app/widgets.md#launcher-buttons-buttons-in-json) 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](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.

Full list of GitHub-style shortcodes: [Emoji cheat sheet](https://github.com/ikatyang/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](https://terminalwidget.app/widgets.md#text-widgets) — especially [launcher buttons](https://terminalwidget.app/widgets.md#launcher-buttons-buttons-in-json) and [emoji + tables](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 --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 -
```

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