lgtvremote-cli 1.0.0__tar.gz

lgtvremote_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Riches
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lgtvremote_cli-1.0.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: lgtvremote-cli
+Version: 1.0.0
+Summary: Command-line interface for controlling LG webOS TVs
+Author: Gary Riches
+License: MIT
+Project-URL: Homepage, https://github.com/griches/lgtvremote-cli
+Keywords: lg,tv,webos,remote,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# LG TV Remote CLI
+
+## Command-line interface for controlling LG webOS TVs over your local network.
+
+Communicates via WebSocket using the SSAP (Simple Service Access Protocol) on port 3001. Supports TV discovery, PIN-based pairing, remote control, app launching, input switching, Wake-on-LAN, and more.
+
+## Installation
+
+Only Python 3.9+ is required (ships with macOS and most Linux distros).
+
+```bash
+# Clone the repo
+git clone https://github.com/griches/lgtvremote-cli.git
+cd lgtvremote-cli
+
+# Option 1: Add a shell alias (recommended)
+echo 'alias lgtv="python3 '$(pwd)'/lgtvremote_cli.py"' >> ~/.zshrc
+source ~/.zshrc
+
+# Option 2: Symlink into your PATH
+ln -s $(pwd)/lgtvremote_cli.py /usr/local/bin/lgtv
+```
+
+If you don't have Python 3 installed:
+
+| Platform | Install |
+|----------|---------|
+| macOS | `brew install python3` |
+| Ubuntu/Debian | `sudo apt install python3` |
+| Fedora/RHEL | `sudo dnf install python3` |
+| Windows | `winget install Python.Python.3` or [python.org](https://www.python.org/downloads/) |
+
+## Quick Start
+
+```bash
+# 1. Scan, add, and pair — all in one step
+lgtv scan
+# Finds TVs, adds them, asks to pair, fetches MAC addresses for Wake-on-LAN
+
+# 2. Control your TV
+lgtv off                    # Turn off
+lgtv on                     # Wake via Wake-on-LAN
+lgtv launch Netflix         # Launch apps by name
+lgtv volume set 20          # Set volume
+lgtv input 1                # Switch to HDMI 1
+```
+
+Or if you know the IP:
+
+```bash
+lgtv add 192.168.1.100      # Adds, pairs, and fetches MACs automatically
+```
+
+## Configuration
+
+Device data is stored in `~/.config/lgtvremote/devices.json`. This includes IP addresses, names, MAC addresses, and pairing keys.
+
+## Command Reference
+
+### Device Management
+
+| Command | Description |
+|---------|-------------|
+| `lgtv scan` | Discover TVs, auto-add, pair, and fetch MAC addresses |
+| `lgtv add <ip>` | Add a TV by IP — auto-enriches, pairs, and fetches MACs |
+| `lgtv add <ip> --name "Living Room"` | Add with a custom name |
+| `lgtv remove <ip>` | Remove a saved TV |
+| `lgtv list` | List all saved TVs |
+| `lgtv set-default <ip>` | Set the default TV for commands |
+| `lgtv pair` | Re-pair with a TV (if needed) |
+| `lgtv enrich` | Re-fetch model name and MAC addresses from TV |
+
+### Power
+
+| Command | Description |
+|---------|-------------|
+| `lgtv on` | Turn on TV via Wake-on-LAN (requires stored MAC address) |
+| `lgtv off` | Turn off TV |
+| `lgtv power` | Toggle power (off via WebSocket, on via WOL if unreachable) |
+
+### Volume
+
+| Command | Description |
+|---------|-------------|
+| `lgtv volume up` | Volume up |
+| `lgtv volume down` | Volume down |
+| `lgtv volume set <0-100>` | Set volume to specific level |
+| `lgtv volume get` | Get current volume and mute status |
+| `lgtv volume mute` | Mute |
+| `lgtv volume unmute` | Unmute |
+
+### Navigation
+
+| Command | Description |
+|---------|-------------|
+| `lgtv nav up` | Navigate up |
+| `lgtv nav down` | Navigate down |
+| `lgtv nav left` | Navigate left |
+| `lgtv nav right` | Navigate right |
+| `lgtv nav ok` | Select / OK / Enter |
+| `lgtv nav back` | Go back |
+| `lgtv nav home` | Go to home screen |
+| `lgtv nav menu` | Open menu |
+
+### Channels
+
+| Command | Description |
+|---------|-------------|
+| `lgtv channel up` | Next channel |
+| `lgtv channel down` | Previous channel |
+| `lgtv channel set <number>` | Switch to specific channel |
+
+### Media Controls
+
+| Command | Description |
+|---------|-------------|
+| `lgtv play` | Play |
+| `lgtv pause` | Pause |
+| `lgtv stop` | Stop playback |
+| `lgtv rewind` | Rewind |
+| `lgtv ff` | Fast forward |
+| `lgtv skip-forward` | Skip forward / next track |
+| `lgtv skip-back` | Skip backward / previous track |
+
+### Input / HDMI
+
+| Command | Description |
+|---------|-------------|
+| `lgtv input 1` | Switch to HDMI 1 |
+| `lgtv input 2` | Switch to HDMI 2 |
+| `lgtv input HDMI_3` | Switch to HDMI 3 (full ID) |
+| `lgtv inputs` | List all available inputs |
+
+### Apps
+
+Launch any app by its display name — matches against what's installed on your TV:
+
+| Command | Description |
+|---------|-------------|
+| `lgtv launch Netflix` | Launch Netflix |
+| `lgtv launch YouTube` | Launch YouTube |
+| `lgtv launch "Disney+"` | Launch Disney+ |
+| `lgtv launch "Prime Video"` | Launch Prime Video |
+| `lgtv launch Plex` | Launch Plex |
+| `lgtv launch browser` | Launch web browser (shortcut) |
+| `lgtv launch settings` | Open TV settings (shortcut) |
+| `lgtv launch <app-id>` | Launch by webOS app ID |
+| `lgtv apps` | List all installed apps with their IDs |
+| `lgtv app` | Show currently running foreground app |
+
+#### Supported App Shortcuts
+
+| Shortcut | App ID |
+|----------|--------|
+| `netflix` | `netflix` |
+| `youtube` | `youtube.leanback.v4` |
+| `amazon` / `prime` / `primevideo` | `amazon` |
+| `disney` / `disney+` / `disneyplus` | `com.disney.disneyplus-prod` |
+| `hulu` | `hulu` |
+| `hbo` / `hbomax` | `hbo-go-2` |
+| `apple` / `appletv` | `com.apple.tv` |
+| `spotify` | `spotify-beehive` |
+| `plex` | `plex` |
+| `crunchyroll` | `crunchyroll` |
+| `twitch` | `twitch` |
+| `vudu` | `vudu` |
+| `livetv` / `tv` | `com.webos.app.livetv` |
+| `settings` | `com.webos.app.settings` |
+| `browser` | `com.webos.app.browser` |
+
+### Open URL
+
+Send a URL to the TV to open in the built-in webOS browser.
+
+| Command | Description |
+|---------|-------------|
+| `lgtv open-url https://example.com` | Open URL in TV browser |
+| `lgtv open-url example.com` | Scheme is added automatically if omitted |
+
+### Number Keys
+
+| Command | Description |
+|---------|-------------|
+| `lgtv number <0-9>` | Send a number key press |
+
+### Display & Settings (newer TVs only)
+
+These commands use `setSystemSettings` which may not be available on older webOS versions.
+
+| Command | Description |
+|---------|-------------|
+| `lgtv screen-off` | Turn off screen (audio continues) |
+| `lgtv screen-on` | Turn screen back on |
+| `lgtv picture-mode <mode>` | Set picture mode (e.g., standard, vivid, cinema, game) |
+| `lgtv sound-mode <mode>` | Set sound mode (e.g., standard, cinema, game) |
+| `lgtv subtitles` | Toggle subtitles |
+| `lgtv audio-track` | Cycle audio track |
+
+### Service Menus (Advanced)
+
+These menus require a password. The default is usually **0413**. Other common codes: **0000**, **7777**.
+
+| Command | Description |
+|---------|-------------|
+| `lgtv service instart` | Open In-Start service menu |
+| `lgtv service ezadjust` | Open Ez-Adjust menu |
+| `lgtv service hotel` | Open Hotel/Installation mode |
+| `lgtv service hidden` | Open hidden menu |
+| `lgtv service freesync` | Show Freesync info |
+
+### Raw Commands
+
+| Command | Description |
+|---------|-------------|
+| `lgtv raw <ssap-uri>` | Send any SSAP command |
+| `lgtv raw <ssap-uri> --payload '{"key":"value"}'` | Send with JSON payload |
+
+#### Examples
+
+```bash
+# Get system info
+lgtv raw ssap://system/getSystemInfo
+
+# Get software info
+lgtv raw ssap://com.webos.service.update/getCurrentSWInformation
+
+# Set a specific setting
+lgtv raw ssap://com.webos.service.settings/setSystemSettings \
+  --payload '{"category":"picture","settings":{"backlight":80}}'
+```
+
+## Using with Multiple TVs
+
+```bash
+# Add multiple TVs
+lgtv add 192.168.1.100 --name "Living Room"
+lgtv add 192.168.1.101 --name "Bedroom"
+
+# Set default
+lgtv set-default 192.168.1.100
+
+# Commands use default TV
+lgtv off
+
+# Override with --tv flag
+lgtv --tv 192.168.1.101 off
+lgtv --tv 192.168.1.101 launch netflix
+```
+
+## Using with AI Assistants
+
+This CLI is designed to be easily used by AI assistants and automation tools. Run `lgtv -h` for the full command list, or `lgtv <command> -h` for detailed help on any command.
+
+Key patterns:
+- All commands return human-readable output to stdout
+- Errors go to stderr with non-zero exit codes
+- `lgtv apps` and `lgtv inputs` list available options with IDs
+- `lgtv raw` allows sending any SSAP command for capabilities not covered by named commands
+
+## Network Requirements
+
+- Your computer and TV must be on the same local network
+- Port 3001 (WSS) must be accessible for TV control
+- Port 3000 (HTTP) is used for device discovery enrichment
+- Port 1900 (UDP) is used for SSDP discovery
+- Ports 7 and 9 (UDP broadcast) are used for Wake-on-LAN
+
+## License
+
+MIT

lgtvremote_cli-1.0.0/README.md

@@ -0,0 +1,270 @@
+# LG TV Remote CLI
+
+## Command-line interface for controlling LG webOS TVs over your local network.
+
+Communicates via WebSocket using the SSAP (Simple Service Access Protocol) on port 3001. Supports TV discovery, PIN-based pairing, remote control, app launching, input switching, Wake-on-LAN, and more.
+
+## Installation
+
+Only Python 3.9+ is required (ships with macOS and most Linux distros).
+
+```bash
+# Clone the repo
+git clone https://github.com/griches/lgtvremote-cli.git
+cd lgtvremote-cli
+
+# Option 1: Add a shell alias (recommended)
+echo 'alias lgtv="python3 '$(pwd)'/lgtvremote_cli.py"' >> ~/.zshrc
+source ~/.zshrc
+
+# Option 2: Symlink into your PATH
+ln -s $(pwd)/lgtvremote_cli.py /usr/local/bin/lgtv
+```
+
+If you don't have Python 3 installed:
+
+| Platform | Install |
+|----------|---------|
+| macOS | `brew install python3` |
+| Ubuntu/Debian | `sudo apt install python3` |
+| Fedora/RHEL | `sudo dnf install python3` |
+| Windows | `winget install Python.Python.3` or [python.org](https://www.python.org/downloads/) |
+
+## Quick Start
+
+```bash
+# 1. Scan, add, and pair — all in one step
+lgtv scan
+# Finds TVs, adds them, asks to pair, fetches MAC addresses for Wake-on-LAN
+
+# 2. Control your TV
+lgtv off                    # Turn off
+lgtv on                     # Wake via Wake-on-LAN
+lgtv launch Netflix         # Launch apps by name
+lgtv volume set 20          # Set volume
+lgtv input 1                # Switch to HDMI 1
+```
+
+Or if you know the IP:
+
+```bash
+lgtv add 192.168.1.100      # Adds, pairs, and fetches MACs automatically
+```
+
+## Configuration
+
+Device data is stored in `~/.config/lgtvremote/devices.json`. This includes IP addresses, names, MAC addresses, and pairing keys.
+
+## Command Reference
+
+### Device Management
+
+| Command | Description |
+|---------|-------------|
+| `lgtv scan` | Discover TVs, auto-add, pair, and fetch MAC addresses |
+| `lgtv add <ip>` | Add a TV by IP — auto-enriches, pairs, and fetches MACs |
+| `lgtv add <ip> --name "Living Room"` | Add with a custom name |
+| `lgtv remove <ip>` | Remove a saved TV |
+| `lgtv list` | List all saved TVs |
+| `lgtv set-default <ip>` | Set the default TV for commands |
+| `lgtv pair` | Re-pair with a TV (if needed) |
+| `lgtv enrich` | Re-fetch model name and MAC addresses from TV |
+
+### Power
+
+| Command | Description |
+|---------|-------------|
+| `lgtv on` | Turn on TV via Wake-on-LAN (requires stored MAC address) |
+| `lgtv off` | Turn off TV |
+| `lgtv power` | Toggle power (off via WebSocket, on via WOL if unreachable) |
+
+### Volume
+
+| Command | Description |
+|---------|-------------|
+| `lgtv volume up` | Volume up |
+| `lgtv volume down` | Volume down |
+| `lgtv volume set <0-100>` | Set volume to specific level |
+| `lgtv volume get` | Get current volume and mute status |
+| `lgtv volume mute` | Mute |
+| `lgtv volume unmute` | Unmute |
+
+### Navigation
+
+| Command | Description |
+|---------|-------------|
+| `lgtv nav up` | Navigate up |
+| `lgtv nav down` | Navigate down |
+| `lgtv nav left` | Navigate left |
+| `lgtv nav right` | Navigate right |
+| `lgtv nav ok` | Select / OK / Enter |
+| `lgtv nav back` | Go back |
+| `lgtv nav home` | Go to home screen |
+| `lgtv nav menu` | Open menu |
+
+### Channels
+
+| Command | Description |
+|---------|-------------|
+| `lgtv channel up` | Next channel |
+| `lgtv channel down` | Previous channel |
+| `lgtv channel set <number>` | Switch to specific channel |
+
+### Media Controls
+
+| Command | Description |
+|---------|-------------|
+| `lgtv play` | Play |
+| `lgtv pause` | Pause |
+| `lgtv stop` | Stop playback |
+| `lgtv rewind` | Rewind |
+| `lgtv ff` | Fast forward |
+| `lgtv skip-forward` | Skip forward / next track |
+| `lgtv skip-back` | Skip backward / previous track |
+
+### Input / HDMI
+
+| Command | Description |
+|---------|-------------|
+| `lgtv input 1` | Switch to HDMI 1 |
+| `lgtv input 2` | Switch to HDMI 2 |
+| `lgtv input HDMI_3` | Switch to HDMI 3 (full ID) |
+| `lgtv inputs` | List all available inputs |
+
+### Apps
+
+Launch any app by its display name — matches against what's installed on your TV:
+
+| Command | Description |
+|---------|-------------|
+| `lgtv launch Netflix` | Launch Netflix |
+| `lgtv launch YouTube` | Launch YouTube |
+| `lgtv launch "Disney+"` | Launch Disney+ |
+| `lgtv launch "Prime Video"` | Launch Prime Video |
+| `lgtv launch Plex` | Launch Plex |
+| `lgtv launch browser` | Launch web browser (shortcut) |
+| `lgtv launch settings` | Open TV settings (shortcut) |
+| `lgtv launch <app-id>` | Launch by webOS app ID |
+| `lgtv apps` | List all installed apps with their IDs |
+| `lgtv app` | Show currently running foreground app |
+
+#### Supported App Shortcuts
+
+| Shortcut | App ID |
+|----------|--------|
+| `netflix` | `netflix` |
+| `youtube` | `youtube.leanback.v4` |
+| `amazon` / `prime` / `primevideo` | `amazon` |
+| `disney` / `disney+` / `disneyplus` | `com.disney.disneyplus-prod` |
+| `hulu` | `hulu` |
+| `hbo` / `hbomax` | `hbo-go-2` |
+| `apple` / `appletv` | `com.apple.tv` |
+| `spotify` | `spotify-beehive` |
+| `plex` | `plex` |
+| `crunchyroll` | `crunchyroll` |
+| `twitch` | `twitch` |
+| `vudu` | `vudu` |
+| `livetv` / `tv` | `com.webos.app.livetv` |
+| `settings` | `com.webos.app.settings` |
+| `browser` | `com.webos.app.browser` |
+
+### Open URL
+
+Send a URL to the TV to open in the built-in webOS browser.
+
+| Command | Description |
+|---------|-------------|
+| `lgtv open-url https://example.com` | Open URL in TV browser |
+| `lgtv open-url example.com` | Scheme is added automatically if omitted |
+
+### Number Keys
+
+| Command | Description |
+|---------|-------------|
+| `lgtv number <0-9>` | Send a number key press |
+
+### Display & Settings (newer TVs only)
+
+These commands use `setSystemSettings` which may not be available on older webOS versions.
+
+| Command | Description |
+|---------|-------------|
+| `lgtv screen-off` | Turn off screen (audio continues) |
+| `lgtv screen-on` | Turn screen back on |
+| `lgtv picture-mode <mode>` | Set picture mode (e.g., standard, vivid, cinema, game) |
+| `lgtv sound-mode <mode>` | Set sound mode (e.g., standard, cinema, game) |
+| `lgtv subtitles` | Toggle subtitles |
+| `lgtv audio-track` | Cycle audio track |
+
+### Service Menus (Advanced)
+
+These menus require a password. The default is usually **0413**. Other common codes: **0000**, **7777**.
+
+| Command | Description |
+|---------|-------------|
+| `lgtv service instart` | Open In-Start service menu |
+| `lgtv service ezadjust` | Open Ez-Adjust menu |
+| `lgtv service hotel` | Open Hotel/Installation mode |
+| `lgtv service hidden` | Open hidden menu |
+| `lgtv service freesync` | Show Freesync info |
+
+### Raw Commands
+
+| Command | Description |
+|---------|-------------|
+| `lgtv raw <ssap-uri>` | Send any SSAP command |
+| `lgtv raw <ssap-uri> --payload '{"key":"value"}'` | Send with JSON payload |
+
+#### Examples
+
+```bash
+# Get system info
+lgtv raw ssap://system/getSystemInfo
+
+# Get software info
+lgtv raw ssap://com.webos.service.update/getCurrentSWInformation
+
+# Set a specific setting
+lgtv raw ssap://com.webos.service.settings/setSystemSettings \
+  --payload '{"category":"picture","settings":{"backlight":80}}'
+```
+
+## Using with Multiple TVs
+
+```bash
+# Add multiple TVs
+lgtv add 192.168.1.100 --name "Living Room"
+lgtv add 192.168.1.101 --name "Bedroom"
+
+# Set default
+lgtv set-default 192.168.1.100
+
+# Commands use default TV
+lgtv off
+
+# Override with --tv flag
+lgtv --tv 192.168.1.101 off
+lgtv --tv 192.168.1.101 launch netflix
+```
+
+## Using with AI Assistants
+
+This CLI is designed to be easily used by AI assistants and automation tools. Run `lgtv -h` for the full command list, or `lgtv <command> -h` for detailed help on any command.
+
+Key patterns:
+- All commands return human-readable output to stdout
+- Errors go to stderr with non-zero exit codes
+- `lgtv apps` and `lgtv inputs` list available options with IDs
+- `lgtv raw` allows sending any SSAP command for capabilities not covered by named commands
+
+## Network Requirements
+
+- Your computer and TV must be on the same local network
+- Port 3001 (WSS) must be accessible for TV control
+- Port 3000 (HTTP) is used for device discovery enrichment
+- Port 1900 (UDP) is used for SSDP discovery
+- Ports 7 and 9 (UDP broadcast) are used for Wake-on-LAN
+
+## License
+
+MIT