alexa-mcp 0.2.2 → 0.3.0

package/README.md

@@ -1,138 +1,149 @@
-# alexa-mcp
+# Alexa MCP
 
-MCP server and CLI for Alexa devices and smart home control via the unofficial Alexa API.
+[![npm version](https://badge.fury.io/js/alexa-mcp.svg)](https://www.npmjs.com/package/alexa-mcp)
+[![CI](https://github.com/m0nkmaster/alexa-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/m0nkmaster/alexa-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Requirements
-
-- Node.js 18+
-- Amazon Alexa account (amazon.com, amazon.co.uk, or amazon.de)
+**Control your Alexa devices and smart home from the command line or AI assistants.**
 
-## Setup
+MCP server and CLI for Alexa/Echo devices and smart home control via the unofficial Alexa API. Works with Claude Desktop, Cursor, VS Code, and other MCP-compatible tools.
 
-1. Install:
-   ```bash
-   npm install alexa-mcp          # local install
-   npm install -g alexa-mcp       # global install (adds alexa-mcp to PATH)
-   npx alexa-mcp auth             # run without installing
-   ```
+## Features
 
-2. Authenticate:
-   ```bash
-   alexa-mcp auth
-   ```
-   Opens a URL (tunnel or localhost) for you to log in to Amazon. Works locally or headless (remote server) — same behaviour either way. Uses cloudflared or localtunnel automatically; no account required.
+- 🎙️ **Voice & Media Control** - TTS, announcements, playback control
+- 💡 **Smart Home** - Control lights, plugs, and devices by name, pattern, or room group
+- ✅ **State Verification** - Every control command returns live device state (power, brightness, colour temp)
+- 🔍 **Device Status** - Query current state of any device by name without issuing a command
+- 🏠 **Group Membership** - List all devices in a room group for post-action verification
+- 🤖 **Routines** - List and run routines by name, partial name, or automation ID
+- 🌍 **Multi-Region** - Supports US (amazon.com), UK (amazon.co.uk), and DE (amazon.de)
+- 🔌 **MCP Integration** - Use with Claude, Cursor, and other AI assistants
+- 🛠️ **CLI & Programmatic** - Command-line tool or Node.js library
 
-   Or headless:
-   ```bash
-   alexa-mcp auth --token "Atnr|..."
-   alexa-mcp auth --token-file /path/to/token.txt
-   alexa-mcp auth --domain amazon.com   # US account (default: amazon.co.uk)
-   alexa-mcp auth --no-save             # validate token without saving
-   ```
+## Quick Start
 
-3. Config stored in `~/.alexa-mcp/config.json`. Also reads `~/.alexa-cli/config.json` or `ALEXA_REFRESH_TOKEN`.
+### Installation
 
-### Environment variables
+```bash
+# Global install (recommended for CLI usage)
+npm install -g alexa-mcp
 
-| Variable | Description |
-|----------|-------------|
-| `ALEXA_REFRESH_TOKEN` | Refresh token; skips config file lookup |
-| `ALEXA_DOMAIN` | Amazon domain when using env token (default: `amazon.co.uk`; options: `amazon.com`, `amazon.de`) |
-| `ALEXA_DEBUG` | Set to any value to log API request/response details to stderr |
+# Or use without installing
+npx alexa-mcp auth
+```
 
-## CLI
+### Authentication
+**Interactive (browser-based):**
+```bash
+alexa-mcp auth
+```
+Opens a URL for you to log in to Amazon. Works locally or on remote servers using automatic tunneling (cloudflared or localtunnel).
 
+**Headless (token-based):**
 ```bash
-alexa-mcp auth                              # Interactive auth (browser / tunnel URL)
-alexa-mcp auth --token <token>             # Save token (headless)
-alexa-mcp auth --token-file <path>         # Read token from file
-alexa-mcp auth --domain amazon.com         # Specify Amazon domain (default: amazon.co.uk)
-alexa-mcp auth --no-save                   # Validate token without saving
-alexa-mcp auth status [--verify]           # Show auth status (--verify calls API)
-alexa-mcp auth logout                      # Remove credentials
-alexa-mcp devices                          # List Echo devices
-alexa-mcp devices --owners                 # Show device names and owner customer IDs (profile matching)
-alexa-mcp speak "Hello" -d Office          # Speak text on a specific device
-alexa-mcp announce "Dinner ready"          # Announce to all devices
-alexa-mcp command -d Office "play jazz"    # Voice command (no response returned)
-alexa-mcp groups                           # List room/space groups (Kitchen, Living room, etc.)
-alexa-mcp switch-group Kitchen off         # Turn off all lights in a group
-alexa-mcp switch-group Kitchen off --all   # Turn off ALL appliances in group (not just lights)
-alexa-mcp switch-room "kitchen lights" off # Turn off all devices matching name pattern
-alexa-mcp switch "Lounge light 2" off      # Turn off single device by name (direct control; -d for voice fallback)
-alexa-mcp appliances                       # List smart home devices (endpointId + friendlyName when available)
-alexa-mcp control <entityId> turnOn|turnOff|setBrightness [--brightness 50]
-alexa-mcp routines                         # List routines
-alexa-mcp run <automationId>               # Run a routine
-alexa-mcp now-playing -d Office            # Now-playing state (EU/UK)
-alexa-mcp media play|pause|resume|stop|next|previous -d Office  # Transport control (EU/UK)
+alexa-mcp auth --token "Atnr|..."
+alexa-mcp auth --token-file /path/to/token.txt
+alexa-mcp auth --domain amazon.com   # US account (default: amazon.co.uk)
 ```
 
-**Smart home:** For "all lights in group Kitchen", use `switch-group Kitchen off` (use `groups` to list group names). For pattern matching (e.g. "kitchen lights"), use `switch-room`. Both use direct control—avoids voice profile issues. `switch` is for a single device. Voice commands (`command`) do not return Alexa's response. `switch-group` targets only lights by default; add `--all` to include all appliances. `media` commands require active playback (`resume` re-starts paused playback). See [docs/API.md](docs/API.md).
+Configuration is stored in `~/.alexa-mcp/config.json`.
 
-### "Can't control – may need to switch user accounts"
+## Usage
 
-If the Echo says it can't control the device and suggests switching user accounts:
+### CLI Commands
 
-- **Who the CLI uses:** The CLI always acts as the **Amazon account you signed in with** when you last ran `alexa-mcp auth`. It does not use the Echo’s current profile. Changing the Echo’s profile in the Alexa app does **not** change which account the CLI uses.
-- **When you use profiles (e.g. Rob vs Emma):** You must run the CLI as the **same account that owns the smart home device**. So:
-  1. Run `alexa-mcp auth logout`.
-  2. Run `alexa-mcp auth` and sign in as the **household member who can say “Alexa, turn off Lounge Lamp”** on that Echo and have it work (the account that “owns” the lamp in the Alexa app).
-  3. Then run `alexa-mcp switch "Lounge Lamp" off -d "Lounge Echo"` again.
-- **Single account:** If there’s only one account, ensure the lamp is linked to that account in the Alexa app (Devices → Lights/Plugs).
+**Authentication:**
+```bash
+alexa-mcp auth                    # Interactive auth
+alexa-mcp auth status [--verify]  # Check auth status
+alexa-mcp auth logout             # Remove credentials
+```
 
-### Seeing which profile owns devices
+**Devices & Voice:**
+```bash
+alexa-mcp devices                      # List Echo devices
+alexa-mcp speak "Hello" -d Office      # Text-to-speech on device
+alexa-mcp announce "Dinner ready"      # Announce to all devices
+alexa-mcp command -d Office "play jazz" # Voice command
+```
 
-Each Echo and smart home device has a **deviceOwnerCustomerId** (Amazon’s internal account ID). The CLI uses the account you signed in with; that account has one or more such IDs. To see who owns what:
+**Smart Home:**
+```bash
+alexa-mcp groups                           # List room groups
+alexa-mcp group-members Kitchen            # List all devices in a group
+alexa-mcp appliances                       # List smart home devices (with …suffix for disambiguation)
+alexa-mcp appliances --type light          # Filter by type: light, switch, plug, sensor, camera
+alexa-mcp status "Lounge lamp"             # Get current state (power, brightness, colour temp)
+alexa-mcp switch-group Kitchen off         # Turn off lights in room group → returns JSON result
+alexa-mcp switch-room "kitchen lights" off # Turn off devices by pattern → returns JSON result
+alexa-mcp switch "Lounge light 2" off      # Turn off single device → returns live state JSON
+alexa-mcp control <entityId> turnOn        # Direct device control → returns live state JSON
+alexa-mcp batch-control turnOff e1 e2 e3  # Batch control → returns per-device result map
+```
 
-- **Echo devices:**  
-  `alexa-mcp devices --owners`  
-  Prints each device name and its `deviceOwnerCustomerId`. Use the same account for `alexa-mcp auth` as the one that owns the Echo you’re targeting.
+**Routines & Media:**
+```bash
+alexa-mcp routines                              # List routines (includes name field)
+alexa-mcp run <automationId>                    # Run a routine by ID
+alexa-mcp run --name "our bedtime"              # Run a routine by exact name
+alexa-mcp run --partial "bedtime"               # Run a routine by partial name match
+alexa-mcp now-playing -d Office                 # Show now-playing
+alexa-mcp media play|pause|next -d Office       # Media control
+```
 
-- **Smart home appliances:**  
-  `alexa-mcp appliances`  
-  The JSON includes `deviceOwnerCustomerId` per device (when the API provides it). Match this to the account you use for auth.
+**Tips:**
+- Use `switch-group` for "all lights in [room]" (e.g., `Kitchen`)
+- Use `switch-room` for pattern matching — tries all-words first, falls back to any-word
+- Use `switch` for single devices by exact name
+- Use `status` to verify device state without issuing a command
+- Use `group-members` after a `switch-group` to see which devices were targeted
+- All control commands now return JSON state — no second API call needed to verify
+- `appliances` output includes `displayName` with a 4-char endpoint suffix to disambiguate duplicates
+- Direct control methods avoid voice profile issues
+- See [docs/API.md](docs/API.md) for full API reference
 
-- **Which account the CLI is using:**  
-  `alexa-mcp auth status --verify`  
-  Shows “Account (deviceOwnerCustomerId): …” for the current session. Control will work when this matches the owner of the Echo and the smart home device.
+### MCP Server Setup
 
-## MCP Server
+### Claude Desktop
 
-**Cursor** (`~/.cursor/mcp.json`) or **VS Code** (`.vscode/mcp.json`):
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
 
 ```json
 {
   "mcpServers": {
     "alexa": {
-      "command": "node",
-      "args": ["/path/to/alexa-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["alexa-mcp"]
     }
   }
 }
 ```
 
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+### Cursor / VS Code
+
+Edit `~/.cursor/mcp.json` or `.vscode/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "alexa": {
-      "command": "node",
-      "args": ["/path/to/alexa-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["alexa-mcp"]
     }
   }
 }
 ```
 
-**With environment variable token** (no file-based config needed):
+### Using Environment Variables
+
+Pass token directly (no config file needed):
 
 ```json
 {
   "mcpServers": {
     "alexa": {
-      "command": "node",
-      "args": ["/path/to/alexa-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["alexa-mcp"],
       "env": {
         "ALEXA_REFRESH_TOKEN": "Atnr|...",
         "ALEXA_DOMAIN": "amazon.co.uk"
@@ -142,52 +153,105 @@ Each Echo and smart home device has a **deviceOwnerCustomerId** (Amazon’s inte
 }
 ```
 
-When installed locally, use the path to `node_modules/alexa-mcp/dist/index.js`. When installed globally (`npm install -g alexa-mcp`), use `npx alexa-mcp` as the command instead of `node`:
+### Local Installation
+
+If installed locally, use the full path:
 
 ```json
 {
   "mcpServers": {
     "alexa": {
-      "command": "npx",
-      "args": ["alexa-mcp"]
+      "command": "node",
+      "args": ["/path/to/node_modules/alexa-mcp/dist/index.js"]
     }
   }
 }
 ```
 
-### MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `alexa_list_devices` | List Echo devices |
-| `alexa_speak` | TTS on a device |
-| `alexa_announce` | Announce to all |
-| `alexa_command` | Voice command (no response returned; prefer direct control for smart home) |
-| `alexa_list_appliances` | List smart home devices (endpointId + friendlyName when available) |
-| `alexa_control_appliance` | turnOn/turnOff/setBrightness by entity/endpoint ID |
-| `alexa_control_by_group` | Turn on/off lights in a room group (e.g. "Kitchen") — **for "all lights in group X"** |
-| `alexa_control_group` | Alias for `alexa_control_by_group`; also supports `lightsOnly` toggle |
-| `alexa_control_by_pattern` | Turn on/off devices matching name pattern (e.g. "kitchen lights") |
-| `alexa_switch_by_name` | Turn single device on/off by friendly name |
-| `alexa_list_device_groups` | List room groups (Living room, Kitchen, etc.) |
-| `alexa_list_audio_groups` | List multi-room audio groups |
-| `alexa_list_routines` | List routines |
-| `alexa_run_routine` | Run a routine by automation ID |
-| `alexa_now_playing` | Now-playing state for a device (includes `taskSessionId`) |
-| `alexa_media_control` | play, pause, resume, stop, next, previous (EU/UK) |
-| `alexa_auth_status` | Check auth status (configured/valid/deviceCount) |
+### Available MCP Tools
+
+**Devices & Voice:**
+- `alexa_list_devices` - List Echo devices
+- `alexa_speak` - Text-to-speech on a device
+- `alexa_announce` - Announce to all devices
+- `alexa_command` - Send voice command
+
+**Smart Home:**
+- `alexa_list_appliances` - List smart home devices; optional `type` filter (light/switch/plug/sensor/camera); includes `displayName` with 4-char endpoint suffix
+- `alexa_device_status` - Get live state of a device by name (power, brightness, colour temp, reachability)
+- `alexa_list_device_groups` - List room groups with member counts
+- `alexa_group_members` - List all appliances in a named room group
+- `alexa_control_by_group` - Control all lights in a room group
+- `alexa_control_by_pattern` - Control devices by name pattern (fuzzy fallback: any-word match if all-word fails)
+- `alexa_switch_by_name` - Control single device by name
+- `alexa_control_appliance` - Direct control by entity/endpoint ID
+- `alexa_batch_control_appliances` - Batch control with same action; returns per-device `{friendlyName, success, error}` map
+- `alexa_batch_control_appliances_custom` - Batch control with per-device actions; returns per-device results
+- `alexa_get_brightness_by_name` - Get device brightness and power state
+- `alexa_set_brightness_by_name` - Set device brightness
+- `alexa_get_color_temperature_by_name` - Get device colour temperature
+- `alexa_set_color_temperature_by_name` - Set device colour temperature
+
+**Routines & Media:**
+- `alexa_list_routines` - List Alexa routines with names and automation IDs
+- `alexa_run_routine` - Execute a routine by `automationId`, exact `name`, or `partial` name match
+- `alexa_list_audio_groups` - List multi-room audio groups
+- `alexa_now_playing` - Get now-playing state
+- `alexa_media_control` - Control playback (play/pause/next/etc.)
+- `alexa_get_volume` / `alexa_set_volume` - Volume control
+
+**Authentication:**
+- `alexa_auth_status` - Check authentication status
+
+## Troubleshooting
+
+### "Can't control – may need to switch user accounts"
+
+This error occurs when the Amazon account you authenticated with doesn't own the device.
+
+**Solution:**
+1. Run `alexa-mcp auth logout`
+2. Run `alexa-mcp auth` and sign in with the account that owns the device
+3. Verify with `alexa-mcp auth status --verify`
+
+**Check device ownership:**
+```bash
+alexa-mcp devices --owners    # Show Echo device owners
+alexa-mcp appliances          # Show smart home device owners
+```
+
+The `deviceOwnerCustomerId` must match between your authenticated account and the device.
 
 ## Development
 
 ```bash
-npm install
-npm run build
-npm test
-npm run test:integration  # Requires ALEXA_REFRESH_TOKEN
+npm install              # Install dependencies
+npm run build           # Compile TypeScript
+npm test                # Run unit tests
+npm run test:integration # Run integration tests (requires auth)
+npm run lint            # Check code style
+npm run lint:fix        # Fix code style issues
 ```
 
-## API Reference
+## Documentation
+
+- **[API Reference](docs/API.md)** - Complete unofficial Alexa API documentation
+- **[Device Capabilities](docs/DEVICE-CAPABILITIES.md)** - Device capability reference
+- **[User Stories](docs/USER-STORIES.md)** - Usage examples and patterns
+
+## Requirements
+
+- Node.js 18+
+- Amazon Alexa account (amazon.com, amazon.co.uk, or amazon.de)
+
+## License
+
+MIT - See LICENSE file for details
+
+## Contributing
+
+Contributions welcome! Please follow [conventional commits](https://www.conventionalcommits.org/) format.
 
-The single authoritative API reference is **[docs/API.md](docs/API.md)** — region base URLs, authentication, all endpoints (devices, routines, smart home, behaviors, alarms, media), request/response bodies, and headers.
+## Acknowledgments
 
-**API usage:** All supported regions use the **app API** (eu-api-alexa for UK/EU, na-api-alexa for US): devices-v2, routinesandgroups, behaviors/preview, smarthome/v2/endpoints, layouts, and GraphQL for smart home control.
+Built on the unofficial Alexa API. Uses [alexa-cookie2](https://github.com/Apollon77/alexa-cookie) for authentication.

package/dist/cli.js

@@ -191,7 +191,7 @@ program
 });
 program
     .command("switch-group <group> <state>")
-    .description("Turn on/off all lights in a room group (e.g. Kitchen, Living room). Uses group membership from Alexa app.")
+    .description("Turn on/off all lights in a room group (e.g. Kitchen, Living room). Returns JSON {action, group, controlled, errors}.")
     .option("--all", "Control all appliances in group, not just lights", false)
     .action(async (group, state, opts) => {
     const s = state.toLowerCase();
@@ -210,12 +210,7 @@ program
         const { controlled, errors } = await client.controlAppliancesByGroup(group, action, {
             lightsOnly: !opts.all,
         });
-        if (controlled.length > 0) {
-            console.log(`${action}: ${controlled.join(", ")}`);
-        }
-        if (errors.length > 0) {
-            console.error(errors.join("\n"));
-        }
+        console.log(JSON.stringify({ action, group, controlled, errors }));
         if (controlled.length === 0 && errors.length === 0) {
             console.error(`No lights in group "${group}". Try 'alexa-mcp groups' to see groups.`);
             process.exit(1);
@@ -228,7 +223,7 @@ program
 });
 program
     .command("switch-room <pattern> <state>")
-    .description("Turn on/off all smart home devices matching a pattern (e.g. 'kitchen lights', 'living room'). Uses direct control—avoids profile issues.")
+    .description("Turn on/off all smart home devices matching a pattern (e.g. 'kitchen lights', 'living room'). Tries all-word match first; falls back to any-word. Returns JSON {action, pattern, controlled, errors}.")
     .action(async (pattern, state) => {
     const s = state.toLowerCase();
     if (s !== "on" && s !== "off") {
@@ -243,12 +238,7 @@ program
     const client = new AlexaClient({ refreshToken: cfg.refreshToken, domain: cfg.domain });
     const action = s === "on" ? "turnOn" : "turnOff";
     const { controlled, errors } = await client.controlAppliancesByPattern(pattern, action);
-    if (controlled.length > 0) {
-        console.log(`${action}: ${controlled.join(", ")}`);
-    }
-    if (errors.length > 0) {
-        console.error(errors.join("\n"));
-    }
+    console.log(JSON.stringify({ action, pattern, controlled, errors }));
     if (controlled.length === 0 && errors.length === 0) {
         console.error(`No devices matched "${pattern}". Try 'alexa-mcp appliances' to see names.`);
         process.exit(1);
@@ -256,7 +246,7 @@ program
 });
 program
     .command("switch <name> <state>")
-    .description("Turn single smart home device on/off by name. For room/pattern (e.g. 'kitchen lights'), use switch-room instead.")
+    .description("Turn single smart home device on/off by name. Returns live device state JSON after applying. For room/pattern (e.g. 'kitchen lights'), use switch-room instead.")
     .option("-d, --device <echo>", "Echo for voice fallback when direct control fails", "")
     .action(async (name, state, opts) => {
     const s = state.toLowerCase();
@@ -274,7 +264,8 @@ program
     const app = await client.resolveApplianceByName(name);
     if (app?.endpointId) {
         await client.controlAppliance(app.endpointId, action);
-        console.log(`Done: ${action} ${app.friendlyName} (direct control)`);
+        const state = await client.getBrightnessState(app.endpointId);
+        console.log(JSON.stringify({ friendlyName: app.friendlyName, endpointId: app.endpointId, ...state }, null, 2));
         return;
     }
     if (!opts.device) {
@@ -288,7 +279,7 @@ program
     }
     const text = s === "on" ? `turn on ${name}` : `turn off ${name}`;
     await client.command(d.serialNumber, d.deviceType, d.deviceOwnerCustomerId, text);
-    console.log(`Sent "${text}" via ${d.accountName} (voice fallback)`);
+    console.log(JSON.stringify({ friendlyName: name, action, method: "voice", device: d.accountName }));
 });
 program
     .command("groups")
@@ -303,22 +294,80 @@ program
     const groups = await client.listDeviceGroups();
     console.log(JSON.stringify(groups, null, 2));
 });
+function filterAppliancesByType(appliances, type) {
+    return appliances.filter((a) => {
+        const caps = (a.capabilities ?? []).join(" ").toLowerCase();
+        const name = (a.friendlyName ?? "").toLowerCase();
+        switch (type) {
+            case "light": return caps.includes("brightness") || caps.includes("colortemperature") || /light|lamp|bulb/.test(name);
+            case "switch": return caps.includes("power") && !caps.includes("brightness");
+            case "plug": return /plug/.test(name);
+            case "sensor": return /sensor|motion|contact|temperature/.test(caps);
+            case "camera": return /camera|doorbell/.test(name);
+            default: return true;
+        }
+    });
+}
 program
     .command("appliances")
     .description("List smart home devices")
-    .action(async () => {
+    .option("--type <type>", "Filter by type: light, switch, plug, sensor, camera")
+    .action(async (opts) => {
     const cfg = getAuthConfig();
     if (!cfg) {
         console.error("No refresh token.");
         process.exit(1);
     }
     const client = new AlexaClient({ refreshToken: cfg.refreshToken, domain: cfg.domain });
-    const appliances = await client.listAppliances();
-    console.log(JSON.stringify(appliances, null, 2));
+    let appliances = await client.listAppliances();
+    if (opts.type) {
+        appliances = filterAppliancesByType(appliances, opts.type.toLowerCase());
+    }
+    const output = appliances.map((a) => ({
+        ...a,
+        displayName: `${a.friendlyName}${a.endpointId ? ` \u2026${a.endpointId.slice(-4)}` : ""}`,
+    }));
+    console.log(JSON.stringify(output, null, 2));
+});
+program
+    .command("status <name>")
+    .description("Get current state of a smart home device by name")
+    .action(async (name) => {
+    const cfg = getAuthConfig();
+    if (!cfg) {
+        console.error("No refresh token.");
+        process.exit(1);
+    }
+    const client = new AlexaClient({ refreshToken: cfg.refreshToken, domain: cfg.domain });
+    const app = await client.resolveApplianceByName(name);
+    if (!app) {
+        console.error(JSON.stringify({ error: `Device not found: "${name}". Try 'alexa-mcp appliances' to see names.` }));
+        process.exit(1);
+    }
+    const eid = app.endpointId ?? app.entityId;
+    const state = eid ? await client.getBrightnessState(eid) : {};
+    console.log(JSON.stringify({ friendlyName: app.friendlyName, endpointId: eid, isReachable: app.isReachable, ...state }, null, 2));
+});
+program
+    .command("group-members <group>")
+    .description("List all devices in a named room group")
+    .action(async (group) => {
+    const cfg = getAuthConfig();
+    if (!cfg) {
+        console.error("No refresh token.");
+        process.exit(1);
+    }
+    const client = new AlexaClient({ refreshToken: cfg.refreshToken, domain: cfg.domain });
+    const members = await client.listGroupMembers(group);
+    if (members.length === 0) {
+        console.error(`No group found matching "${group}". Try 'alexa-mcp groups' to see groups.`);
+        process.exit(1);
+    }
+    console.log(JSON.stringify(members, null, 2));
 });
 program
     .command("control <entityId> <action>")
-    .description("Control smart home device (turnOn, turnOff, setBrightness, setColorTemperature)")
+    .description("Control smart home device (turnOn, turnOff, setBrightness, setColorTemperature). Returns live state JSON after applying.")
     .option("-b, --brightness <0-100>", "Brightness for setBrightness", (v) => parseInt(v, 10))
     .option("-k, --kelvin <2000-6500>", "Color temperature in Kelvin for setColorTemperature", (v) => parseInt(v, 10))
     .action(async (entityId, action, opts) => {
@@ -342,7 +391,8 @@ program
     }
     const client = new AlexaClient({ refreshToken: cfg.refreshToken, domain: cfg.domain });
     await client.controlAppliance(entityId, action, opts.brightness, opts.kelvin);
-    console.log(`Done: ${action} ${entityId}`);
+    const state = entityId.startsWith("amzn1.alexa.endpoint.") ? await client.getBrightnessState(entityId) : {};
+    console.log(JSON.stringify({ entityId, action, ...state }, null, 2));
 });
 program
     .command("routines")
@@ -358,24 +408,55 @@ program
     console.log(JSON.stringify(routines, null, 2));
 });
 program
-    .command("run <automationId>")
-    .description("Run a routine by automation ID")
-    .action(async (automationId) => {
+    .command("run [automationId]")
+    .description("Run a routine by ID, exact name (--name), or partial name (--partial)")
+    .option("--name <name>", "Run routine by exact name (case-insensitive)")
+    .option("--partial <text>", "Run routine by partial name match")
+    .action(async (automationId, opts) => {
     const cfg = getAuthConfig();
     if (!cfg) {
         console.error("No refresh token.");
         process.exit(1);
     }
+    if (!automationId && !opts.name && !opts.partial) {
+        console.error("Provide automationId, --name <name>, or --partial <text>");
+        process.exit(1);
+    }
     const client = new AlexaClient({ refreshToken: cfg.refreshToken, domain: cfg.domain });
     const routines = await client.listRoutines();
-    const r = routines.find((x) => x.automationId === automationId);
-    if (!r) {
-        console.error(`Routine not found: ${automationId}`);
-        process.exit(1);
+    let r;
+    if (automationId) {
+        r = routines.find((x) => x.automationId === automationId);
+        if (!r) {
+            console.error(`Routine not found: ${automationId}`);
+            process.exit(1);
+        }
+    }
+    else if (opts.name) {
+        const q = opts.name.toLowerCase();
+        r = routines.find((x) => x.name.toLowerCase() === q);
+        if (!r) {
+            console.error(`Routine not found with name: "${opts.name}"`);
+            process.exit(1);
+        }
+    }
+    else if (opts.partial) {
+        const q = opts.partial.toLowerCase();
+        const matches = routines.filter((x) => x.name.toLowerCase().includes(q));
+        if (matches.length === 0) {
+            console.error(`No routines matched: "${opts.partial}"`);
+            process.exit(1);
+        }
+        if (matches.length > 1) {
+            console.log(JSON.stringify({ matches: matches.map((m) => ({ automationId: m.automationId, name: m.name })) }, null, 2));
+            console.error(`Multiple matches. Provide --name or a more specific --partial.`);
+            process.exit(1);
+        }
+        r = matches[0];
     }
     const sequenceJson = r.sequence != null ? JSON.stringify(r.sequence) : undefined;
     await client.runRoutine(r.automationId, sequenceJson);
-    console.log(`Ran routine: ${r.name}`);
+    console.log(JSON.stringify({ ran: r.name, automationId: r.automationId }));
 });
 program
     .command("now-playing")
@@ -514,7 +595,7 @@ program
 });
 program
     .command("batch-control <action>")
-    .description("Batch control multiple smart home devices with same action/value. Much faster than individual calls.")
+    .description("Batch control multiple smart home devices with same action/value. Returns per-device result map {friendlyName, success, error?}.")
     .argument("[entityIds...]", "Entity IDs or endpoint IDs (omit to read from stdin)")
     .option("-b, --brightness <0-100>", "Brightness for setBrightness", (v) => parseInt(v, 10))
     .option("-k, --kelvin <2000-6500>", "Color temperature in Kelvin for setColorTemperature", (v) => parseInt(v, 10))
@@ -552,10 +633,20 @@ program
         process.exit(1);
     }
     const client = new AlexaClient({ refreshToken: cfg.refreshToken, domain: cfg.domain });
-    const startTime = Date.now();
-    await client.batchControlAppliances(entityIds, action, opts.brightness, opts.kelvin);
-    const duration = Date.now() - startTime;
-    console.log(`Batch done: ${action} on ${entityIds.length} devices in ${duration}ms`);
+    const [results, appliances] = await Promise.all([
+        client.batchControlAppliances(entityIds, action, opts.brightness, opts.kelvin),
+        client.listAppliances(),
+    ]);
+    const nameMap = new Map(appliances.map((a) => [a.entityId, a.friendlyName]));
+    const output = Object.fromEntries(results.map((r) => [
+        r.entityId,
+        {
+            friendlyName: nameMap.get(r.entityId) ?? r.entityId,
+            success: r.success,
+            ...(r.error ? { error: r.error } : {}),
+        },
+    ]));
+    console.log(JSON.stringify(output, null, 2));
 });
 const mediaCmd = program
     .command("media <command>")