Use this command to install Yeelight Home with WinGet:
winget install --id=Yeelight.yeelight-home -e
Yeelight Home is a CLI tool designed to execute smart-home automation skills locally on user machines, enabling seamless control over Yeelight devices through a command-line interface. This software empowers users by running locally, handling credentials securely, and integrating with Yeelight's cloud services via MCP for comprehensive device management.
Key Features:
Local Execution: Runs smart-home automation scripts directly on your machine, ensuring quick response times and reduced dependency on external servers.
Comprehensive Device Support: Manages a wide range of Yeelight devices, including lights, sensors, and gateways, providing unified control across your smart-home ecosystem.
Secure Credential Management: Stores access tokens securely using system credential stores or local fallbacks, ensuring safe and efficient authorization.
MCP Integration: Connects to Yeelight's cloud services via MCP, allowing lightweight connections for AI clients that cannot install Skills directly.
Target Audience and Benefits:
Ideal for developers and smart-home enthusiasts aiming to streamline automation workflows. Yeelight Home offers a robust platform for creating, testing, and deploying smart-home solutions, enhancing productivity and user experience.
Available via Winget, you can easily install or deploy this tool using the winget command line, making setup straightforward and efficient.
README
yeelight-home
Default language: English. Chinese documentation is available in README.zh-CN.md.
Official Repository And Mirrors
GitHub is the canonical source for
issues, contributions, CI, and releases. Read-only mirrors are available on
Gitee and
GitCode for users who cannot reach
GitHub reliably, with GitLab.com as
an additional global fallback. Clone from any reachable source, but report
issues and contribute changes on GitHub.
yeelight-home is the standalone local Runtime CLI for Yeelight smart-home Skills and automation scripts. It runs on the user's machine, keeps credentials local, resolves smart-home requests, executes supported Yeelight home capabilities, and returns redacted structured results.
The Runtime is intentionally not bundled inside Skills. A Skill finds yeelight-home through YEELIGHT_HOME_BIN or PATH and sends JSON requests to yeelight-home invoke --stdin. One-shot mode reads one request and returns one response; --keep-alive keeps the Runtime process and LAN session open, accepts one JSON request per input line, and returns one response line per request.
Official Step-by-Step Tutorial
New to Yeelight Home? Follow the official English tutorial from computer setup and installation through QR sign-in, home selection, and the first verified response. A Simplified Chinese tutorial is also available.
The Ecosystem In Plain Language
You only install one foundation: Yeelight Home. The other projects are
different ways for an AI to use Yeelight, not competing replacements.
Term
Plain-language meaning
Yeelight project
Depends on
CLI / Runtime
The Yeelight program on your computer. It signs in, knows the selected home, performs checked operations, and can also be used directly by people or scripts.
yeelight-home
Nothing else in this matrix
Skill
A Yeelight playbook for an AI: home rules, lighting knowledge, safe operating steps, and best practices.
A standard cloud connection for AI clients that cannot install Skills. One Yeelight MCP setup includes home understanding, management, live state, and control.
yeelight-metadata-mcp + yeelight-iot-mcp
Configured together by yeelight-home; neither cloud service depends on the Runtime to execute requests
Recommended for most people: install Yeelight Home, then let setup add the
Smart Home Skill. Choose MCP only when your AI client cannot install Skills.
Use the CLI workbench directly when you are scripting, troubleshooting, or
deliberately working from a terminal.
Three Paths, One CLI
Users do not need to learn CLI, Skill, and MCP terminology first. Install yeelight-home, then choose an outcome:
Path
What you get
Best for
Full intelligence (recommended)
The yeelight-smart-home Skill brings Yeelight home rules, lighting knowledge, and safety boundaries, then executes through yeelight-home.
People who want to control, manage, and design their home in everyday language.
Lightweight connection
One yeelight-home setup --mode mcp --mcp-source cloud flow configures the complete Yeelight MCP cloud suite through credential proxies, without placing Authorization in client configuration.
MCP clients that cannot install Agent Skills.
CLI workbench
Select homes, rooms, devices, and scenes by name, or use stable resource commands and invoke --stdin.
Advanced users, scripts, CI, and troubleshooting.
The setup paths share one local profile and Yeelight Pro app QR sign-in. The Skill and local MCP execute through the Runtime; cloud Yeelight MCP connects directly to the Yeelight PRO cloud through two independently deployed services. Cloud and home-gateway LAN remain distinct execution routes, not competing products.
Features
Yeelight home capabilities for homes, rooms, areas, devices, groups, gateways, scenes, automations, diagnostics, lighting design, product knowledge, memory, and personalization.
Product pedia search for fuzzy product lookup, product codes, product metadata, attachment records, and candidate manual or FAQ resource URLs.
Thin execution model for persistent changes: supported writes execute directly after Runtime validation; callers own any user confirmation and can use dry-run previews when needed.
Local credential handling: access tokens are stored in the system credential store when available, with a protected local fallback.
Multiple profiles for different accounts, regions, or homes.
Region-aware cloud endpoints with default region cn.
Redacted JSON output for Skill hosts and diagnostics.
Local preference memory and recommendation feedback stored under the Runtime data directory, not in Skill prompts.
Human-friendly resource commands plus a stable invoke --stdin contract for Skills and generated apps.
yeelight-home setup checks the current account, keeps it by default, or lets an interactive user scan again to switch accounts; it then installs the selected Skill/MCP clients and completes read-only verification in Chinese or English. MCP setup supports automatic detection, multiple clients, and every verified adapter.
A TTY with no arguments opens the interactive workbench; yeelight-home menu opens it explicitly, while non-TTY no-argument behavior remains deterministic help output.
yeelight-home mcp serve --stdio exposes the same Runtime to local MCP clients without saving Yeelight Authorization in client configuration.
cloud, local-preferred, and local-only choose between Cloud and home-gateway LAN safely; an uncertain LAN write never triggers a blind Cloud retry.
Cross-platform distribution through the GoReleaser-backed GitHub Releases pipeline, with Homebrew, Scoop, npm, Linux packages, and optional container/package-manager channels.
Optional Docker/GHCR and Docker Hub images for NAS, server, and scheduled automation use.
product.pedia.search, manuals and FAQ candidates, thing-model schema and product definitions
Diagnostics
gateway/device diagnostics, upgrade files, operation progress, install and credential checks
Local intelligence
local preference memory, recommendation list, recommendation feedback and cooldown
Reads execute immediately. Persistent writes and deletes also execute after Runtime validation; use --dry-run, --preview-only, or options.dryRun=true only when the caller wants a no-write preview before its own user confirmation.
Install
macOS and Linux:
curl -fsSL https://github.com/Yeelight/yeelight-home/releases/latest/download/install.sh | sh
In mainland China, npmmirror can accelerate the npm package download for a
single installation:
npm install -g yeelight-home --registry=https://registry.npmmirror.com
npm config get registry
Restore a previously changed global registry with
npm config set registry https://registry.npmjs.org/. The npm wrapper verifies
the platform binary against checksums.txt; for the official repository it
tries GitHub first, then the official Gitee and GitCode Release mirrors.
Debian, Ubuntu, Fedora, Arch, AUR, Snap, Docker, GHCR, Docker Hub, and Winget channel details are maintained in INSTALL.md and DISTRIBUTION.md.
AI-Assisted Install
If you use a local AI assistant that can run terminal commands, paste this single request:
Install `yeelight-home` from an official Yeelight GitHub Release, official mirror, or supported package manager. Then run `yeelight-home setup --lang en-US`, prefer Full intelligence, guide me to Yeelight Pro app Home -> top-right `+` -> MCP Authorization, and wait for my scan. Never request or print a token, password, cookie, Client ID, or QR result. Finish with `yeelight-home doctor --json` and read-only home discovery.
Quick Start
yeelight-home setup --lang en-US
yeelight-home setup --lang en-US --mode skill --agent auto --yes
yeelight-home setup --lang en-US --mode mcp --agent auto --yes
yeelight-home menu
yeelight-home version
yeelight-home doctor
yeelight-home doctor --json
yeelight-home auth status --json
yeelight-home auth login --qr
yeelight-home home list --json
# Optional: choose a default home before house-scoped device, room, scene, or automation operations.
yeelight-home home select --lang en-US
yeelight-home device list --json
yeelight-home product search --multi-field 青空灯 --json
yeelight-home scene execute --scene-id --json
yeelight-home light on --device-id --json
yeelight-home automation enable --automation-id --json
When interactive setup finds an authenticated account, press Enter (or choose 1) to keep it, or choose 2 to scan again and switch accounts. A successful switch selects a home from the new account; a failed scan keeps the previous credential and home. Non-interactive --yes always keeps the current account.
LAN-preferred setup:
yeelight-home setup --lang en-US --mode lan --gateway-ip 192.168.1.2 --agent auto --yes
yeelight-home lan inspect --json
yeelight-home config set --control-mode local-only --gateway-ip 192.168.1.2
MCP clients start the unified local Runtime through yeelight-home mcp serve --stdio by default. Use --mcp-source cloud or --mcp-source gateway only for explicit advanced compatibility needs. Cloud MCP setup stores only local yeelight-home mcp proxy launch arguments in the AI client; the proxy reads Authorization from the local credential store at runtime, so the token is not copied into client configuration.
The default region is cn. Pass --region sg, --region us, or --region eu when your Yeelight account belongs to another cloud region.
Ordinary Yeelight Pro homes are the default (bizType=0). For a commercial-lighting project, run yeelight-home setup --lang en-US --biz-type 1 or add --biz-type 1 to auth login and home list. Switching the business type clears the previously selected home unless you explicitly select a project from the new type, so a consumer House ID is never reused as a commercial project ID.
For non-interactive local setup, import a token outside chat. Prefer --stdin in real shells so the token is not saved in shell history:
printf '%s' "$YEELIGHT_TOKEN" | yeelight-home auth token set --stdin --region cn
printf '%s' "$YEELIGHT_DEV_TOKEN" | yeelight-home auth token set --stdin --profile dev --region dev --json
Token-only setup is valid. houseId is optional profile metadata for the default home. In other words, houseId is optional until you run a house-scoped command. Account-level commands such as auth status, doctor, api smoke, home list, home.summary, home.search, and account.info do not require it. House-scoped operations such as device, room, scene, group, gateway, favorite, and automation actions require a houseId from the request, YEELIGHT_HOME_HOUSE_ID, or the selected profile.
Do not paste tokens into AI chat. The CLI stores tokens locally and never prints token values in normal status or doctor output.
Configuration Model
Runtime settings are resolved in this order:
Command flags.
Environment variables.
Active profile metadata and credential store.
Defaults.
Default values:
Profile: default
Region: cn
Business type: 0 (ordinary Yeelight Pro home); use 1 for commercial-lighting projects
Home: unset until selected, and only required for house-scoped operations
Common environment variables:
Variable
Purpose
YEELIGHT_HOME_BIN
Absolute path used by Skills to find the CLI.
YEELIGHT_HOME_PROFILE
Selects a profile for this process.
YEELIGHT_CLOUD_REGION
Overrides region for this process: cn, sg, us, eu, or dev for development.
YEELIGHT_HOME_BIZ_TYPE
Selects ordinary homes (0) or commercial-lighting projects (1) for this process.
YEELIGHT_HOME_HOUSE_ID
Temporarily overrides selected home.
YEELIGHT_HOME_ACCESS_TOKEN
Temporary token for local smoke tests or CI; not written to profile metadata.
YEELIGHT_HOME_DIR
Overrides Runtime home directory.
YEELIGHT_API_BASE_URL
Developer-only API base URL override. Do not use in Skill prompts or user automation.
See CONFIG.md for full command and precedence details.
Command Reference
Human Commands Versus invoke
invoke --stdin is the stable machine contract for Skills, generated apps, and automation hosts. In one-shot mode it accepts one SkillRequest JSON object and returns one SkillResponse JSON object. With --keep-alive, it accepts newline-delimited SkillRequest objects and emits one newline-delimited SkillResponse for each request while reusing the Runtime process and LAN session. It also accepts --profile, --region, and --house-id for context overrides.
Human operators should usually use resource commands:
yeelight-home device list --json
yeelight-home room list --json
yeelight-home scene execute --scene-id --json
yeelight-home light brightness --device-id --brightness 60 --json
yeelight-home automation enable --automation-id --json
The resource commands are thin wrappers around Runtime intents. They keep the same profile, region, credential, redaction, preflight, direct execution, dry-run preview, and verification rules as invoke.
Common resources include home, room, area, device, entity, gateway, group, scene, automation, light, lighting, favorite, panel, knob, sensor, thing, upgrade, memory, recommendation, and account. Run yeelight-home --help for the full resource list.
Use yeelight-home help to list actions, and yeelight-home help for action-specific flags. Examples:
yeelight-home help device
yeelight-home help scene execute
yeelight-home help light brightness
For machine-readable intent contracts, use intent schema or the explain shortcut:
These commands are offline. They print the SkillRequest envelope, accepted parameter keys, nested payload shape, examples, and nextStep hints so Skills and traditional programs do not need to guess large JSON fields such as lighting design models, scene actions[], automation trigger / conditions / actions[], panel button events, or batch operations.
For uncommon fields, pass advanced parameters through the documented request contract:
product search returns redacted product metadata such as product name, brand, model, SKU/SPU, category/class fields, product code, support markers, status, attachments, and candidate manual or FAQ resource URLs when they can be derived safely. Product knowledge explains what a product is; it does not prove that a matching device is installed in a user's home. Use entity capabilities, device detail, or state query for installed-device truth.
Local Memory And Recommendations
yeelight-home memory remember --house-id --set scopeType=room,scopeRef=客厅,preferenceType=brightness,preferenceValue=45 --json
yeelight-home memory remember --house-id --params-json '{"preferences":[{"scopeType":"profile","preferenceType":"ambience","preferenceValue":"prefer_romantic_warm","evidence":"user explicitly asked to remember romantic ambience"},{"scopeType":"profile","preferenceType":"product_preference","preferenceValue":"prefer_premium_luxury","evidence":"user explicitly asked to remember premium product positioning"}]}' --json
yeelight-home recommendation record --house-id --params-json '{"type":"automation","source":"ai_skill","targetIntent":"automation.create","scopeType":"room","scopeRef":"主卧","explanation":"Create a warm evening automation from the saved romantic ambience preference.","evidence":"Saved memory ambience=prefer_romantic_warm"}' --json
yeelight-home recommendation list --house-id --json
yeelight-home recommendation feedback --params-json '{"recommendationId":"","feedback":"cooldown","cooldownHours":24}' --json
Local memory and recommendations are enabled by default for every profile + region + houseId scope. memory pause is the explicit opt-out switch, and memory resume turns local learning back on. memory remember directly upserts one structured local preference or multiple structured preferences in parameters.preferences[]. recommendation record directly upserts a caller-authored structured candidate; the Runtime only validates, stores, deduplicates, ranks, lists, and records feedback. Recommendation judgment belongs to the caller/Skill, not the Runtime. Feedback such as accepted, dismissed, rejected, or cooldown is stored locally and respected by later recommendation reads.
The Runtime does not store full conversation logs as memory and does not interpret subjective natural-language preferences. Callers such as Skills must pass structured fields such as scopeType, scopeRef, preferenceType, preferenceValue, and evidence. If callers want "warm soft light" and "warmer" to be the same memory, they should pass the same canonical preferenceValue; Runtime then merges exact same structured preferences and evidence instead of duplicating them.
The JSON store is sharded under ~/.yeelight-home/data/memory///.json. Each shard and export carries namespace metadata with accountProfile, profile, region, houseId, and dataType. Interaction signals are coarse counters with intent and response status evidence only; user utterances are not stored as signal evidence. Accepted, dismissed, or rejected recommendation evidence and interaction signals are compacted after the local retention window, while explicit preferences remain until the user forgets them.
doctor
yeelight-home doctor [--json] [--online] [--profile ] [--region ] [--house-id ]
Reports installation, config directories, selected profile, selected region, selected home, token presence, and warnings. Without --json, it prints a human-readable diagnostic summary. With --json, it prints the machine-readable diagnostic object. Token values are never printed.
The selected home may be empty; that is healthy for token-only account-level use.
The install object includes the running CLI version, executable path, PATH lookup result, OS, architecture, and npm wrapper path when launched through the npm package. If path_lookup_differs_from_running_executable appears, a shell, package manager, or Skill host is resolving a different yeelight-home binary than the one currently being inspected.
It also includes packageManagers.npm and packageManagers.homebrew when those tools are available. Homebrew diagnostics include separate formula and cask entries so PATH drift can be traced to the exact channel. Use those fields to find stale npm wrappers, Homebrew formula installs, or Homebrew cask installs that differ from the Runtime binary on PATH.
When launched by the npm wrapper, doctor --json reports install.npmWrapper and install.npmWrapperResolved. npm_wrapper_differs_from_path_lookup means the running wrapper is not the same file that the current shell would resolve from PATH; restart the host shell or remove the stale channel.
Text output includes Install source summary to make the active PATH channel and installed npm/Homebrew versions visible without parsing JSON.
Pass --online when you want doctor to query the public GitHub Release, npm registry, and Yeelight Homebrew tap latest versions. This is intentionally opt-in so default diagnostics stay fast and offline-friendly. A single online channel with ok=false means that channel could not be checked; other successful channel results and local warnings remain useful.
The install.remediations array and the text-mode Suggested fixes section provide safe next commands for the detected local install shape.
version
yeelight-home version
yeelight-home version --json
version --json reports build metadata: version, commit, build date, OS, and architecture.
auth status
yeelight-home auth status [--json] [--profile ] [--region ] [--house-id ]
Reports whether the selected profile has a usable local credential.
Without --json, it prints a human-readable summary. With --json, it prints the machine-readable status object.
Starts the local QR login flow. If --region is omitted, cn is used.
--house-id is optional and should be used only when a home context must be carried into the login payload.
Imports a token into the local credential store. It never writes the token into the profile metadata file.
Prefer --stdin in real shells to avoid saving secrets in command history.
--house-id is optional. Omit it when you only need account-level commands or plan to select a home later.
Profiles isolate account metadata and selected home. Use YEELIGHT_HOME_PROFILE or --profile for temporary selection.
The selected home can be empty in a profile.
Prints a shell completion script to stdout. Install it using the standard mechanism for your shell.
home
yeelight-home home list [--profile ] [--region ] [--json]
yeelight-home home select [--house-id ] [--profile ] [--region ] [--biz-type <0|1>] [--lang ] [--json]
Lists homes available to the selected credential and stores the default home for later Skill calls.
Run home select --lang en-US in an interactive terminal to choose by number or complete home name. Automation can pass --house-id directly. Use it only when you want future house-scoped commands to use a default home; a one-time --house-id or YEELIGHT_HOME_HOUSE_ID remains available.
Reads a SkillRequest JSON object from stdin and writes a SkillResponse JSON object to stdout. Add --keep-alive to process newline-delimited requests on a persistent process and receive one response line for each request. This is the only command Skills should call for smart-home operations.
Flag overrides are applied before request parameters are resolved; request parameters.region and parameters.houseId still work when the corresponding flag is omitted.
Interactive users do not need to hand-write SkillRequest JSON for common operations. Prefer resource commands such as device list, scene execute, light on, room create, and automation enable.
api smoke
yeelight-home api smoke [--json] [--profile ] [--region ] [--house-id ]
Runs a local cloud smoke check using the selected credential. This is intended for installation and support diagnostics.
Without --json, it prints a human-readable summary. With --json, it prints account and home-list check details for support automation.
Skill Integration
Skill wrapper lookup order:
YEELIGHT_HOME_BIN
yeelight-home on PATH
Published Skill packages do not carry or auto-discover Runtime source-tree
binaries. Use YEELIGHT_HOME_BIN for a deliberate local override, or install
the public CLI so it is available on PATH.
When the Runtime is missing, install it from a published public channel, then run:
yeelight-home auth status --json
yeelight-home auth login --qr
yeelight-home home list --json
If QR login is unavailable and the user already has an authorized token, import it locally outside chat:
Skills must use yeelight-home commands instead of URLs, headers, curl, third-party services, or token-bearing commands.
Release And Packaging
yeelight-home is maintained directly in the monorepo's top-level yeelight-home/ directory and published from the same self-contained project to Yeelight/yeelight-home. The legacy yeelight-smart-home/runtime directory is not retained.
The public runtime release pipeline uses GoReleaser from Yeelight/yeelight-home. The monorepo mirror workflow only validates and exports runtime source; it no longer builds or publishes CLI binaries.
One tagged public v* release can produce:
macOS, Linux, Windows archives for amd64, arm64, and Linux armv7.
Checksums and release metadata.
Homebrew tap Formula and Cask automation.
Scoop bucket manifest.
Linux packages through nFPM: .deb, .rpm, .apk, and Arch package artifacts.
Docker/GHCR and Docker Hub multi-arch images.
Snap and AUR artifacts or publication when required credentials are configured.
Winget manifest or PR flow when the Windows package route is enabled.
Yeelight/homebrew-tap and Yeelight/scoop-bucket remain standard package-manager metadata repositories. They should be updated by GoReleaser, not used as Runtime source repositories.
Do not paste tokens, passwords, or account secrets into AI chat.
auth status, doctor, and invoke responses are redacted.
Profile metadata contains non-secret values such as profile name, region, selected home, and QR device identity. Tokens stay in credential storage.
Persistent writes use supported Runtime intents; the model cannot execute arbitrary low-level payloads. Callers own user confirmation for high-impact operations.