mirror of
https://github.com/hanzoskill/homey.git
synced 2026-10-30 21:10:06 +00:00
3.3 KiB
3.3 KiB
Output contract (JSON)
This CLI is designed to be called by agents. When --json is set:
- Success outputs JSON to stdout.
- Errors output JSON to stdout in a stable shape (see below).
- Text output (without
--json) is intended for humans and may change.
Error JSON (stable)
All errors use this envelope:
{
"error": {
"code": "AMBIGUOUS",
"message": "...",
"details": {
"candidates": [{"id": "...", "name": "..."}]
}
}
}
Notes:
detailsis optional.- When present,
details.candidatesis an array of{ id, name }objects.
Exit codes are documented in docs/errors.md.
Success JSON (stable fields)
homeycli auth status --json
{
"modeWanted": "auto",
"modeWantedSource": "config",
"modeSelected": "local",
"path": "/Users/.../.homey/config.json",
"local": {
"addressPresent": true,
"tokenPresent": true,
"address": "http://192.168.1.50",
"addressSource": "config",
"tokenSource": "config"
},
"cloud": {
"tokenPresent": true,
"tokenSource": "config"
}
}
homeycli auth set-token ... --json (cloud)
{
"saved": true,
"kind": "cloud",
"source": "config",
"path": "/Users/.../.homey/config.json"
}
homeycli auth discover-local ... --json
{
"discovered": true,
"candidates": [{ "index": 1, "address": "http://192.168.1.50", "homeyId": "...", "host": "192.168.1.50", "port": 80 }]
}
homeycli auth set-local ... --json (local)
{
"saved": true,
"kind": "local",
"address": "http://192.168.1.50",
"path": "/Users/.../.homey/config.json"
}
homeycli status --json
{
"name": "Homey",
"platform": "local|cloud|...",
"platformVersion": 2,
"hostname": "...",
"cloudId": "...",
"homeyId": "...",
"connected": true,
"connectionMode": "local|cloud",
"address": "http://192.168.1.50"
}
Notes:
addressis only present inlocalmode.cloudIdis kept for backwards compatibility; preferhomeyId.
homeycli zones --json
Array of zones:
id(string)name(string)parent(string|null)icon(string|null)
homeycli devices --json / homeycli device <id> ... --json
Array of devices (or a single device depending on command). Stable fields per device:
id(string)name(string)zoneId(string|null)zoneName(string|null)zone(string|null) – convenience display fieldclass(string)capabilities(string[])capabilitiesObj(object) – Homey capability metadata + latest valuesvalues(object) –{ [capabilityId]: value }available(boolean)ready(boolean)
homeycli flows --json
Array of flows:
id(string)name(string)enabled(boolean)folder(string|null)
homeycli flow trigger <idOrName> --json
Returns the triggered flow object (same shape as flows above).
homeycli snapshot --json
{
"status": { /* same as status */ },
"zones": [ /* same as zones */ ],
"devices": [ /* same as devices */ ],
"flows": [ /* optional; same as flows */ ]
}
--raw (intentionally unstable)
When --raw is set, responses may include a raw field containing the underlying Homey API object.
rawis very verbose and may change at any time.- Agents should not depend on
rawfields for core behavior.