wled

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 off

Brightness

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% brightness

Colors

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   # White

Effects

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 intensity

Palettes

python3 scripts/wled.py -H <ip> palettes            # List all palettes with IDs
python3 scripts/wled.py -H <ip> palette 6           # Set Party palette

Presets

python3 scripts/wled.py -H <ip> presets             # List saved presets
python3 scripts/wled.py -H <ip> preset 1            # Load preset #1

Status

python3 scripts/wled.py -H <ip> status              # Full device status

Reference

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 0

Or set the WLED_HOST environment variable:

export WLED_HOST=192.168.1.100
python3 scripts/wled.py brightness 255

Finding 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)

1. Open your router admin panel
2. Find the WLED device by MAC address
3. Reserve/assign a static IP

Option 2: On-device

1. Access WLED web UI at http://<current-ip>
2. Go to Settings → WiFi Settings
3. Set static IP manually
4. Save and reboot

Using mDNS hostnames (e.g., wled-abc123.local) also avoids IP tracking—routers resolve these automatically.