# Widget Types, Modes, and Examples
> A complete guide to TerminalWidget text, progress, and chart modes with sample commands and screenshot capture workflow.
Source: https://terminalwidget.app/widgets
**TerminalWidget is a Mac, iPhone, and iPad app that shows text, progress bars, charts, and images in widgets, used by developers and power users to monitor scripts and automations at a glance.**
Use this page as a visual checklist for every widget style. Each section includes sample commands you can run as-is, plus screenshot slots for macOS, iOS/iPadOS, and watchOS.
**Widgets are not automatic.** Place a TerminalWidget on the Desktop or Home Screen yourself, then set **Edit Widget → Target name** so sample commands (and any automation) can reach it. Setup steps: [Integrations → Getting Started](https://terminalwidget.app/integrations.md#getting-started).
> Click a screenshot to zoom and you'll see the command that generated it beneath it.
## macOS Widget Gallery
Example output for each widget style:
- [{:loading=eager fetchpriority=high width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/text-basic@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/text-nowrap@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/terminal-output@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/terminal-output-figlet@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/text-icon@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/text-markdown-links@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/text-markdown-include@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/buttons-launcher@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/buttons-border@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/text-caption-colors@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/bg-gradient@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/icon-text-fill@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/icon-only@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/progress-bar@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/progress-matrix@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/progress-dots@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/progress-stack@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/progress-gradient-horizontal@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/progress-gradient-vertical@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/progress-circle@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/progress-watch@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-grouped@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-sparkline@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-append-limit@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-height@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-base-zero@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/base-zero@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-sparkline-radius@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-sparkline-glass@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-graph@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-waveform@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-area@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-lollipop@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-strip@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-radial@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-delta@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-threshold@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-smooth@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-sine@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-peak@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-neo@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-matrix@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-rangebar@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-rangebar-glass@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-annotate@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-annotate-bars@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-label-y@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-timestamp@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/chart-caption-sides@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/text-title-caption@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/text-title-align-left@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/foreground-background@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/light-mode@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/image-full-width@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/image-filter-sepia@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/image-filter-grayscale@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/image-filter-chain@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/fullsize-area@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/icon-inline@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/emoji-icon-bg@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/table-grid-zebra@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/table-grid-both@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/table-grid-none@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/macos/table-cell-links@2x.jpg){.widget-shot.js-lightbox}
{.widget-shot-grid}
- [{:loading=lazy width=400 height=258}](https://terminalwidget.app/assets/video/widgets.mp4){.widget-shot.widget-shot-video.js-lightbox data-lightbox-type=video data-video-poster="/assets/images/home/widgets-700.jpg" data-video-webm="/assets/video/widgets.webm" data-lightbox-caption="macOS widgets demo"}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/video/progress-bars.mp4){.widget-shot.widget-shot-video.js-lightbox data-lightbox-type=video data-video-poster="/assets/images/progress-bars.jpg" data-lightbox-caption="Progress Bars Demo"}
{.widget-shot-grid}
## iOS/iPadOS/watchOS
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/text-trio@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/text-markdown-links@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/text-markdown-include@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/buttons-launcher@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/buttons-border@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/text-nowrap@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/terminal-output@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/progress-trio@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/text-caption-colors@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/bg-gradient@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/progress-stack@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/progress-gradient@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/progress-circle-watch@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-grouped@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-core@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-append-limit@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-height@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-base-zero@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-caption-sides@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/text-title-caption@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/text-title-align-left@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/base-zero@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-sparkline-radius@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-sparkline-glass@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-sparkline-glass-2@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-styles-a@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-styles-b@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-styles-c@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-neo@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-matrix-annotate@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-annotate-bars@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-rangebar@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/chart-rangebar-glass@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/ansi-text-trio@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/mode-showcase@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/image-showcase@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/icon-inline-mix@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/fullsize-contrast@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/fg-bg-variants@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/icon-only-trio@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/table-grid-modes@2x.jpg){.widget-shot.js-lightbox}
- [{:loading=lazy width=400 height=400}](https://terminalwidget.app/assets/images/shots/iphone/table-cell-links@2x.jpg){.widget-shot.js-lightbox}
{.widget-shot-grid}
## watchOS
Screenshots coming soon.
## Text Widgets
Text mode is active when you provide `--text` or `--command` without chart/progress-only output.
### Basic Text
```bash
terminal-widget --target widget1 --text "Build complete"
```
### Text + Icon
```bash
terminal-widget --target widget1 --text "API healthy" --icon "checkmark.seal.fill"
```
### Markdown links in text
`--text` accepts CommonMark-style `[label](url)` links. On macOS and iOS, link labels render as tappable buttons; taps outside links still use the widget's `--action-kind` action. URLs need a scheme (`https://…`, `mailto:…`, etc.). `--fit-text` scaling is skipped when any link is present.
```bash
terminal-widget --target widget1 --text "Status: [Docs](https://terminalwidget.app) · [Support](https://terminalwidget.app/support)" --fg "#EAF6FF" --bg "#1F2A44"
terminal-widget --target widget1 --text "[Open dashboard](https://example.com/status)"
terminal-widget --target widget1 --text "Include [Markdown links](https://brettterpstra.com) in widgets" --fg "#EAF6FF" --bg "#1F2A44"
```
### Launcher buttons (`buttons` in JSON)
JSON updates (`--json`) can include a `buttons` array that renders a tappable footer grid under any widget content (text, chart, progress, image, table), or alone as a buttons-only layout. Max **12** buttons. Set launcher buttons from CLI `--json` (file, `-` stdin, inline `{...}`, or URL); Shortcuts/AppleScript do not expose per-button fields in v1, but any update that sends structured JSON can include `buttons`.
### Button fields
Each entry needs a label and an action:
| Field | Required | Notes |
| --- | --- | --- |
| `label` | yes | Button title |
| `icon` | no | SF Symbol name or `:emoji:` shortcode; left of label. If any button has an icon, all buttons reserve a left gutter so icons/labels line up |
| `action-type` | yes | Same values as `--action-kind`: `open-url`, `open-app`, `run-shortcut`, `run-command`, `refresh` (aliases: `actionType`, `actionKind`) |
| `action-value` | yes | URL, macOS bundle ID, Shortcut name, shell command, or refresh endpoint (aliases: `actionValue`) |
| `color` | no | Fill / accent color for the button |
| `border` | no | Shorthand stroke, e.g. `"2px #0f0aff"` or `"#ffffff 1.5"` (see borders below) |
| `border-color` | no | Stroke color (aliases: `borderColor`) |
| `border-width` | no | Stroke width in points, `0`–`12` (aliases: `borderWidth`) |
| `border-radius` | no | Corner radius in points, `0`–`48` (aliases: `borderRadius`); omit for default **8** |
### Button layout (`button-columns`)
- **Small** widgets always use one column.
- **Medium / large** default to smart layout: **3** columns when the button count is divisible by 3, otherwise **2**. Incomplete final rows are padded so widths stay equal. A single button stays one column.
- Root `button-columns` / `buttonColumns`: `"smart"` or `"auto"` restores smart layout; `1`, `2`, or `3` forces that many columns (capped by button count).
- Omit `button-columns` to leave the previous column mode. Clear the footer with `"buttons": []` (merges onto the previous payload and keeps text, charts, and other content), `--clear-buttons`, or `--json '{"buttons":[]}'`. Omit the `buttons` key to leave the previous button list.
### Button border styling
Buttons are **borderless** by default. Borders come from widget-level defaults and optional per-button overrides.
**Root defaults** (apply to every button unless overridden):
- `button-border` / `buttonBorder` — shorthand width + color, e.g. `"2px #0f0aff"`
- `button-border-color` / `buttonBorderColor`
- `button-border-width` / `buttonBorderWidth` (`0`–`12`)
- `button-border-radius` / `buttonBorderRadius` (`0`–`48`)
**Per-button overrides:** `border`, `border-color`, `border-width`, `border-radius` win over the matching root default.
**Shorthand rules:** tokens may be `WIDTH`, `WIDTHpx`, and/or a color (`#rrggbb`, named colors, etc.), in either order. Optional `solid` / `none` tokens are ignored. Empty string clears width + color from that shorthand. Explicit `border-color` / `border-width` (or root equivalents) after a shorthand override those parts.
**Effective stroke:** if a border color is set and width is omitted, width defaults to **1**. If neither color nor width is set, width is **0** (no stroke). Corner radius defaults to **8** when omitted.
Root border keys persist like other payload fields: send them without `buttons` to restyle the current grid; omit them to keep previous defaults.
### Button platform notes
On **iOS**, `open-app` and `run-command` buttons render muted and do not run (macOS supports all action types). When any launcher buttons are present, the whole-widget tap URL is omitted on macOS so the footer controls stay interactive.
```bash
terminal-widget --target widget1 --json - <<'EOF'
{
"text": "Status board",
"button-columns": 2,
"button-border": "2px #0f0aff",
"button-border-radius": 10,
"buttons": [
{"label": "Docs", "icon": "doc.text", "color": "#5ac5fa", "border": "1px #ffffff", "border-radius": 10, "action-type": "open-url", "action-value": "https://terminalwidget.app"},
{"label": "Marked", "color": "#22c55e", "action-type": "open-app", "action-value": "com.brettterpstra.marked2"},
{"label": "Refresh", "action-type": "refresh", "action-value": "https://example.com/widget.json"}
]
}
EOF
```
### Title and custom caption (`--title`, `--title-color`, `--caption-text`)
`--title` renders a small caption-style line at the top (inside padding). `--caption-text` sets custom footer text below the main content and implies `--caption` (no `[min/max]` or `[n%]` auto text). Both accept GitHub `:emoji:` shortcodes like `--text`.
```bash
terminal-widget --target widget1 --text "Build queue" --title ":chart_with_upwards_trend: Throughput" --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 --text "Deploy log" --title "Left-aligned title" --title-alignment left --fg "#e2e8f0" --bg "#0f172a"
```
`--title-alignment` accepts `left`, `center` (default when `--title` is set), or `right`.
### Text vs caption colors (`--text-color`, `--caption-color`)
Use `--foreground` for icons, charts, and progress visuals. Optionally set `--text-color` so the main `--text` line (and table defaults) differ from `--foreground`, and `--caption-color` for `[min/max]`, `[n%]`, `--caption-text`, and `--timestamp` lines.
```bash
terminal-widget --target widget1 --text "Queues" --foreground "#64748b" --text-color "#2dd4bf" --progress 55 --caption --timestamp --caption-color "#fbbf24" --bg "#0f172a"
```
### Single-Line Truncation (`--no-wrap`)
```bash
terminal-widget --target widget1 --text "This is a very long line that truncates instead of wrapping in the widget" --no-wrap
```
### Terminal Output (`terminal-output`)
```bash
cal -A 1 | terminal-widget --target widget1 --text - --font menlo --bg "333333" --fg "#e1c245" --no-wrap
```
### Icon-Only Widget
When no `--text`, `--progress`, `--chart`, `--image`, or `--command` is present, the icon is centered and scaled.
```bash
terminal-widget --target widget1 --icon "terminal.fill"
```
### ANSI Text (`--ansi-mode`, `--strip-colors`)
Use ANSI escape sequences for foreground/background color blocks in text mode, or strip them when you want plain text.
```bash
printf '\033[30;47m black on white \033[0m \033[97;44m white on blue \033[0m' | terminal-widget --target widget1 --text - --ansi-mode on
printf '\033[31mred text\033[0m' | terminal-widget --target widget1 --text - --strip-colors
```
## Progress Widgets
Progress mode uses `--progress 0..100`. Add `--progress-format` to choose a visual style.
### `bar` (default)
```bash
terminal-widget --target widget1 --text "Syncing assets" --progress 42 --progress-format bar
```
### `matrix`
```bash
terminal-widget --target widget1 --text "Compile queue" --progress 74 --progress-format matrix --caption
```
### `dots`
```bash
terminal-widget --target widget1 --text "Packaging release" --progress 92 --progress-format dots --caption
```
### `stack`
```bash
terminal-widget --target widget1 --text "Layer sync" --progress 68 --progress-format stack --caption
```
### `gradient` / `gradient-horizontal`
`gradient` is an alias for `gradient-horizontal`.
```bash
terminal-widget --target widget1 --text "Transfer queue" --progress 52 --progress-format gradient --gradient-from "#4fd1ff" --caption
```
### `gradient-vertical`
Use `--gradient-width` to render a narrower vertical progress bar.
```bash
terminal-widget --target widget1 --text "Build queue" --progress 63 --progress-format gradient-vertical --gradient-from "rgba(126,240,168,0.95)" --gradient-width 32 --caption
```
### `circle`
```bash
terminal-widget --target widget1 --text "Build Progress" --progress 72 --progress-format circle --fg "#7ee081" --caption --bg "#2a1f44"
```
macOS gallery slot **progress-circle** matches the command above (`capture-macos-widgets.sh --only progress-circle`).
### `watch` (clock-style arc)
```bash
terminal-widget --target widget1 --text "Build time" --progress 58 --progress-format watch --fg "#a78bfa" --caption --bg "#1e293b"
```
macOS gallery slot **progress-watch** matches the command above (`capture-macos-widgets.sh --only progress-watch`).
## Chart Widgets
Chart mode uses `--chart "N N ..."` with `--chart-format`. `rangebar` uses `low-high` pairs instead of single numeric values.
### Grouped sparkline/bar (`/` series)
Use slash-separated segments for side-by-side sub-bars per column (up to four series). Pair with comma-separated `--foreground` for per-series colors.
```bash
terminal-widget --target widget1 --chart "0 1 5 2/1 2 5 3/2 3 4 1" --chart-format bar --bar-radius 20 --fg "#ee9b00,#e9d8a6,#94d2bd" --annotate --bg "#001219"
```
macOS gallery slot **chart-grouped** matches the command above (`capture-macos-widgets.sh --only chart-grouped`). iOS interactive scene **chart-grouped** uses the same slash syntax on all three widget targets.
### Starter Example
```bash
terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5 10 6" --chart-format sparkline
```
### Append and limit (`--append`, `--limit`)
Use `--append` to add chart columns (same syntax as `--chart`, including slash-grouped series and rangebar `low-high` pairs) or text lines without replacing the rest of the widget. Use `--limit N` for a rolling window of the newest N columns/lines (`0` clears the soft limit; charts still hard-cap at 128 newest points).
```bash
terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5" --chart-format sparkline --limit 8 --bar-radius 20 --chart-bar-style glass --fg "#ffffff" --bg "#9b1e86"
terminal-widget --target widget1 --append "10 6" --limit 8
```
macOS gallery slot **chart-append-limit** matches the sequence above.
### Bar radius (`--bar-radius`)
Use `--bar-radius 0..100` to round sparkline bar corners, or **range bar** column corners in `rangebar` mode.
```bash
terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5 10 6" --chart-format sparkline --bar-radius 45
terminal-widget --target widget1 --chart "1-3,2-4,1-5" --chart-format rangebar --bar-radius 40
```
### Chart bar style (`--chart-bar-style`)
Use `--chart-bar-style glass` with bar-like formats (**sparkline**, **waveform**, **rangebar**, **matrix**, **delta**) for a gradient “liquid glass” bar/cell treatment (default is solid). The same flag applies to **circle** progress rings (`--progress-format circle`) without chart data.
```bash
terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5 10 6" --chart-format sparkline --chart-bar-style glass --bar-radius 35
terminal-widget --target widget1 --progress 72 --progress-format circle --chart-bar-style glass --fg "#4a9eff" --caption
terminal-widget --chart "6-8,1-8,1-6,2-4,1-6" --chart-format rangebar --chart-bar-style glass --bar-radius 40 --target widget1 --bg "ffffff" --fg "ca4fae" --text "TerminalWidget" --text-color "#5ac5fa"
```
macOS gallery slot **chart-rangebar-glass** matches the range bar example above (run `capture-macos-widgets.sh --only chart-rangebar-glass` after placing widgets).
### All Chart Modes
```bash
DATA="1 4 9 3 8 2 7 5 10 6"
terminal-widget --target widget1 --chart "$DATA" --chart-format sparkline
terminal-widget --target widget1 --chart "$DATA" --chart-format graph
terminal-widget --target widget1 --chart "$DATA" --chart-format waveform
terminal-widget --target widget1 --chart "$DATA" --chart-format area
terminal-widget --target widget1 --chart "$DATA" --chart-format lollipop
terminal-widget --target widget1 --chart "$DATA" --chart-format strip
terminal-widget --target widget1 --chart "$DATA" --chart-format radial
terminal-widget --target widget1 --chart "$DATA" --chart-format delta
terminal-widget --target widget1 --chart "$DATA" --chart-format threshold
terminal-widget --target widget1 --chart "$DATA" --chart-format smooth
terminal-widget --target widget1 --chart "$DATA" --chart-format sine
terminal-widget --target widget1 --chart "$DATA" --chart-format peak
terminal-widget --target widget1 --chart "$DATA" --chart-format matrix
terminal-widget --chart "5-6,1-6,1-5,1.5-4,1-5" --chart-format rangebar --target widget1 --bg "ffffff" --fg "ca4fae"
```
### Range Bar
`rangebar` draws each bar as one contiguous inclusive range. The y axis starts at `0` and scales to the highest range endpoint plus one.
```bash
terminal-widget --chart "5-6,1-6,1-5,1.5-4,1-5" --chart-format rangebar --target widget1 --bg "ffffff" --fg "ca4fae"
```
### Chart Annotation (`--annotate`)
`--annotate` overlays point/bar labels for `sparkline`, `graph`, `waveform`, and `rangebar` chart families.
```bash
terminal-widget --target widget1 --chart "5 12 8 21 13 34" --chart-format graph --annotate
terminal-widget --target widget1 --chart "5 12 8 21 13 34" --chart-format sparkline --annotate
```
Gallery captures for bar-style annotations use slug **chart-annotate-bars** (`capture-macos-widgets.sh` / `capture-ios-widgets-interactive.sh --only chart-annotate-bars`).
### Y axis labels (`--label-y`) and update time (`--timestamp`)
`--label-y` adds a left axis with five labels spanning the chart’s value range (and `0…max+1` for `rangebar`). `--timestamp` shows a short local “last updated” line at the bottom on any widget type when no chart/progress footer already shows it; on charts/progress it can be combined with `--caption`, `--caption-text`, or used alone. Both apply to the same update that sets the payload (not the WidgetKit refresh schedule).
```bash
terminal-widget --target widget1 --chart "1 4 9 3 8 2 7 5 10 6" --chart-format sparkline --label-y --caption
terminal-widget --target widget1 --chart "5 12 8 21 13 34" --chart-format graph --caption --timestamp
terminal-widget --target widget1 --text "Syncing" --progress 42 --caption --timestamp
```
## Styling and Layout Flags
## Emoji + Tables
TerminalWidget expands GitHub-style `:shortcode:` aliases (same set as GitHub-flavored Markdown) in **`--text`**, **`--icon`**, **`--title`**, and **`--caption-text`**, plus table cell strings from **`--table`**. Examples: `:rocket:` → 🚀, `:white_check_mark:` → ✅, `:clock3:` → 🕒.
```bash
terminal-widget --target widget1 --text "Deploy :rocket:" --icon :smiley:
terminal-widget --target widget1 --title ":chart_with_upwards_trend: Weekly" --caption-text "Updated :clock3:"
```
Use these exact commands when capturing screenshot slots:
### Emoji Icon + Background (`emoji-icon-bg`)
```bash
terminal-widget --target widget1 --icon :x: --bg "#ff5f5f"
```
### Table with Zebra Grid (`table-grid-zebra`)
```bash
terminal-widget --target widget1 --table ~/status/status.csv --grid zebra --zebra-opacity 60 --mode dark
```
### Table with Row + Column Grid (`table-grid-both`)
```bash
terminal-widget --target widget1 --table ~/status/status.csv --grid both --mode dark
```
### Table with Header Rule Only (`table-grid-none`)
```bash
terminal-widget --target widget1 --table ~/status/status.csv --grid none --mode dark
```
### Table cell markdown links (`table-cell-links`)
Table cells accept the same `[label](url)` syntax as `--text`. Linked labels render as tappable buttons; other cell text stays plain.
```bash
cat scripts/fixtures/capture-table-links.csv | terminal-widget --target widget1 --table - --grid zebra --mode dark --table-layout equal
```
### Optional STDIN Variant
```bash
cat ~/status/status.csv | terminal-widget --target widget1 --table -
```
### Foreground / Background (`--foreground`, `--background`, aliases `--fg`, `--bg`)
These set text/icon/chart/progress foreground and widget background colors for this payload.
```bash
terminal-widget --target widget1 --text "Night mode test" --icon "moon.stars.fill" --fg "#dbeafe" --bg "#0b1220"
```
### Full-size (`--fullsize`, alias for `--padding 0`)
Useful for edge-to-edge charts/images and dense visual widgets.
```bash
terminal-widget --target widget1 --chart "2 6 4 9 7 3 8 5" --chart-format area --fullsize
```
### Image + Full Width (`--image` + `--full-width`)
Use a remote image source and fill mode for edge-to-edge image rendering.
```bash
terminal-widget --target widget1 --image "https://picsum.photos/400/400" --full-width
```
### SVG diagrams
WidgetKit’s SVG renderer is not full WebKit. SVGs that use `` or `` often look correct in Safari, Sketch, and similar apps, but labels can be missing or wrong in the widget. **Convert text to outlines/paths** before passing the file to `--image` — then display is clean.
Easiest conversion is usually the Inkscape CLI:
```bash
inkscape treeBoxes.svg --export-text-to-path --export-plain-svg --export-filename=usingPaths.svg
```
Then point TerminalWidget at the outlined file:
```bash
terminal-widget --target widget1 --image ./usingPaths.svg
```
### Image Filters (`--filter`)
Apply built-in filters to images. You can pass one filter, repeat `--filter`, or provide a comma-separated filter chain.
```bash
terminal-widget --target widget1 --image "https://picsum.photos/640/640" --filter sepia:35
terminal-widget --target widget1 --image "https://picsum.photos/640/640" --filter grayscale
terminal-widget --target widget1 --image "https://picsum.photos/640/640" --filter "sepia:25,blur:8"
```
### Icon Behavior (`--icon`)
`--icon` is inline with text/progress/chart, or centered if icon-only mode is active.
```bash
terminal-widget --target widget1 --text "CPU 62%" --icon "cpu.fill" --chart "58 61 66 62 64 62" --chart-format strip
```