fix(service): take --entity, name a missing target, and say the right form for the usual wrong guesses

With 0.0.4 an Agent turned a light yellow in three steps, then needed five
to turn it off: --entity_id=..., --entity-id=..., hass-cli light.turn_off
and a call with no target (a bare HTTP 400) all failed first.

- service call takes --entity (repeatable or comma-separated), and reads
  --entity_id / --entity-id as it.
- A call with no entity, device, area, floor, label or target fails locally
  when the live service catalog says the service takes a target, naming the
  flag and how to find the entity.
- An unknown flag on service call names the three ways to pass a target and
  data; a domain.service used as a command names service call; other
  unknown commands keep their close matches.
- Errors print in full: FriendlyMessage printed only the inner HTTP error,
  so the hint 0.0.4 added to a 400 never reached the terminal.
- ha-lighting and ha-shared quick control use --entity.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: pengpeng

cmd/root.go

@@ -2,6 +2,9 @@
 package cmd
 
 import (
+	"fmt"
+	"strings"
+
 	"github.com/beclab/hass-cli/internal/cmdutil"
 	"github.com/spf13/cobra"
 )
@@ -28,6 +31,21 @@ func NewRootCommand() *cobra.Command {
 		SilenceUsage:  true,
 		SilenceErrors: true,
 		Version:       version,
+		// A service name used as a command (hass-cli light.turn_off ...) is the
+		// commonest wrong guess; say what the right command is.
+		Args: cobra.ArbitraryArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if len(args) == 0 {
+				return cmd.Help()
+			}
+			if strings.Count(args[0], ".") == 1 && !strings.HasPrefix(args[0], "-") {
+				return fmt.Errorf("unknown command %q for \"hass-cli\"; to call that service: hass-cli service call %s --entity <entity_id>", args[0], args[0])
+			}
+			if near := cmd.SuggestionsFor(args[0]); len(near) > 0 {
+				return fmt.Errorf("unknown command %q for \"hass-cli\"; did you mean %s?", args[0], strings.Join(near, ", "))
+			}
+			return fmt.Errorf("unknown command %q for \"hass-cli\"; run hass-cli --help for the commands", args[0])
+		},
 	}
 
 	pf := root.PersistentFlags()

cmd/service.go

