apple tv remote control from the terminal. full tui with d-pad, volume, app launcher, and playback controls.
pipx install cli-appletvone-liner (installs pipx + cli-appletv in one shot):
python3 -m pip install --user pipx && python3 -m pipx ensurepath && python3 -m pipx install cli-appletvpip install pipx && pipx ensurepath && pipx install cli-appletvbrew install pipx && pipx ensurepath && pipx install cli-appletvpip install cli-appletvafter install, restart your terminal (or run source ~/.zshrc / source ~/.bashrc) so atv is on your PATH.
atv add # scan network, pair your apple tv (all protocols)
atv # launch the remotethat's it. atv add pairs both companion (remote control) and airplay (now-playing metadata) automatically.
just run atv — it opens the full-screen tui remote:
┌─────────────────────────────────┬──────────────┐
│ ▲ │ Apps │
│ ◄ OK ► │ YouTube │
│ ▼ │ Netflix │
│ │ Spotify │
│ Prev Play Next Stop │ Disney+ │
│ Home Menu Power │ ... │
│ │ │
│ Volume │ │
│ - + Mute │ │
├─────────────────┬───────────────┘ │
│ System │ Log │
│ Living Room │ Connected to Living Room │
│ Apple TV 4K │ Loaded 22 apps │
└─────────────────┴──────────────────────────────┘
| key | action |
|---|---|
| arrows / wasd | d-pad navigation |
| enter / o | select |
| esc / backspace / b | back (menu) |
| h | home |
| space | play/pause |
| s | stop |
| n / p | next / previous |
| + / - | volume up / down |
| 0 | mute toggle |
| P | power on/off |
| ? | help overlay |
| q | quit |
mouse clicks work on all buttons and the apps list.
atv # launch tui (default)
atv add # add/pair apple tv
atv remove # remove paired device
atv scan # discover apple tvs on network
atv power status # check power state
atv remote play # send play command
atv audio up # volume up
atv apps list # list installed apps
atv shell # interactive repl
atv --help # all commandsvolume control uses relative mode (up/down steps) on most setups connected via hdmi. this is a known pyatv limitation — the companion protocol sends HID key events but can't read volume back from hdmi-cec receivers.
the tui handles this with fire-and-forget volume commands (no timeout errors).
- python 3.11+
- apple tv on the same network
mit