Add device settings management commands

[langtind]

Summary

Closes #3

Adds two new commands for managing device settings:

• homeyctl devices get-settings <name-or-id> - View all settings for a device
• homeyctl devices set-setting <name-or-id> <key> <value> - Modify a device setting

Also updates homeyctl ai with documentation for these commands.

Important: OAuth Scope Limitation

@fishfisher - heads up on a discovery during implementation:

Athom's OAuth system does NOT support the homey.device scope required for changing device settings. The only available device scopes are:

• homey.device.readonly - read device info
• homey.device.control - control devices (on/off, dim, etc.)

This means OAuth tokens (from homeyctl login) cannot modify device settings.

Workaround

Users who need to change device settings must create an API key at my.homey.app:

1. Go to https://my.homey.app
2. Select your Homey → Settings → API Keys
3. Create a new API key (has full access)
4. Run: homeyctl config set-token <api-key>

The CLI includes a clear error message explaining this when users hit the "Missing Scopes" error.

Test plan

• Tested devices get-settings against real Homey
• Tested devices set-setting against real Homey with API key
• Verified clear error message when using OAuth token without required scope
• Updated homeyctl ai documentation

Summary by CodeRabbit

• New Features
  • Added device settings commands to retrieve and update device settings from the CLI.
• Documentation
  • Added guidance on required permissions and authentication (scope and token differences) for accessing device settings.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Adds CLI commands to get and set device settings and corresponding client methods to call Homey’s device settings endpoints; includes an AI-context note about required scopes and API key usage. (50 words)

Changes

Cohort / File(s)	Summary
Client API Methods internal/client/client.go	Added GetDeviceSettings(id string) (json.RawMessage, error) (GET /api/manager/devices/device/{id}/settings_obj) and SetDeviceSetting(deviceID string, settings map[string]interface{}) error (PUT /api/manager/devices/device/{deviceID}/settings).
CLI Command Implementations cmd/devices.go	Added devices get-settings <name-or-id> (fetch/display device settings) and devices set-setting <name-or-id> <setting-key> <value> (resolve device, parse value type, send single-entry settings map, surface permission errors and success message). Registered commands in init().
AI Context Documentation cmd/ai.go	Added AI helper commands for device settings and a note clarifying that settings require full homey.device scope and API keys (OAuth tokens support only homey.device.control), with guidance for creating API keys.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant CLI as "homeyctl CLI"
participant Client as "internal Client\n(internal/client/client.go)"
participant API as "Homey Device Settings API\n(/api/manager/devices/...)"
CLI->>Client: get-settings(deviceID or name)
Client->>API: GET /device/{id}/settings_obj
API-->>Client: settings JSON
Client-->>CLI: settings (JSON or table)
CLI->>Client: set-setting(deviceID or name, key, value)
Client->>API: PUT /device/{id}/settings { key: value }
API-->>Client: 200 OK / error
Client-->>CLI: success / permission error note

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Hop, I nudge and tap the key,

Settings dance from root to tree,
Get and set with tiny feet,
Devices hum, the change is neat,
A rabbit’s cheer for CLI glee 🥕✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add device settings management commands' directly and clearly summarizes the main change—adding CLI commands for viewing and modifying device settings.
Linked Issues check	✅ Passed	All coding requirements from issue #3 are met: new CLI commands for get-settings and set-setting added [#3], settings endpoint used correctly [#3], device name/ID resolution implemented [#3], and value parsing for different types handled [#3].
Out of Scope Changes check	✅ Passed	All changes are directly related to the linked issue requirements: device settings commands in cmd/devices.go, API client methods in internal/client/client.go, and AI documentation in cmd/ai.go are all in scope.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3dc9af0 and 9ef9d2c.

📒 Files selected for processing (3)

• cmd/ai.go
• cmd/devices.go
• internal/client/client.go

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}