CLI Reference

April 3, 2026 · View on GitHub

Complete reference for all stv commands.

Run stv --help or stv <command> --help for inline help.

Global Options

Option	Default	Description
`--format [text\|json]`	`text`	Output format for commands that return data
`--tv NAME`	primary	Target TV name (for multi-TV setups)
`--all`		Target all configured TVs (sync mode)
`--group NAME` / `-g NAME`		Target a TV group (sync mode)

--all and --group work with: play, off, on, volume, mute, notify.

Setup & Diagnostics

`stv setup [--ip IP]`

Interactive wizard. Discovers TVs on the network (SSDP), handles pairing, and writes ~/.config/smartest-tv/config.toml.

stv setup                    # auto-discovery
stv setup --ip 192.168.1.100 # direct IP, skip discovery

`stv doctor`

Checks connectivity, queries TV status, and verifies Netflix/YouTube/Spotify apps are installed.

`stv serve`

Start stv as a remote MCP server + REST API for party mode.

stv serve                               # MCP :8910, API :8911
stv serve --host 0.0.0.0 --port 8910    # expose to network
stv serve --transport streamable-http

The REST API (port+1) enables remote TV control from friends. See Sync & Party Mode.

Power

`stv on`

Turn on the TV via Wake-on-LAN (requires mac in config).

`stv off`

Put the TV into standby.

Volume

`stv volume [LEVEL]`

Get current volume (no argument) or set to LEVEL (0–100).

stv volume         # print current volume + mute state
stv volume 30      # set to 30

`stv mute`

Toggle mute on/off.

Apps

`stv launch APP [CONTENT_ID]`

Launch an app. Pass CONTENT_ID for deep linking.

stv launch netflix
stv launch netflix 82656797      # deep link to episode
stv launch youtube dQw4w9WgXcQ   # deep link to video

APP accepts friendly names: netflix, youtube, spotify, disney, prime, appletv, hulu, tving, wavve, coupang, browser, hdmi1, hdmi2.

`stv close APP`

Close a running app.

`stv apps`

List all installed apps (id + name).

Media Playback

`stv play`

Resume playback (sends Play key).

`stv pause`

Pause playback (sends Pause key).

Status

`stv status`

Show current TV state: platform, current app, volume, mute, sound output.

`stv info`

Show system info: platform, model, firmware, IP, name.

Notifications

`stv notify MESSAGE`

Show a toast notification on the TV screen.

What's On

`stv whats-on [PLATFORM] [-n LIMIT]`

Show trending content on Netflix or YouTube.

stv whats-on
stv whats-on netflix
stv whats-on youtube
stv whats-on netflix -n 5

PLATFORM: netflix, youtube (or omit for both)

Content Search

`stv search PLATFORM QUERY`

Search for content and show what stv found (does not play anything).

stv search netflix Frieren
stv search spotify "Ye White Lines"
stv search youtube "baby shark"

PLATFORM: netflix, youtube, spotify

Content Resolution

`stv resolve PLATFORM QUERY [OPTIONS]`

Resolve a content name to a platform-specific ID without playing it.

stv resolve netflix Frieren -s 2 -e 8
stv resolve netflix Frieren s2e8            # inline S/E notation
stv resolve youtube "baby shark"
stv resolve netflix "The Glory" --title-id 81519223 -s 1 -e 1

Options:

Option	Description
`-s, --season INT`	Season number (Netflix)
`-e, --episode INT`	Episode number (Netflix)
`--title-id INT`	Netflix title ID — skips web search

Inline S/E notation — append to the query as the last argument:

Format	Example	Result
`sNeM`	`s2e8`	season=2, episode=8
`SNNEM` (zero-padded)	`S02E08`	season=2, episode=8
`NxM`	`2x8`	season=2, episode=8

Play Content

`stv play PLATFORM QUERY [OPTIONS]`

Resolve content and play it on TV in one step.

stv play netflix Frieren s2e8
stv play netflix Frieren -s 2 -e 8 --title-id 81726714
stv play youtube "baby shark"
stv play spotify "spotify:album:5poA9SAx0Xiz1cd17fWBLS"

Same options as stv resolve. For Netflix, automatically closes the app first (required for deep links to work), then relaunches with the content ID. Records the play to local history.

Cast

`stv cast URL`

Cast a streaming URL to the TV. Accepts Netflix, YouTube, and Spotify links.

stv cast https://www.netflix.com/watch/82656797
stv cast https://www.netflix.com/title/81726714
stv cast https://www.youtube.com/watch?v=dQw4w9WgXcQ
stv cast https://youtu.be/dQw4w9WgXcQ
stv cast https://open.spotify.com/track/3bbjDFVu9BtFtGD2fZpVfz

Netflix /title/ URLs are resolved to an episode ID automatically.

History

`stv history [-n LIMIT]`

Show recent play history. Default limit: 10.

stv history
stv history -n 5

`stv next [QUERY]`

Play the next episode of a Netflix show based on history.

stv next Frieren    # next episode after last watched Frieren
stv next            # continues most recently watched Netflix show

Cache Management

`stv cache set PLATFORM QUERY [OPTIONS]`

Save a content ID to the local cache manually.

# Netflix season data
stv cache set netflix "Frieren" -s 2 --first-ep-id 82656790 --count 10 --title-id 81726714

# Direct ID (YouTube/Spotify)
stv cache set youtube "baby shark" --content-id XqZsoesa55w
stv cache set spotify "Ye Vultures" --content-id "spotify:album:xxx"

Option	Description
`-s, --season INT`	Season number
`--first-ep-id INT`	First episode videoId of the season
`--count INT`	Number of episodes in the season
`--title-id INT`	Netflix title ID
`--content-id STR`	Direct content ID (YouTube/Spotify)

`stv cache get PLATFORM QUERY [OPTIONS]`

Look up a cached content ID.

stv cache get netflix Frieren -s 2 -e 8
stv cache get youtube "baby shark"

`stv cache show`

Print the full contents of the local cache JSON.

`stv cache contribute`

Print local cache in community-cache.json format (history stripped). Pipe to a file to submit a PR.

Groups

`stv group create NAME MEMBER [MEMBER ...]`

Create a TV group for sync playback.

stv group create party living-room bedroom
stv group create watch-party living-room friend-jake

stv multi add friend --platform remote --url http://203.0.113.50:8911

stv --all play netflix "Squid Game" s2e3         # every TV
stv --group party play youtube "lo-fi beats"     # group of TVs
stv --all volume 20                               # set volume everywhere
stv --all off                                     # turn off everything
stv --group home notify "Dinner's ready!"        # toast on group

Content is resolved once, then launched on all targets concurrently. One TV failing does not stop the others. See Sync & Party Mode for the full guide.