Back to HyperTray

Script API

HyperTray can run any shell command on a schedule and render its output as a status icon. This page explains the output format, time limits, icon naming, and shows a few working examples.

Any shell command

Bash, zsh, python, node, or any executable on your Mac. Use curl, jq, gh, or any CLI you have installed.

JSON output

Print a single JSON object to stdout. HyperTray reads icon, text, and icon_color from it.

5 second limit

Scripts must finish within 5 seconds. Slow or hanging commands show a warning/failed icon.

Expected output

Your script must print exactly one JSON object to stdout. All fields are optional, but at least one of icon or text should be present for something to appear in the tray.

{
  "icon": "sun",
  "text": "30°",
  "icon_color": "#f59e0b"
}
  • 1icon — a glyph name from the Lucide icon library (e.g. sun, cloud-rain, bitcoin). See lucide.dev/icons.
  • 2text — the label shown next to the icon. Keep it short; the menu bar has limited space. Maximum 10 characters is recommended.
  • 3icon_color — optional hex, RGB, or named CSS color for the icon. If omitted, HyperTray falls back to the automation's on/off color.

About icons

HyperTray uses the Lucide icon set. Any icon name you find on lucide.dev/icons can be used as the icon value. Use the kebab-case name shown on the site — for example git-pull-request, mail-plus, or cloud-rain.

If you pass an icon name that does not exist, HyperTray will show a fallback icon. If you do not pass an icon at all, only the text label is rendered.

Time limit & errors

Each script invocation is killed after 5 seconds. If the script exits with a non-zero status, prints invalid JSON, or prints nothing, HyperTray shows a warning/failed state so you know the automation needs attention.

Examples

Switch tabs to see real scripts. Click Copy to grab the source code for your own automation.

# Bitcoin price (max 10 chars)
price=$(curl -s "https://api.coinbase.com/v2/prices/BTC-USD/spot" \
  | jq -r '.data.amount' | awk '{printf "$%.1fk", $1/1000}')

echo "{\"text\": \"$price\", \"icon\": \"bitcoin\"}"
$67.4kevery 1 min

Generate your own

Not sure what to build? Copy the prompt below and paste it into your favorite LLM. It contains the full output contract and asks you to describe what you want the script to reflect.