Help & Documentation
Everything you need to get started with LumenSky
Getting Started
- Download & Install - Download the DMG, drag LumenSky to Applications
- Launch - Open LumenSky from Applications (or Spotlight)
- Menu Bar - Look for the weather icon in your menu bar
- Choose a Scene - Click the icon and select any weather effect
- Enable at Login - Check "Open at Login" so it starts automatically
The LumenSky menu bar dropdown with weather modes
That's it! LumenSky runs as a menu bar app with no dock icon.
Live Weather Setup
LumenSky can sync with your real-world weather using OpenWeatherMap.
Get a Free API Key
- Go to openweathermap.org/api
- Sign up for a free account
- Navigate to "API Keys" in your account
- Copy your API key
Configure in LumenSky
- Click the LumenSky menu bar icon
- Go to Live Weather → Configure API Key
- Paste your key and click Save
- Enable Live Weather from the menu
Configure your API key for live weather sync
Note: The free tier allows 1,000 API calls/day—more than enough for personal use.
URL Hooks (Automation)
Control LumenSky from the Terminal, Shortcuts app, or any automation tool using URL schemes.
Supported Commands
| Action | URL |
|---|---|
| Set weather mode | lumensky://mode/snow |
| Temporary mode (5 sec) | lumensky://mode/fireworks/5 |
| Next random scene | lumensky://next |
| Refresh weather | lumensky://refresh |
| Enable live weather | lumensky://weather/on |
| Disable live weather | lumensky://weather/off |
| Toggle live weather | lumensky://weather |
Available Modes
rain, rainShower, snow, hail, wind,
sunny, cloudy, lightning, night,
meteor,
aurora, rainbow, foggy, drizzle,
sleet, frost, dust, thunderstorm,
blizzard, tornado, cherryBlossom, clearSky,
comet, fireworks, confetti, random
Usage Examples
# From Terminal
open "lumensky://mode/aurora"
# Confetti celebration for 5 seconds
open "lumensky://mode/confetti/5"
# Fireworks for 10 seconds
open "lumensky://mode/fireworks/10"
# From AppleScript
do shell script "open 'lumensky://mode/snow'"
Multi-Monitor Setup
LumenSky supports independent scenes on each display.
Configure Displays
- Click the menu bar icon
- Select Configure Displays...
- Drag scene cards onto each monitor
- Mix Live Weather with manual scenes
Drag and drop scenes onto your monitor layout
Tip: You can run Aurora on your main display while having Rain on your secondary monitor!
Random Mode
Automatically cycle through different weather scenes at customizable intervals.
Configure Random Mode
- Select Random from the weather modes menu
- Click Configure Random Mode...
- Set your preferred interval (e.g., every 5 minutes)
- Exclude any scenes you don't want in the rotation
Customize your random scene rotation and exclusions
Global Hotkey
Skip to the next random scene from anywhere with a keyboard shortcut.
Configure Shortcut
- Click the menu bar icon
- In Random Mode section, click Configure Shortcut...
- Press your desired key combination (e.g.,
⌘N) - Click Save
Set a global keyboard shortcut for quick scene switching
The shortcut works globally—even when other apps are focused.
Troubleshooting
Make sure LumenSky is running (check menu bar). Try clicking "Refresh Now" in the menu. On some Macs, you may need to grant Screen Recording permission in System Settings → Privacy & Security.
LumenSky uses your location to fetch weather. Ensure Location Services are enabled in System Settings → Privacy & Security → Location Services. Try "Refresh Now" to force an update.
LumenSky pauses rendering when the screen is locked or the app is covered. If usage is still high, try reducing the number of active displays or switching to simpler scenes like Clear Sky.
Open LumenSky, click the menu bar icon, and enable "Open at Login". If it still doesn't work, check System Settings → General → Login Items.
Right-click the app and select "Open". This bypasses Gatekeeper for the first launch. The app is safe—it's just not notarized yet.