- name
- wled
- description
- Control WLED LED controllers via HTTP API. Use when a user asks to control WLED lights, LED strips, or ESP-based LED controllers. Supports power on/off, brightness, colors (RGB), effects, palettes, presets, and device status.
WLED Control
Control WLED LED strips and matrices via the HTTP JSON API.
Requirements
- WLED device on the same network
- Device IP address or hostname
- Python 3 (no external dependencies)
Usage
All commands require --host (or -H) with the WLED device IP/hostname.
Power Control
python3 scripts/wled.py -H <ip> power # Get power state
python3 scripts/wled.py -H <ip> power on # Turn on
python3 scripts/wled.py -H <ip> power off # Turn offBrightness
python3 scripts/wled.py -H <ip> brightness # Get current brightness
python3 scripts/wled.py -H <ip> brightness 255 # Max brightness
python3 scripts/wled.py -H <ip> brightness 128 # 50% brightnessColors
python3 scripts/wled.py -H <ip> color 255 0 0 # Red
python3 scripts/wled.py -H <ip> color 0 255 0 # Green
python3 scripts/wled.py -H <ip> color 0 0 255 # Blue
python3 scripts/wled.py -H <ip> color 255 255 255 # WhiteEffects
python3 scripts/wled.py -H <ip> effects # List all effects with IDs
python3 scripts/wled.py -H <ip> effect 0 # Solid color
python3 scripts/wled.py -H <ip> effect 9 # Rainbow
python3 scripts/wled.py -H <ip> effect 9 -s 200 # Rainbow, fast speed
python3 scripts/wled.py -H <ip> effect 9 -i 128 # Rainbow, medium intensityPalettes
python3 scripts/wled.py -H <ip> palettes # List all palettes with IDs
python3 scripts/wled.py -H <ip> palette 6 # Set Party palettePresets
python3 scripts/wled.py -H <ip> presets # List saved presets
python3 scripts/wled.py -H <ip> preset 1 # Load preset #1Status
python3 scripts/wled.py -H <ip> status # Full device statusReference
See references/api.md for complete API documentation.
Configuration
Avoid passing --host every time by creating a config file at ~/.wled/config.json:
{
"bedroom": "192.168.1.100",
"kitchen": "192.168.1.101",
"living_room": "wled-abc123.local"
}Then use aliases:
python3 scripts/wled.py -H bedroom brightness 255
python3 scripts/wled.py -H kitchen color 255 0 0Or set the WLED_HOST environment variable:
export WLED_HOST=192.168.1.100
python3 scripts/wled.py brightness 255Finding Your WLED Device
WLED devices can typically be found via:
- Router admin panel (look for ESP device)
- mDNS/Bonjour:
wled-<mac>.local - WLED app discovery
Static IP Recommendation
IP addresses change over time. To avoid updating your config, set a static IP on your WLED device:
Option 1: Router-based (easiest)
- Open your router admin panel
- Find the WLED device by MAC address
- Reserve/assign a static IP
Option 2: On-device
- Access WLED web UI at
http://<current-ip> - Go to Settings → WiFi Settings
- Set static IP manually
- Save and reboot
Using mDNS hostnames (e.g., wled-abc123.local) also avoids IP tracking—routers resolve these automatically.