yeelight-home 0.1.8 → 0.1.9

package/CONFIG.md

@@ -111,6 +111,47 @@ yeelight-home home select --profile family --house-id <house-id> --region cn
 `home select` writes the selected home id into profile metadata. A process can temporarily override it with `--house-id` or `YEELIGHT_HOME_HOUSE_ID`.
 The selected home is a default context, not an authentication requirement. Account-level commands such as `auth status`, `doctor`, `api smoke`, `home list`, home summary/search, and account info work with token-only profiles. Device, room, area, group, scene, automation, gateway, favorite, lighting, and other house-scoped operations require `houseId` at the request, environment, or profile layer.
 
+## Resource Commands
+
+Resource commands are the human-friendly command surface. They follow the common CLI shape `yeelight-home <resource> <action> [flags]` and use the same Runtime intent engine as `invoke --stdin`.
+
+```sh
+yeelight-home help device
+yeelight-home help device list
+yeelight-home device list --json
+yeelight-home room search --name 客厅 --json
+yeelight-home scene execute --scene-id <scene-id> --json
+yeelight-home light on --device-id <device-id> --json
+yeelight-home light brightness --device-id <device-id> --brightness 60 --json
+yeelight-home automation enable --automation-id <automation-id> --json
+yeelight-home plan commit --plan-id <plan-id> --json
+```
+
+Resource groups exposed by the CLI:
+
+| Group | Examples |
+| --- | --- |
+| Account and setup | `account info`, `home list`, `home select`, `profile use`, `config set` |
+| Home organization | `home summary`, `home detail`, `home sort`, `home sort-configure`, `favorite add`, `favorite batch-delete` |
+| Space and entities | `room list`, `room batch-create`, `area update`, `group structure`, `entity list`, `entity rename-batch` |
+| Devices and gateways | `device detail`, `device attrs`, `device move-room-batch`, `gateway thread`, `gateway stats`, `meshgroup detail` |
+| Scenes and automations | `scene execute`, `scene batch-delete`, `automation supported-v2`, `automation enable`, `schedule jobs` |
+| Lighting and controls | `light on`, `light brightness-adjust`, `lighting plan`, `lighting apply`, `behavior execute` |
+| Panels and sensors | `panel screen-controls`, `panel button-event-update`, `knob configure`, `sensor events`, `screen controls` |
+| Knowledge and maintenance | `thing products`, `thing schema-get`, `thing faqs`, `upgrade files`, `progress get`, `message list` |
+| Local intelligence | `memory remember`, `memory list`, `recommendation feedback`, `ai-voice products` |
+
+For less common intent fields, use `--params-json` or `--set key=value`:
+
+```sh
+yeelight-home scene create --params-json '{"name":"回家灯光","details":[{"typeId":2,"resId":"50018330","params":{"set":{"p":true}}}]}' --json
+yeelight-home favorite add --set typeId=2,resId=50018330,rank=1 --json
+yeelight-home thing product-info --product-ids 133121,198660 --json
+yeelight-home panel button-event-update --button-event-id <id> --params-json '<json>' --json
+```
+
+`invoke --stdin` remains the stable machine interface for Skills and generated apps. Resource commands are for humans and support scripts that prefer ordinary flags.
+
 ## Config Commands
 
 ```sh

package/README.md

@@ -61,6 +61,10 @@ 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 --house-id <house-id>
+yeelight-home device list --json
+yeelight-home scene execute --scene-id <scene-id> --json
+yeelight-home light on --device-id <device-id> --json
+yeelight-home automation enable --automation-id <automation-id> --json
 ```
 
 The default region is `cn`. Pass `--region sg`, `--region us`, or `--region eu` when your Yeelight account belongs to another cloud region.
@@ -107,6 +111,50 @@ See [CONFIG.md](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. It accepts one SkillRequest JSON object and returns one SkillResponse JSON object.
+
+Human operators should usually use resource commands:
+
+```sh
+yeelight-home device list --json
+yeelight-home room list --json
+yeelight-home scene execute --scene-id <scene-id> --json
+yeelight-home light brightness --device-id <device-id> --brightness 60 --json
+yeelight-home automation enable --automation-id <automation-id> --json
+yeelight-home plan commit --plan-id <plan-id> --json
+```
+
+The resource commands are thin wrappers around Runtime intents. They keep the same profile, region, credential, redaction, preflight, pending-plan, and verification rules as `invoke`.
+
+The command shape is intentionally conventional:
+
+```text
+yeelight-home <resource> <action> [--json] [--profile <name>] [--region <region>] [--house-id <id>] [resource flags]
+```
+
+Common resources include `home`, `room`, `area`, `device`, `entity`, `gateway`, `group`, `scene`, `automation`, `light`, `lighting`, `favorite`, `panel`, `knob`, `sensor`, `thing`, `upgrade`, `memory`, `recommendation`, `account`, and `plan`. Run `yeelight-home --help` for the full resource list.
+
+Use `yeelight-home help <resource>` to list actions, and `yeelight-home help <resource> <action>` for action-specific flags. Examples:
+
+```sh
+yeelight-home help device
+yeelight-home help scene execute
+yeelight-home help light brightness
+```
+
+For uncommon fields, pass advanced parameters without dropping to raw stdin:
+
+```sh
+yeelight-home room search --name 客厅 --json
+yeelight-home scene create --params-json '{"name":"回家灯光","details":[{"typeId":2,"resId":"50018330","params":{"set":{"p":true}}}]}' --json
+yeelight-home favorite add --set typeId=2,resId=50018330,rank=1 --json
+yeelight-home thing schema-get --schema-id <schema-id> --json
+yeelight-home upgrade files --json
+yeelight-home panel button-configure --device-id <panel-id> --params-json '<json>' --json
+```
+
 ### `doctor`
 
 ```sh
@@ -208,6 +256,8 @@ yeelight-home invoke --stdin
 
 Reads a SkillRequest JSON object from stdin and writes a SkillResponse JSON object to stdout. This is the only command Skills should call for smart-home operations.
 
+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`, `automation enable`, and `plan commit`.
+
 ### `api smoke`
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yeelight-home",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Local Yeelight Home Runtime CLI installer and launcher.",
   "license": "UNLICENSED",
   "homepage": "https://github.com/Yeelight/yeelight-home#readme",