@@ -9,6 +9,7 @@ import (
 	"github.com/beclab/hass-cli/internal/catalog"
 	"github.com/beclab/hass-cli/internal/cmdutil"
 	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
 )
 
 func newServiceCmd(f *cmdutil.Factory) *cobra.Command {
@@ -17,7 +18,8 @@ func newServiceCmd(f *cmdutil.Factory) *cobra.Command {
 		Short: "List and call services",
 		Example: `  hass-cli service list
   hass-cli service describe light.turn_on
-  hass-cli service call light.turn_on --arguments entity_id=light.kitchen`,
+  hass-cli service call light.turn_on --arguments entity_id=light.kitchen
+  hass-cli service call light.turn_off --entity light.kitchen`,
 	}
 
 	cmd.AddCommand(&cobra.Command{
@@ -48,7 +50,7 @@ func newServiceCmd(f *cmdutil.Factory) *cobra.Command {
 	})
 
 	var dataJSON string
-	var arguments []string
+	var arguments, entities []string
 	callCmd := &cobra.Command{
 		Use:   "call <domain.service>",
 		Short: "Call a service, e.g. light.turn_on --arguments entity_id=light.kitchen",
@@ -74,6 +76,9 @@ func newServiceCmd(f *cmdutil.Factory) *cobra.Command {
 					data[strings.TrimSpace(k)] = coerceValue(strings.TrimSpace(v))
 				}
 			}
+			if len(entities) > 0 {
+				data["entity_id"] = strings.Join(entities, ",")
+			}
 			c, err := f.Client()
 			if err != nil {
 				return err
@@ -82,6 +87,9 @@ func newServiceCmd(f *cmdutil.Factory) *cobra.Command {
 			if err := checkEntities(cmd.Context(), c, entityIDsIn(data)); err != nil {
 				return err
 			}
+			if err := checkTarget(cmd.Context(), c, domain, service, data); err != nil {
+				return err
+			}
 			raw, err := c.CallService(cmd.Context(), domain, service, data)
 			if err != nil {
 				return explainCallError(err, args[0])
@@ -91,6 +99,18 @@ func newServiceCmd(f *cmdutil.Factory) *cobra.Command {
 	}
 	callCmd.Flags().StringVar(&dataJSON, "data", "", "Service data as a JSON object (or @file.json)")
 	callCmd.Flags().StringArrayVar(&arguments, "arguments", nil, "key=value pairs (repeatable; one flag may also hold several, comma-separated). Values may be numbers, true/false or JSON lists")
+	callCmd.Flags().StringSliceVar(&entities, "entity", nil, "Target entity id(s), repeatable or comma-separated; the same as --arguments entity_id=...")
+	// --entity_id and --entity-id are what an agent guesses first; take them for --entity.
+	callCmd.Flags().SetNormalizeFunc(func(_ *pflag.FlagSet, name string) pflag.NormalizedName {
+		switch name {
+		case "entity_id", "entity-id", "entities", "entity_ids", "entity-ids":
+			name = "entity"
+		}
+		return pflag.NormalizedName(name)
+	})
+	callCmd.SetFlagErrorFunc(func(c *cobra.Command, err error) error {
+		return fmt.Errorf("%w\nservice call takes the target and data as: --entity light.kitchen, --arguments key=value, or --data '{\"entity_id\":\"light.kitchen\",...}'", err)
+	})
 	cmd.AddCommand(callCmd)
 
 	cmd.AddCommand(&cobra.Command{

cmd/service_args.go

@@ -9,6 +9,7 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/beclab/hass-cli/internal/catalog"
 	"github.com/beclab/hass-cli/internal/client"
 )
 
@@ -174,3 +175,30 @@ func explainCallError(err error, service string) error {
 	}
 	return err
 }
+
+// targetKeys are the ways a service call can name what it acts on.
+var targetKeys = []string{"entity_id", "device_id", "area_id", "floor_id", "label_id", "target"}
+
+// checkTarget fails before the call when the service acts on targets and the
+// data names none: Home Assistant answers that with a bare "400: Bad Request".
+// Whether a service takes a target comes from the live service catalog.
+func checkTarget(ctx context.Context, c *client.Client, domain, service string, data map[string]any) error {
+	for _, key := range targetKeys {
+		if _, ok := data[key]; ok {
+			return nil
+		}
+	}
+	raw, err := c.Services(ctx)
+	if err != nil {
+		return nil
+	}
+	cat, err := catalog.Parse(raw)
+	if err != nil {
+		return nil
+	}
+	svc, ok := cat.Lookup(domain, service)
+	if !ok || len(svc.Target) == 0 || string(svc.Target) == "null" {
+		return nil
+	}
+	return fmt.Errorf("%s.%s needs a target: add --entity %s.<object_id> (find it with: hass-cli state list --domain %s --search <name>)", domain, service, domain, domain)
+}

internal/client/errors.go

@@ -18,15 +18,17 @@ func FriendlyMessage(err error) string {
 
 	var httpErr *HTTPError
 	if errors.As(err, &httpErr) {
+		// err, not httpErr: a command may have wrapped the HTTP error with what to do
+		// next, and printing only the inner error dropped that.
 		switch {
 		case httpErr.Status == 401 || httpErr.Status == 403:
-			return httpErr.Error() + " (token rejected or lacks permission; check HASS_TOKEN is a valid admin long-lived token)"
+			return err.Error() + " (token rejected or lacks permission; check HASS_TOKEN is a valid admin long-lived token)"
 		case httpErr.Status == 404:
-			return httpErr.Error() + " (not found; check the path or resource exists)"
+			return err.Error() + " (not found; check the path or resource exists)"
 		case httpErr.Status >= 500:
-			return httpErr.Error() + " (Home Assistant internal error; check the HA logs)"
+			return err.Error() + " (Home Assistant internal error; check the HA logs)"
 		default:
-			return httpErr.Error()
+			return err.Error()
 		}
 	}
 

internal/client/errors_test.go

@@ -0,0 +1,14 @@
+package client
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+)
+
+func TestFriendlyMessageKeepsWhatACommandAdded(t *testing.T) {
+	err := fmt.Errorf("%w\nuse --data for lists", &HTTPError{Status: 400, Body: "400: Bad Request"})
+	if msg := FriendlyMessage(err); !strings.Contains(msg, "use --data for lists") || !strings.Contains(msg, "HTTP 400") {
+		t.Fatalf("FriendlyMessage dropped the hint: %q", msg)
+	}
+}

skills/ha-lighting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ha-lighting
-version: 0.3.1
+version: 0.3.2
 description: "Turn lights, switches and fans on or off, dim them, set colour or colour temperature, set fan speed. The skill for 'turn on the light' or 'turn off the fan'."
 metadata:
   requires:
@@ -22,10 +22,10 @@ skills, run `service describe`, or check the state afterwards.
 hass-cli state list --domain light --search kitchen
 
 # 2. Call the service on the entity_id from step 1
-hass-cli service call light.turn_on --arguments entity_id=light.kitchen
-hass-cli service call light.turn_off --arguments entity_id=light.kitchen
-hass-cli service call switch.turn_off --arguments entity_id=switch.porch
-hass-cli service call fan.turn_on --arguments entity_id=fan.bedroom
+hass-cli service call light.turn_on --entity light.kitchen
+hass-cli service call light.turn_off --entity light.kitchen
+hass-cli service call switch.turn_off --entity switch.porch
+hass-cli service call fan.turn_on --entity fan.bedroom
 
 # Colour, brightness, warmth: one light.turn_on, which also switches it on
 hass-cli service call light.turn_on --data '{"entity_id":"light.kitchen","color_name":"yellow"}'

skills/ha-shared/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ha-shared
-version: 0.3.1
+version: 0.3.2
 description: "Connecting hass-cli to Home Assistant (profile or token), output formats, raw REST and WebSocket access, and auth-error recovery. Load when a command cannot connect or authenticate; device control is in the domain skills."
 metadata:
   requires:
@@ -26,11 +26,11 @@ hass-cli state list --domain light --search kitchen
 hass-cli state list --search 客厅
 
 # 2. Call the service on the entity_id from step 1
-hass-cli service call light.turn_on --arguments entity_id=light.kitchen
+hass-cli service call light.turn_on --entity light.kitchen
 hass-cli service call light.turn_on --data '{"entity_id":"light.kitchen","brightness_pct":30}'
-hass-cli service call switch.turn_off --arguments entity_id=switch.porch
+hass-cli service call switch.turn_off --entity switch.porch
 hass-cli service call climate.set_temperature --data '{"entity_id":"climate.living","temperature":21}'
-hass-cli service call cover.close_cover --arguments entity_id=cover.bedroom
+hass-cli service call cover.close_cover --entity cover.bedroom
 ```
 
 - The call prints the entities it changed: that is the confirmation. `No entity

smoke_test.go

@@ -45,6 +45,7 @@ func mockHAWith(t *testing.T, components []string) *httptest.Server {
 					"turn_on": map[string]any{
 						"name":        "Turn on",
 						"description": "Turn a light on",
+						"target":      map[string]any{"entity": []any{map[string]any{"domain": []string{"light"}}}},
 						"fields": map[string]any{
 							"brightness_pct":  map[string]any{"description": "Brightness %"},
 							"advanced_fields": map[string]any{"collapsed": true, "fields": map[string]any{"color_name": map[string]any{"example": "red"}}},
@@ -261,6 +262,8 @@ func TestSmoke(t *testing.T) {
 		{"service-call-unchanged", []string{"service", "call", "light.turn_on", "--arguments", "entity_id=light.living_room"}, "No entity changed state"},
 		{"state-list-yaml", []string{"-o", "yaml", "state", "list"}, "entity_id: light.kitchen"},
 		{"state-list-ndjson", []string{"-o", "ndjson", "state", "list"}, "{\"entity_id\":\"sun.sun\""},
+		{"service-call-entity_id-flag", []string{"service", "call", "light.turn_on", "--entity_id=light.kitchen"}, "light.kitchen"},
+		{"service-call-entity-id-flag", []string{"service", "call", "light.turn_on", "--entity-id", "light.kitchen"}, "light.kitchen"},
 		{"service-call-comma-pairs", []string{"service", "call", "light.turn_on", "--arguments", "entity_id=light.kitchen,brightness_pct=40"}, "light.kitchen"},
 		{"service-describe-table", []string{"service", "describe", "light.turn_on"}, "brightness_pct"},
 		{"service-describe-section-fields", []string{"service", "describe", "light.turn_on"}, "color_name"},
@@ -414,6 +417,10 @@ func TestServiceCallEntityChecks(t *testing.T) {
 	cases := map[string][]string{
 		"did you mean light.kitchen (Kitchen Ceiling)": {"service", "call", "light.turn_on", "--arguments", "entity_id=light.kitchen_lamp"},
 		"is not an entity id":                          {"service", "call", "light.turn_on", "--data", `{"entity_id":"Kitchen light"}`},
+		"light.turn_on needs a target: add --entity":   {"service", "call", "light.turn_on"},
+		"service call takes the target and data as":    {"service", "call", "light.turn_on", "--brightness", "40"},
+		"hass-cli service call light.turn_off":         {"light.turn_off", "light.kitchen"},
+		"did you mean state":                           {"stat", "list"},
 	}
 	for want, args := range cases {
 		t.Run(want, func(t *testing.T) {