{"skill":{"slug":"hivehome","displayName":"Hive Home","summary":"Control and query Hive Home (UK) smart heating, hot water, lights and devices via the unofficial API. Use when the user mentions Hive, Hive Home, Hive thermo...","description":"---\nname: hivehome\ndescription: Control and query Hive Home (UK) smart heating, hot water, lights and devices via the unofficial API. Use when the user mentions Hive, Hive Home, Hive thermostat, smart heating, Hive app, British Gas Hive, or wants to automate or script Hive devices.\nlicense: MIT\ncompatibility: Requires Python 3, pyhiveapi>=1.0.0, network access. Hive UK account (my.hivehome.com). For non-interactive use set HIVE_DEVICE_* env vars after first login.\nhomepage: https://github.com/yourusername/agent-skills\nmetadata:\n  {\"openclaw\":{\"homepage\":\"https://www.hivehome.com\",\"requires\":{\"env\":[\"HIVE_USERNAME\",\"HIVE_PASSWORD\"]}},\"clawdbot\":{\"emoji\":\"🏠\",\"requires\":{\"env\":[\"HIVE_USERNAME\",\"HIVE_PASSWORD\"]},\"primaryEnv\":\"HIVE_USERNAME\",\"files\":[\"scripts/*\"]}}\n---\n\n# Hive Home (UK)\n\nControl Hive thermostats, hot water, lights and other devices programmatically. Hive does **not** provide a public API; this skill uses the community **Pyhiveapi** library, which talks to the same backend as the Hive app.\n\n**Prefer the bundled scripts** for common actions. Run `scripts/hive_control.py` from the skill directory (or `{baseDir}/scripts/hive_control.py` when the agent has the skill path). Only generate custom Pyhiveapi code when the user needs something the scripts do not support (e.g. lights, multi-zone by name, or custom logic).\n\n**Important:** The API is unofficial. Never hardcode credentials or 2FA codes in prompts, logs or code. Use environment variables or a secure secret store.\n\n## Bundled scripts\n\nFrom the skill root (e.g. `hivehome/` or the skill directory loaded by your agent):\n\n```bash\n# Status (heating + hot water)\npython scripts/hive_control.py status\n\n# Heating\npython scripts/hive_control.py set-temp 21\npython scripts/hive_control.py mode heat\npython scripts/hive_control.py mode schedule\npython scripts/hive_control.py boost 30 21    # 30 min at 21°C\npython scripts/hive_control.py boost-off\n\n# Hot water\npython scripts/hive_control.py hotwater-boost 30\npython scripts/hive_control.py hotwater-boost-off\npython scripts/hive_control.py hotwater-mode schedule\npython scripts/hive_control.py hotwater-mode off\n\n# Multiple zones (default zone 0)\npython scripts/hive_control.py --zone 1 set-temp 20\n```\n\nRequires `HIVE_USERNAME`, `HIVE_PASSWORD`; for non-interactive use (e.g. agent runs) set `HIVE_DEVICE_GROUP_KEY`, `HIVE_DEVICE_KEY`, `HIVE_DEVICE_PASSWORD` after one interactive first-time login.\n\n## Credentials\n\n**Required env vars:** `HIVE_USERNAME`, `HIVE_PASSWORD`. For automation (no 2FA each run): `HIVE_DEVICE_GROUP_KEY`, `HIVE_DEVICE_KEY`, `HIVE_DEVICE_PASSWORD`.\n\n**Where to set them:**\n- **Generic / Cursor / CLI:** Set in your shell (`export HIVE_USERNAME=...`) or in a local `.env` file that is **not committed**. Run the script in an environment where these are set.\n- **OpenClaw:** Set in `~/.openclaw/openclaw.json` under `skills.entries.hivehome.env`. OpenClaw injects these into the process for the agent run; they are not put in prompts or logs.\n- **Other agents:** Use that agent’s recommended way to inject env vars or secrets so the skill’s scripts see them at runtime.\n\n**Agent instruction:** If credentials are missing, do not ask the user to paste passwords or keys in chat. Tell them to set the required environment variables (or configure the skill in their agent’s config) and run the script again. See [references/CREDENTIALS.md](references/CREDENTIALS.md) for platform-specific notes.\n\n## When to use this skill\n\n- User asks to control Hive heating, thermostat, or hot water.\n- User wants to script or automate Hive devices (heating, lights, plugs).\n- User mentions Hive, British Gas Hive, or the Hive app in the context of automation or code.\n\n## Prerequisites\n\n- **Python 3** with **pyhiveapi>=1.0.0** (session API): `pip install \"pyhiveapi>=1.0.0\"`. If you see attribute or method errors, run `pip install -U pyhiveapi` and try again.\n- **Hive account** (UK; my.hivehome.com). First-time login requires **SMS 2FA**; subsequent logins can use device credentials to avoid 2FA.\n\n## Authentication\n\n### First-time login (username + password + 2FA)\n\nHive enforces two-factor authentication. After initial login, capture **device credentials** for future runs so the user does not need to enter a 2FA code every time.\n\n```python\nimport os\nfrom pyhiveapi import Hive, SMS_REQUIRED\n\nusername = os.environ.get(\"HIVE_USERNAME\")\npassword = os.environ.get(\"HIVE_PASSWORD\")\nif not username or not password:\n    raise SystemExit(\"Set HIVE_USERNAME and HIVE_PASSWORD\")\n\nsession = Hive(username=username, password=password)\nlogin = session.login()\n\nif login.get(\"ChallengeName\") == SMS_REQUIRED:\n    code = input(\"Enter 2FA code from SMS: \")\n    session.sms2fa(code, login)\n\n# Save these for next time (e.g. to env or a secure store)\ndevice_data = session.auth.getDeviceData()\nprint(\"Store for device login:\", device_data)\n\nsession.startSession()\n# Now use session.heating, session.hotwater, session.light, etc.\n```\n\n### Device login (no 2FA after first time)\n\nUse after the user has run first-time login and stored device credentials. Set `HIVE_DEVICE_GROUP_KEY`, `HIVE_DEVICE_KEY`, `HIVE_DEVICE_PASSWORD` (or pass them another secure way).\n\n```python\nimport os\nfrom pyhiveapi import Hive\n\nsession = Hive(\n    username=os.environ[\"HIVE_USERNAME\"],\n    password=os.environ[\"HIVE_PASSWORD\"],\n    deviceGroupKey=os.environ[\"HIVE_DEVICE_GROUP_KEY\"],\n    deviceKey=os.environ[\"HIVE_DEVICE_KEY\"],\n    devicePassword=os.environ[\"HIVE_DEVICE_PASSWORD\"],\n)\nsession.deviceLogin()\nsession.startSession()\n```\n\n## Device lists\n\nAfter `session.startSession()`, devices are in `session.deviceList` by type:\n\n```python\nheating = session.deviceList[\"climate\"]\nwater_heaters = session.deviceList[\"water_heater\"]\nlights = session.deviceList[\"light\"]\nswitches = session.deviceList[\"switch\"]\nsensors = session.deviceList[\"sensor\"]\nbinary_sensors = session.deviceList[\"binary_sensor\"]\n```\n\nUse the first (or chosen) device when calling the methods below.\n\n## Heating (thermostat)\n\n```python\nif heating:\n    zone = heating[0]\n    # Read\n    session.heating.getMode(zone)\n    session.heating.getState(zone)\n    session.heating.getCurrentTemperature(zone)\n    session.heating.getTargetTemperature(zone)\n    session.heating.getBoostStatus(zone)\n    session.heating.getBoostTime(zone)\n    session.heating.getOperationModes()  # e.g. SCHEDULE, HEAT, OFF\n\n    # Write\n    session.heating.setMode(zone, \"SCHEDULE\")\n    session.heating.setMode(zone, \"HEAT\")\n    session.heating.setTargetTemperature(zone, 21)\n    session.heating.setBoostOn(zone, 30, 21)   # 30 min at 21°C\n    session.heating.setBoostOff(zone)\n```\n\n## Hot water\n\n```python\nif water_heaters:\n    hw = water_heaters[0]\n    session.hotwater.getMode(hw)\n    session.hotwater.getState(hw)\n    session.hotwater.getBoost(hw)\n    session.hotwater.setMode(hw, \"OFF\")\n    session.hotwater.setMode(hw, \"SCHEDULE\")\n    session.hotwater.setBoostOn(hw, 30)\n    session.hotwater.setBoostOff(hw)\n```\n\n## Lights\n\n```python\nif lights:\n    light = lights[0]\n    session.light.getState(light)\n    session.light.getBrightness(light)\n    session.light.getColorTemp(light)\n    session.light.getColor(light)\n    # Set state (exact method names depend on pyhiveapi version; see reference)\n```\n\n## Quick reference\n\n- **Modes (heating):** `SCHEDULE`, `HEAT`, `OFF` (and others per `getOperationModes()`).\n- **Temperatures:** Use integers (e.g. `21` for 21°C). Check `session.heating.getMinTemperature(zone)` / `session.heating.getMaxTemperature(zone)` for limits.\n- **Boost:** Heating boost takes (minutes, target_temp); hot water boost takes (minutes) only.\n\n## Additional resources\n\n- Full API surface, auth flow diagram and links: [references/REFERENCE.md](references/REFERENCE.md)\n- Pyhiveapi: [GitHub](https://github.com/Pyhass/Pyhiveapi), [Session examples](https://pyhass.github.io/pyhiveapi.docs/docs/examples/session/)\n- Home Assistant Hive integration (same backend): [home-assistant.io/integrations/hive](https://www.home-assistant.io/integrations/hive/)\n\n## External endpoints\n\nThis skill ships **scripts** (`scripts/hive_control.py`) that call the **Pyhiveapi** Python library. The agent should run these scripts for common actions. When the user needs unsupported behaviour (e.g. lights), the agent may generate Pyhiveapi code. In all cases, only the following endpoints are used. No direct HTTP is made from the skill; Pyhiveapi encapsulates it.\n\n| Purpose | Endpoint / host | Data sent |\n|--------|------------------|-----------|\n| Login (first time) | `beekeeper.hivehome.com` / `api.prod.bgchprod.info` (via Pyhiveapi) | Hive username, password; after 2FA, device registration |\n| Device login | Same | Username, password, device group key, device key, device password |\n| Device control (heating, hot water, lights, etc.) | Same | Session token; device IDs and command payloads (e.g. target temperature, mode) |\n\nCredentials and 2FA codes must be supplied via environment variables or user input; the skill never contains or logs them. The bundled script includes a SECURITY MANIFEST header (env vars and endpoints used).\n\n## Security and privacy\n\n- **What leaves the machine:** Hive account credentials (username, password, and optionally device keys) and API requests (device state, setpoints, mode changes) are sent to Hive’s backend (Centrica/British Gas). The skill does not send data elsewhere.\n- **What stays local:** Credentials should be stored only in the user’s environment or secret store; the skill instructs the agent never to hardcode or log them.\n- **Autonomous invocation:** When this skill is enabled, the agent may suggest or generate code that calls the Hive API when the user asks about heating, thermostats, or Hive. The user controls whether to run that code and what credentials to provide.\n\n## Trust statement\n\nBy using this skill, you send your Hive account credentials and device commands to Hive’s servers (beekeeper.hivehome.com / api.prod.bgchprod.info). Only install and use this skill if you trust that infrastructure and the Pyhiveapi library. This skill is not affiliated with Hive or British Gas.\n","tags":{"latest":"1.0.1","latest home heating smart thermostat heating boiler":"1.0.0"},"stats":{"comments":0,"downloads":607,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":2},"createdAt":1773186483081,"updatedAt":1778491816516},"latestVersion":{"version":"1.0.1","createdAt":1773189979754,"changelog":"Hivehome 1.0.1\n\n- Updated code examples and quick reference for heating to use new pyhiveapi method names (e.g. getCurrentTemperature, getTargetTemperature, getBoostStatus, setBoostOn).\n- Updated temperature limit references to use getMinTemperature and getMaxTemperature methods.\n- No functional or code changes; documentation only.","license":"MIT-0"},"metadata":{"setup":[{"key":"HIVE_USERNAME","required":true},{"key":"HIVE_PASSWORD","required":true}],"os":null,"systems":null},"owner":{"handle":"m0nkmaster","userId":"s177rkwg2hry4pdmperpeqa76x83r5wt","displayName":"Rob MacDonald","image":"https://avatars.githubusercontent.com/u/1137937?v=4"},"moderation":null}