CLI Reference
homectl provides a modular CLI built with Cobra. All commands support --help for inline documentation.
Global Flags
Section titled “Global Flags”--bridge string: Lutron Bridge IP address. Defaults to auto-discovery or cached IP.--json: Output results as machine-readable JSON.--dry-run: Simulate operation without sending network mutations.
Subcommands Overview
Section titled “Subcommands Overview”homectl├── discover # Network-wide device scan├── ui # Launch interactive Bubble Tea TUI├── serve # Start REST API server and static UI host├── lutron # Control Lutron Caseta / RA2 Select│ ├── list # List devices, zones, and areas│ │ ├── devices│ │ ├── zones│ │ └── areas│ └── set # Set dimming levels│ ├── level│ └── all├── sonos # Control Sonos speakers│ ├── list # List speakers with transport and volume│ ├── details # Show queue and audio stream details│ ├── play # Start playback│ ├── pause # Pause playback│ ├── stop # Stop playback│ ├── next # Next track│ ├── prev # Previous track│ ├── seek # Seek track or time offset│ ├── now-playing # Quick track metadata display│ ├── volume # Set volume (0-100)│ ├── favorites # List pinned cloud favorites│ ├── play-favorite# Play pinned favorite by ID│ ├── play-stream # Play direct HTTP/HTTPS audio stream│ ├── queue-add # Enqueue track to playback queue│ ├── queue # View items in playback queue│ ├── queue-remove # Remove track(s) from playback queue│ ├── queue-clear # Clear all tracks from playback queue│ ├── queue-reorder# Reorder tracks in playback queue│ ├── queue-mode # Configure playback modes (shuffle, repeat, crossfade)│ └── services # List streaming services catalog└── qolsys # Qolsys alarm panel integration └── monitor # Stream live panel events via WebSocketCommand Details
Section titled “Command Details”homectl discover
Section titled “homectl discover”Runs concurrent discovery across all registered providers:
homectl discoverhomectl lutron list devices
Section titled “homectl lutron list devices”Fetches all devices from the bridge alongside their real-time zone status:
homectl lutron list deviceshomectl lutron set level
Section titled “homectl lutron set level”Sets the dimming level (0–100) for a zone:
homectl lutron set level <zone_href> <0-100># Example:homectl lutron set level /zone/1 75homectl lutron set all
Section titled “homectl lutron set all”Sets the dimming level across all lights in the home:
homectl lutron set all 0homectl sonos list
Section titled “homectl sonos list”Lists all Sonos speakers, cached or discovered, with generation (S1/S2), device type (Speaker vs. Bridge), volume, and now-playing track:
homectl sonos listhomectl sonos details <ip>
Section titled “homectl sonos details <ip>”Prints full metadata (queue length, format, duration, next track):
homectl sonos details 192.168.1.120homectl sonos seek <ip>
Section titled “homectl sonos seek <ip>”Jumps to a 1-based track number in the queue or seeks to a time offset in the current track. Supports --dry-run:
homectl sonos seek 192.168.1.120 --track 3homectl sonos seek 192.168.1.120 --time 1:30homectl sonos seek 192.168.1.120 --track 3 --dry-runhomectl sonos volume <ip> <0-100>
Section titled “homectl sonos volume <ip> <0-100>”Sets speaker volume percentage:
homectl sonos volume 192.168.1.120 35homectl sonos favorites [ip]
Section titled “homectl sonos favorites [ip]”Lists pinned cloud playlists, albums, and radio stations from Sonos Favorites (FV:2):
homectl sonos favorites 192.168.1.120homectl sonos favorites 192.168.1.120 --jsonhomectl sonos play-favorite [ip] <id>
Section titled “homectl sonos play-favorite [ip] <id>”Starts playback of a pinned favorite by ID (or title). Supports --dry-run:
homectl sonos play-favorite 192.168.1.120 FV:2/1homectl sonos play-favorite 192.168.1.120 FV:2/1 --dry-runhomectl sonos play-stream [ip] <url>
Section titled “homectl sonos play-stream [ip] <url>”Streams any direct HTTP or HTTPS audio URL (internet radio, podcast, TTS voice):
homectl sonos play-stream 192.168.1.120 http://stream.somafm.com/groovesalad-128-mp3 --title "SomaFM"homectl sonos queue-add [ip] <uri>
Section titled “homectl sonos queue-add [ip] <uri>”Enqueues a track or container URI without interrupting current playback:
homectl sonos queue-add 192.168.1.120 x-file-cifs://nas/track.flac --nexthomectl sonos queue [ip]
Section titled “homectl sonos queue [ip]”Inspects items in the Sonos playback queue with positions, titles, artists, and durations:
homectl sonos queue 192.168.1.120 --start 0 --count 20homectl sonos queue 192.168.1.120 --jsonhomectl sonos queue-remove [ip]
Section titled “homectl sonos queue-remove [ip]”Removes one or more tracks from the Sonos playback queue. Supports --dry-run:
homectl sonos queue-remove 192.168.1.120 --track 3 --count 1homectl sonos queue-remove 192.168.1.120 --track 3 --dry-runhomectl sonos queue-clear [ip]
Section titled “homectl sonos queue-clear [ip]”Clears all tracks from the speaker’s playback queue. Supports --dry-run:
homectl sonos queue-clear 192.168.1.120homectl sonos queue-clear 192.168.1.120 --dry-runhomectl sonos queue-reorder [ip]
Section titled “homectl sonos queue-reorder [ip]”Reorders tracks in the playback queue, moving a track range before a target position or bumping to play next. Supports --dry-run:
homectl sonos queue-reorder 192.168.1.120 --track 8 --as-nexthomectl sonos queue-reorder 192.168.1.120 --track 5 --insert-before 2homectl sonos queue-reorder 192.168.1.120 --track 8 --as-next --dry-runhomectl sonos queue-mode [ip]
Section titled “homectl sonos queue-mode [ip]”Configures queue playback modes (shuffle, repeat, crossfade) on the speaker or group coordinator. Supports --dry-run and --json:
homectl sonos queue-mode 192.168.1.120 --shuffle on --repeat all --crossfade offhomectl sonos queue-mode 192.168.1.120 --shuffle on --dry-runhomectl sonos queue-mode 192.168.1.120 --repeat one --jsonhomectl sonos services [ip]
Section titled “homectl sonos services [ip]”Lists the catalog of supported streaming services and identifies the configured default provider:
homectl sonos services 192.168.1.120 --jsonhomectl sonos join <speaker-ip> <target-ip>
Section titled “homectl sonos join <speaker-ip> <target-ip>”Joins a speaker to another speaker’s group. Validates that both devices belong to the same hardware generation (S1 with S1, S2 with S2) and rejects grouping with non-rendering devices (bridges):
homectl sonos join 192.168.1.121 192.168.1.120homectl sonos leave <speaker-ip>
Section titled “homectl sonos leave <speaker-ip>”Unjoins a speaker into an independent standalone coordinator group:
homectl sonos leave 192.168.1.121homectl qolsys monitor
Section titled “homectl qolsys monitor”Connects to a Qolsys IQ Panel and prints incoming event frames:
homectl qolsys monitor --host 192.168.1.30 --token 123456homectl serve
Section titled “homectl serve”Starts the HTTP API server:
homectl serve --port 8080 --ui ./ui/distFlags:
-H, --host string: Host/IP address to bind the API server to (default0.0.0.0; supports127.0.0.1, Tailscale100.x.y.z).-p, --port int: Port to listen on (default8080).--ui string: Path to directory containing built Web UI assets (default./ui/dist).
Security examples:
# Bind to localhost for reverse-proxy or local-only agent accesshomectl serve --host 127.0.0.1 --port 8080
# Bind to Tailscale IP for secure off-LAN remote accesshomectl serve -H 100.85.12.34 -p 8080