Generate a fresh image with the OpenAI Image API (GPT Image) and show it in a Terminal Widget via --image.
Each run is a paid API call. Prefer long intervals (hours or days), not every few minutes.
Requirements
- Terminal Widget (
terminal-widgetCLI) - An OpenAI API key with image generation access
- Org API verification may be required for GPT Image models
curl,jq, andbase64(brew install jq)
1. Create an OpenAI API key
- Sign in at platform.openai.com.
- Open API keys → Create new secret key.
- Copy the key (
sk-…). Store it only in your local config file. - Confirm billing is enabled and that your org can use GPT Image (
gpt-image-1-mini,gpt-image-1,gpt-image-2, etc.).
2. Create openai.env
mkdir -p ~/.config/terminal-widget
chmod 700 ~/.config/terminal-widget
Create ~/.config/terminal-widget/openai.env:
# Required
export OPENAI_API_KEY='sk-your_key_here'
# Optional defaults when the script is run with no / partial arguments
# export OPENAI_IMAGE_TARGET='openai-image'
# export OPENAI_IMAGE_PROMPT='neon rain on a quiet street' # theme text, or omit for surprise default
# export OPENAI_IMAGE_SIZE='square' # square | landscape | portrait | 1024x1024 | …
# export OPENAI_IMAGE_MODEL='gpt-image-1-mini' # or gpt-image-1 / gpt-image-2
# export OPENAI_IMAGE_QUALITY='low' # low | medium | high | auto
# export OPENAI_IMAGE_PROMPT_MODE='theme' # theme (wrap) | raw (use prompt as-is)
# export OPENAI_IMAGE_PROMPT_PREFIX='A striking wallpaper-style image of'
# export OPENAI_IMAGE_DEFAULT_PROMPT='A surprising, beautiful wallpaper-style scene…'
# Optional: Shortcut name for tap-to-refresh (recommended; run-command is sandboxed)
# export OPENAI_TAP_SHORTCUT='OpenAI Image Refresh'
# Optional: path to the CLI if it is not on PATH
# export TERMINAL_WIDGET='/opt/homebrew/bin/terminal-widget'
Lock it down:
chmod 600 ~/.config/terminal-widget/openai.env
Alternate config path: set OPENAI_ENV=/path/to/your.env before running.
3. Add a widget target
| Target ID | Purpose |
|---|
| openai-image | Default when no CLI args / env overrides are set |
Use distinct targets per theme (e.g. openai-neon, openai-forest) if you run multiple LaunchAgents.
4. Install and run
Save the script as ~/bin/openai-image.sh (or ~/Scripts/…), then:
chmod +x ~/bin/openai-image.sh
~/bin/openai-image.sh
# theme + size:
~/bin/openai-image.sh openai-neon "neon rain on a quiet street" landscape
# surprise default prompt:
~/bin/openai-image.sh openai-image - square
Add a Desktop widget and choose that target. Generated PNGs are cached under ~/.cache/terminal-widget/openai-image-<target>.png.
5. Schedule updates
Enable the launchd section on this recipe (suggested: 6 hours or longer). The auto-generated agent runs the script with no arguments, using openai.env defaults.
Customize the LaunchAgent (target + prompt)
Edit ProgramArguments after creating the plist:
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>/Users/YOU/bin/openai-image.sh</string>
<string>openai-neon</string>
<string>neon rain on a quiet street</string>
<string>landscape</string>
</array>
| Argument | Meaning |
|---|---|
| 1 — target | Terminal Widget target name |
| 2 — prompt | Theme text, or - for the default/surprise prompt |
| 3 — size | square, landscape, portrait, or WxH |
Multiple widgets
Duplicate the plist (unique Label + logs), change the three args, create matching targets, bootstrap each job. Watch your OpenAI usage — N widgets × interval = N billable images.
Tap to refresh
App Sandbox blocks run-command from running Homebrew/~/Scripts. Use a Shortcut:
- Shortcuts → OpenAI Image Refresh → Run Shell Script with the same command you use manually.
- Set
OPENAI_TAP_SHORTCUT='OpenAI Image Refresh'inopenai.env. - Re-run the script once so the widget stores
run-shortcut.
Environment variables reference
| Variable | Required | Default | Description |
|---|---|---|---|
OPENAI_API_KEY |
Yes | — | OpenAI secret key |
OPENAI_IMAGE_TARGET |
No | openai-image |
Widget target when arg 1 is omitted |
OPENAI_IMAGE_PROMPT |
No | surprise default | Prompt/theme when arg 2 is - / omitted |
OPENAI_IMAGE_SIZE |
No | square |
Size preset or WxH |
OPENAI_IMAGE_MODEL |
No | gpt-image-1-mini |
Image model id |
OPENAI_IMAGE_QUALITY |
No | low |
low / medium / high / auto |
OPENAI_IMAGE_PROMPT_MODE |
No | theme |
theme wraps the subject; raw sends arg/env as the full prompt |
OPENAI_TAP_SHORTCUT |
No | — | Shortcut name for tap refresh |
OPENAI_ENV |
No | ~/.config/terminal-widget/openai.env |
Config path |
TERMINAL_WIDGET |
No | terminal-widget |
CLI path |
WIDGET_CACHE_DIR |
No | ~/.cache/terminal-widget |
Where PNGs are written |
Troubleshooting
| Symptom | Likely cause |
|---|---|
| “OPENAI_API_KEY not set” | Missing/empty openai.env |
| Verification / model errors | Complete org API verification; try gpt-image-1-mini |
| Billing / quota errors | Add payment method or lower quality/size/frequency |
| Slow updates | Image gen takes several seconds; quality low is faster |
Tap does nothing with run-command |
Expected under sandbox — use OPENAI_TAP_SHORTCUT instead |