Direct Bluetooth Mesh control of amaran studio lights. The amaran CLI talks
to the lights over BLE mesh (Telink protocol) — the amaran Desktop app is not
required at runtime and must be quit while using the CLI (it holds the BLE
connections).
Requirements
- macOS with Bluetooth on; grant Bluetooth permission to the terminal when prompted.
- Python 3.10+.
- One-time: the amaran Desktop app must have paired the lights at least once — its local database contains the mesh keys needed to join the network.
Install
cd amaran-cli # repo containing this file
python3 -m venv .venv
.venv/bin/pip install -e .
ln -sf "$PWD/.venv/bin/amaran" ~/.local/bin/amaran # or any dir in PATH
Setup (one time)
amaran setup # imports mesh keys + light list from the amaran Desktop DB
amaran lights # shows your lights: keys, mesh addresses, MACs
Config is written to ~/.config/amaran/lights.json and can be edited by hand
(light key fields are the CLI target names).
Commands
amaran on [target] # turn on (wake)
amaran off [target] # turn off (sleep)
amaran bright <0-100> [target] # brightness percent
amaran cct <0-100> <kelvin> [target] # brightness + color temp (e.g. 4300, 5600)
amaran cct 60 3200 --gm 5 [target] # optional green/magenta shift -10..+10
amaran hsi <0-100> <hue> <sat> [target] # color: hue 0-360, sat 0-100 (RGB fixtures only)
amaran status [target] # query current state from the lights
amaran repl # interactive mode: stays connected, much faster
amaran scan # list nearby mesh lights (raw BLE view)
amaran lights # list configured lights (no BLE)
Targeting
- Omit the target (or use
all) to address the whole group at once. - Targets are case-insensitive substrings of the light keys/names shown by
amaran lights. A substring matching several lights hits all of them (e.g. a shared model name), a full key hits exactly one. - Always run
amaran lightsfirst on a new setup to learn the actual target names — never guess them.
Agent operating rules
- If a command fails with "no mesh proxy connection", tell the user to quit the amaran Desktop app and enable Bluetooth, then retry.
statusreplies occasionally get lost in the mesh — retry once before concluding a light is unreachable.- After changing settings, verify with
amaran statuswhen the result matters (commands are fire-and-forget with mesh retries, no ack). - Use
amaran replfor sequences of several adjustments — direct commands reconnect each time (~5-10s); the REPL stays connected. - Not every fixture supports every mode: bi-color lights do CCT only; HSI and
--gm require RGBWW fixtures. A rejected mode fails silently — check
status. - Individual fixtures may cap brightness (power/thermal limits). If a light ignores brightness but accepts CCT/on/off, report it to the user instead of retrying in a loop.
Linking this skill
Drop or symlink this file wherever your agent loads skills from, e.g.:
mkdir -p ~/.config/opencode/skills
ln -s "$PWD" ~/.config/opencode/skills/amaran-lights # dir containing SKILL.md