New recipes and diagnostics for TerminalWidget

TerminalWidget is built to turn your desktop and mobile widgets into versatile, programmable displays for whatever data you care about. Over the last few updates, I’ve added some fun new visual capabilities like multi-series charts, pie charts, and centered tables. But even the slickest widget is only as good as the script feeding it, and when something goes wrong with a background task or an image fetch, tracking down why a widget didn’t update can feel like hunting ghosts.

I’ve rolled out a bunch of new recipes on the Recipes gallery, but to tackle the diagnostics side, I built a brand-new diagnostic event logging system featuring twdiags widgets for macOS and iOS. (Thanks to Scrivolical for the push on this.)

Fresh recipes: Server Stats and Planets

If you haven’t browsed the TerminalWidget Recipes page lately, there are some great new additions—both from me and from the community.

The newest recipe in the gallery is Server Stats. If you manage remote Linux servers, VPS instances, or shared hosting with SSH access, this script logs in over SSH once, extracts 1/5/15-minute load averages, memory usage, disk utilization, and uptime days, and renders them into a centered, zebra-striped table widget with a custom background image.

Here’s how the script pipes the remote metrics directly into terminal-widget:

printf '%s' "$tsv" | terminal-widget \
  --target "server-stats" \
  --table - \
  --no-header \
  --grid zebra-row \
  --table-align right,left \
  --table-layout fill \
  --center-table \
  --fit-text \
  --background-image "https://images.unsplash.com/photo-1431440869543-efaf3388c585?q=80&w=2940&auto=format&fit=crop" \
  --fg ffffff \
  --font Menlo

It runs cleanly on a 15-minute launchd timer, and if SSH ever drops out or fails, it exits quietly without clearing out your last good widget state.

Right before that, I published Planets Updated. This builds upon an awesome original script by Dr. Drang that computes azimuth, altitude, and constellations for the Moon, Sun, and visible planets using Python’s astropy library. My updated version formats the output into a clean multi-column table with custom column alignment (--table-align left,right,left,right,left), vertical centering (--center-table), an alpha-blended dark background, and an astronomical backdrop image. It looks especially sharp on Extra Large desktop and iPad widgets.

run([
    "terminal-widget",
    "--target", "planets",
    "--table", "-",
    "--grid", "none",
    "--table-layout", "auto",
    "--center-table",
    "--table-align", "left,right,left,right,left",
    "--bg", "0b1220",
    "--fg", "e2e8f0",
    "--filter", "alpha:80",
    "--background-image", BACKGROUND_IMAGE,
    "--title", "Planets",
    "--timestamp",
], input=table_csv.encode(), check=False)

I’ve also seen fantastic community recipes come in, including Matthew Charlesworth’s Webalizer and Foreign Exchange Rates scripts, Rob Trew’s script for linking flagged lines in Hogbay Software Bike 2.0, and Scrivolical’s colorized nftables status one-liner. If you have a clever setup or workflow, you can submit your own recipe directly on the site.

Silent failures no more: Introducing twdiags

Widgets are inherently asynchronous. Between background LaunchAgents, cron jobs, CloudKit sync, URL-scheme callbacks, and iOS Shortcuts, a lot happens out of sight. When a widget didn’t update or an image showed up blank, figuring out why required digging through system logs or running one-off curl tests.

TerminalWidget now has a dedicated diagnostic logging subsystem that captures silent failures across the host app, CLI, and widget extensions on both macOS and iOS.

The coolest part is how you view it on your devices: twdiags widgets.

Name any widget’s Target name twdiags (case-insensitive) in the widget configuration, and it transforms into a live diagnostic viewer. It displays recent warnings and errors from that specific device while respecting whatever background, font, and color styling you applied to that target.

Because the log is device-local:

• Your iPhone or iPad twdiags widget will show iOS-specific issues like failed Shortcuts payload saves, malformed terminalwidget:// URLs, or missing image downloads.
• Your Mac twdiags widget will show script execution errors, CLI validation failures, and CloudKit sync issues.

Inspecting logs from the CLI: terminal-widget log

On macOS, you can also inspect and stream diagnostic events directly from your shell using the new log subcommand:

# View recent warnings and errors
terminal-widget log --level warn

# Filter events for a specific target widget
terminal-widget log --target server-stats

# Tail diagnostic events in real time
terminal-widget log --follow

# Pipe machine-readable JSON into jq
terminal-widget log --json | jq '.[] | {target: .target, msg: .message, code: .code}'

You can also clear the bounded log whenever you want a fresh slate:

terminal-widget log --clear

What the diagnostic log catches

The diagnostic system monitors a wide swath of potential failure points:

• Widget button & command actions: Non-zero exit codes, stderr output, slow runs exceeding timeouts, and commands terminated by signals are now logged rather than failing silently.
• Image handling: Records failures when fetching remote URLs, copying images into the App Group container, or rendering missing assets.
• CloudKit sync: Captures pull, push, retry, and subscription errors across your synced devices.
• Shortcuts & URL handlers: Catches invalid payloads, malformed URL schemes, or failed persistence calls on iOS.
• Timeline lifecycle: Pairs reload.requested and timeline.built events so you can tell if WidgetKit actually refreshed your widget after a data push.
• Smart throttling: Repetitive events are throttled per target to keep the bounded JSONL log clean and useful.

If you’re on a Mac, you can also view the last 50 events in the Info/Debug panel from the menu bar app, or copy them along with your cloud diagnostics when reporting an issue.

Check out the Recipes gallery to try out the new Server Stats and Planets recipes, and grab the latest TerminalWidget update to get twdiags running on your devices!

Like or share this post Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.