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.
Only Python 3.9+ is required (ships with macOS and most Linux distros).
# Install from PyPI (recommended)
pip install lgtvremote-cli
# Or with pipx (isolated environment, great for CLI tools)
pipx install lgtvremote-cligit clone https://github.com/griches/lgtvremote-cli.git
cd lgtvremote-cli
pip install .Run lgtv pair after upgrading to 1.3.1 — the registration manifest changed, and existing client keys are frozen to their original (more limited) permission set. Re-pairing issues a fresh key under the new manifest.
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 |
# 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 1Or if you know the IP:
lgtv add 192.168.1.100 # Adds, pairs, and fetches MACs automaticallyDevice data is stored in ~/.config/lgtvremote/devices.json. This includes IP addresses, names, MAC addresses, and pairing keys.
| 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-or-name> |
Remove a saved TV (by IP or name) |
lgtv list |
List all saved TVs |
lgtv set-default <ip-or-name> |
Set the default TV for commands (by IP or name) |
lgtv pair |
Re-pair with a TV (if needed) |
lgtv enrich |
Re-fetch model name and MAC addresses from TV |
| 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) |
lgtv power-status |
Check if TV is on or off (JSON output, exit code 1 if off/unreachable) |
| 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 |
| 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 |
| Command | Description |
|---|---|
lgtv livetv |
Switch to Live TV tuner |
lgtv channel up |
Next channel |
lgtv channel down |
Previous channel |
| 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 |
| 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 input PS5 |
Switch by label (case-insensitive) |
lgtv inputs |
List all available inputs (also caches labels) |
lgtv input-alias HDMI_1 PS5 |
Set a custom alias for an input |
lgtv input-alias HDMI_1 |
Remove the alias for an input |
Input labels are automatically cached per TV when you run lgtv inputs or lgtv pair, so you can switch by label name (e.g., lgtv input ps5) without an extra network round-trip. Custom aliases set with input-alias take precedence over TV-reported labels.
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 |
| 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 |
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 |
| Command | Description |
|---|---|
lgtv number <0-9> |
Send a number key press |
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 |
lgtv energy-saving <mode> |
Set energy saving mode (auto, off, min, med, max, screen_off) |
lgtv screenshot [output] |
Capture a 960x540 JPEG screenshot from the TV (saves to screenshot-<timestamp>.jpg by default) |
The SSAP screenshot endpoint is hard-locked to 960x540 JPEG on every webOS version tested (B9, CX, G5). Higher resolutions require Developer Mode or a rooted TV and calling luna://com.webos.service.capture/executeOneShot directly.
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 |
| Command | Description |
|---|---|
lgtv raw <ssap-uri> |
Send any SSAP command |
lgtv raw <ssap-uri> --payload '{"key":"value"}' |
Send with JSON payload |
# 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}}'# 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 (IP or name)
lgtv --tv 192.168.1.101 off
lgtv --tv "Bedroom" launch netflixThis 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 appsandlgtv inputslist available options with IDslgtv rawallows sending any SSAP command for capabilities not covered by named commands
- 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
MIT