govee-control

# Govee OpenAPI (No Scripts)

Control Govee devices using manual `curl` commands only.

## Linux System Requirements

- Linux shell with `bash` available.
- `curl` installed.
- Internet access to `https://developer-api.govee.com` and `https://developer.govee.com`.
- Govee account with supported devices linked.
- Optional: `jq` for pretty-printing JSON responses.

Quick check:

```bash
bash --version | head -n 1
curl --version | head -n 1
command -v jq >/dev/null && jq --version || echo "jq not installed (optional)"
```

## Required Credential

- `GOVEE_API_KEY` (required)

## Autonomous Use Guardrails

- Only read `GOVEE_API_KEY` from your chosen per-user secrets file.
- Do not read unrelated secret files or system credentials.
- Restrict outbound requests to:
  - `https://developer-api.govee.com`
  - `https://developer.govee.com`
- Ask before controlling multiple devices or performing bulk changes.

## Get a Govee API Key

1. Open `https://developer.govee.com/`.
2. Sign in with the same Govee account that owns your devices.
3. Go to the API key section in the developer console.
4. Generate/apply for a key and copy it.
5. Keep it private (treat it like a password).

If the portal UI changes, use the same flow: sign in to Govee Developer → find API key management → create key.

## Secure Local Storage (Per-User)

Never store API keys in skill files, git, or chat logs.

Create a per-user secrets file (avoid `/root` unless intentionally running as root):

```bash
mkdir -p "$HOME/.openclaw/secrets"
cat > "$HOME/.openclaw/secrets/govee.env" <<'EOF'
export GOVEE_API_KEY='<YOUR_API_KEY>'
EOF
chmod 600 "$HOME/.openclaw/secrets/govee.env"
```

Load only this variable into the current shell (no `set -a`):

```bash
source "$HOME/.openclaw/secrets/govee.env"
```

## API Base URL

```bash
https://developer-api.govee.com/v1
```

## Discover Devices First

Before controlling lights, list devices and copy your own `device` + `model`:

```bash
curl -sS -X GET "https://developer-api.govee.com/v1/devices" \
  -H "Govee-API-Key: $GOVEE_API_KEY" \
  -H "Content-Type: application/json"
```

## View Device State

```bash
curl -sS -X GET "https://developer-api.govee.com/v1/devices/state?device=<DEVICE>&model=<MODEL>" \
  -H "Govee-API-Key: $GOVEE_API_KEY" \
  -H "Content-Type: application/json"
```

## Control Commands

### Turn on

```bash
curl -sS -X PUT "https://developer-api.govee.com/v1/devices/control" \
  -H "Govee-API-Key: $GOVEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device":"<DEVICE>","model":"<MODEL>","cmd":{"name":"turn","value":"on"}}'
```

### Turn off

```bash
curl -sS -X PUT "https://developer-api.govee.com/v1/devices/control" \
  -H "Govee-API-Key: $GOVEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device":"<DEVICE>","model":"<MODEL>","cmd":{"name":"turn","value":"off"}}'
```

### Brightness (1-100)

```bash
curl -sS -X PUT "https://developer-api.govee.com/v1/devices/control" \
  -H "Govee-API-Key: $GOVEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device":"<DEVICE>","model":"<MODEL>","cmd":{"name":"brightness","value":75}}'
```

### RGB color

```bash
curl -sS -X PUT "https://developer-api.govee.com/v1/devices/control" \
  -H "Govee-API-Key: $GOVEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device":"<DEVICE>","model":"<MODEL>","cmd":{"name":"color","value":{"r":120,"g":180,"b":255}}}'
```

## Response Check

Success usually returns:

```json
{"code":200,"message":"Success"}
```

If `code` is not `200`, treat it as failure.

## Troubleshooting

- `401` / unauthorized: key missing, expired, or invalid.
- `429` / rate limit: slow retries.
- command rejected: model does not support that command (`supportCmds`).
- empty device list: account has no supported linked devices.

## Safety Rules

- Use placeholders in docs only (`<DEVICE>`, `<MODEL>`, `<YOUR_API_KEY>`).
- Do not include real keys or device IDs in published artifacts.
- Prefer one-device-at-a-time actions over bulk changes.
- Avoid pasting API keys into chat.