Yeelight AI CLI

简体中文

Caution

Archived historical implementation. Do not install or use yeelight-ai for a new setup. Its supported consumer capabilities have moved to yeelight-home, the single current CLI, sign-in entry, local Runtime, MCP setup tool, and Cloud/LAN workbench. This directory remains only as migration history and is not published or used by either Yeelight MCP service.

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-ai is the official command-line workspace for Yeelight Cloud, Metadata, and LAN MCP services. It provides one installation, one local profile, safe device shortcuts, MCP discovery and invocation, diagnostics, and client configuration for Cursor, Claude Desktop, and VS Code.

Yeelight AI Capability Matrix

These projects form a complementary stack. Choose the entry point that matches how you integrate with Yeelight; they can also be combined.

Project	Role and capabilities	Best for	GitHub
Yeelight Home	Recommended local semantic Runtime with one structured invoke --stdin boundary for queries, control, scenes, automations, lighting design, diagnostics, product knowledge, and generated apps.	Agent hosts, local automation, and applications that need a stable and policy-aware smart-home execution layer.	Yeelight/yeelight-home
Yeelight Smart Home Skills	Official Agent Skills: Smart Home turns natural language into safe Runtime operations; PRO App Builder generates focused local apps from proven Runtime capabilities.	Agent hosts that need conversational smart-home workflows or app generation.	Yeelight/yeelight-smart-home-skills
Yeelight AI CLI	Unified terminal workspace and MCP client for Cloud, Metadata, and LAN services, with local profiles, safe shortcuts, diagnostics, scripting, and AI client configuration.	People, scripts, and CI that want one general MCP and automation entry point.	Yeelight/yeelight-cli
Yeelight Metadata MCP	Recommended cloud MCP entry for new integrations, with guarded workflows for homes, rooms, devices, groups, panels, scenes, automations, favorites, maintenance, accounts, multi-region authorization, and request-scoped home selection.	New MCP integrations and AI clients that need broad discovery, inspection, and management workflows.	Yeelight/yeelight-metadata-mcp
Yeelight IoT MCP	Focused companion MCP for direct topology and live-state access, device control, and scene execution not yet fully covered by Metadata MCP.	Existing integrations or clients that specifically need control_node, execute_scene, or focused live control.	Yeelight/yeelight-iot-mcp

Yeelight Home also provides system credential storage, local QR login, secret-redacted diagnostics, preview and validation, caller confirmation and Runtime policy/readback behavior, local memory and recommendation support, operation lessons, and machine-readable intent schema/explanations. Cross-platform binaries are distributed through GitHub Releases, npm, and supported package managers.

Typical paths: smart-home agents and generated apps -> Skills -> Yeelight Home; terminal users and scripts -> Yeelight AI CLI; new MCP integrations -> Metadata MCP; add IoT MCP only for focused direct control or scene execution that Metadata MCP does not yet cover.

Requirements

• Node.js 20 or later
• A Yeelight account for Cloud and Metadata MCP
• A reachable Yeelight gateway with LAN CONTROL enabled for LAN MCP

Install

npm install --global yeelight-ai
yeelight-ai --version
yeelight-ai --help

If npm is slow or unreachable in mainland China, use npmmirror for this one installation without changing the global registry:

npm install --global yeelight-ai --registry=https://registry.npmmirror.com
npm config get registry

If you previously changed the global registry, restore the official source with npm config set registry https://registry.npmjs.org/.

To run from a source checkout:

git clone https://github.com/Yeelight/yeelight-cli.git
cd yeelight-cli
npm install
npm test
node bin/yeelight-ai.js --help

Quick Start

Start the interactive workspace:

yeelight-ai

The CLI checks the local profile, resolves the account Region, and guides you through QR login when required. In Yeelight Pro APP, tap the + button in the top-right corner of Home, choose MCP Authorization, then scan the terminal QR code. Login defaults to consumer Pro homes (bizType=0); commercial-lighting projects are queried only when bizType=1 is selected explicitly. Manual token entry remains available for recovery and non-interactive environments.

Figure 1: Yeelight Pro APP Home -> top-right + -> MCP Authorization

The workspace shows the selected home, Cloud and Metadata endpoints, and a recommended next action. Its menus accept both numbers and semantic aliases such as devices, doctor, tools, switch, and back.

For scripts and CI, use explicit commands and JSON output:

yeelight-ai doctor --json
yeelight-ai status --json
yeelight-ai mcp list --json

Common Commands

Read-only home commands:

yeelight-ai house show
yeelight-ai room list
yeelight-ai device list
yeelight-ai device show <deviceId>
yeelight-ai scene list

Device and scene writes are previews by default. Add --yes only after the target and action have been reviewed:

yeelight-ai light brightness <deviceId> 80
yeelight-ai light brightness <deviceId> 80 --yes
yeelight-ai scene run <sceneId>
yeelight-ai scene run <sceneId> --yes

If Cloud MCP initialization returns HTTP 421, read-only shortcuts automatically fall back to the Yeelight OpenAPI and identify the data source. Cloud and Metadata MCP can be switched between local, remote, or explicit endpoints:

yeelight-ai mcp configure cloud --local
yeelight-ai mcp configure cloud --remote
yeelight-ai mcp configure cloud --endpoint http://127.0.0.1:9000/mcp
yeelight-ai mcp configure metadata --local
yeelight-ai mcp configure metadata --remote

Login And Home Selection

Running yeelight-ai is normally enough. To explicitly log in, switch home, select a business type, or support app integration, use:

yeelight-ai login
yeelight-ai login --qr --region cn --biz-type 0
yeelight-ai login --qr --client-device-id cli-debug-1 --no-wait --json
yeelight-ai login --authorization <token> --region eu --house-id <houseId>
yeelight-ai login --authorization <token> --region cn --biz-type 1
yeelight-ai login --manual

The QR payload has the form cli&clientDeviceId&qrCodeId. When no device ID is supplied, the CLI generates and persists a cli_... identifier for later logins; an explicit value applies only to that invocation. Region resolution is --region -> YEELIGHT_CLOUD_REGION -> saved profile -> cn. Cloud and Metadata requests receive Authorization, Yeelight-Region, optional House-Id, and bizType; users do not configure a Client ID.

MCP Tool Invocation

Discover and invoke MCP tools:

yeelight-ai mcp tools cloud
yeelight-ai mcp describe cloud get_devices
yeelight-ai mcp call cloud get_devices --args '{}' --json

yeelight-ai mcp groups metadata
yeelight-ai mcp describe metadata yeelight_metadata.execute_task
yeelight-ai mcp call metadata yeelight_metadata.list_tasks --args '{}' --json

MCP Services

ID	Purpose	Authentication
cloud	Device and scene reads and controls	Local Yeelight profile headers
metadata	Home, room, group, scene, automation, and configuration tasks	Local Yeelight profile headers
lan	Gateway-local discovery and control	Local network; no cloud headers

Metadata tool definitions are available locally for fast discovery. Use --remote when you explicitly need to compare them with the live service. LAN tool names and schemas always come from the gateway at runtime.

Tool listings support MCP cursor pagination through --cursor, --limit, and --all. JSON listings are compact by default; add --raw for complete schemas. Tool calls similarly support --data-only for full business data without the MCP envelope and --raw for protocol diagnostics. Interactive tool sessions stay on the selected MCP so multiple calls can be made; use switch to change services and back or 0 to return.

Credentials And Safety

• Configuration is stored under ~/.config/yeelight-ai/config.json on macOS/Linux or %APPDATA%/yeelight-ai/config.json on Windows.
• Override the directory with YEELIGHT_AI_CONFIG_DIR for tests or isolation.
• config get and doctor --json redact credentials by default.
• Do not paste tokens, passwords, home IDs, device names, or gateway addresses into issues or chat transcripts.
• Use mcp describe before raw tool calls. Preview writes first and verify state after any confirmed write.

Client Configuration

Preview a client configuration before writing it:

yeelight-ai client configure cursor --json
yeelight-ai client configure claude --json
yeelight-ai client configure vscode --json

Use --write --yes to merge the generated MCP servers into an existing client configuration. Existing unrelated servers are preserved.

Documentation

• Integration guide
• Usage and source guide
• 中文接入指南
• 中文使用与源码指南

Development

npm test
npm run smoke
npm pack --dry-run --json

The package contains only the public runtime, QR login implementation, bilingual documentation, guides, and license. Internal release and security tooling remain outside the npm tarball.

License

Apache License 2.0. See LICENSE.