pyatv-cli 1.0.4

Comprehensive Apple TV CLI & TUI remote control powered by pyatv

🍎 pyatv-cli

The ultimate Apple TV remote control for your terminal

50+ commands · Full-screen TUI · Rich output · JSON scripting

---

Control your Apple TV entirely from the terminal. Power, remote, media, apps, audio, streaming, touch gestures — everything your Siri Remote can do, atv can do better. Built on pyatv with gorgeous Rich output and a full-screen Textual TUI.

---

📖 Table of Contents

• ✨ Feature Highlights
• 🤔 Why pyatv-cli?
• 👀 Preview
• 📦 Installation
• 🚀 Quick Start
• 📚 Complete Command Reference
• 🖥️ TUI Mode
• 🔧 JSON Scripting
• ⚙️ Configuration
• 📡 Protocol Support
• 🔍 Troubleshooting
• 🤝 Contributing
• 📄 License
• 🙏 Credits

---

✨ Feature Highlights

• 🎮 50+ commands across 13 command groups — power, remote, media, apps, audio, keyboard, touch, stream, system, accounts, monitor, settings, shell
• 🖥️ Full-screen TUI — A beautiful Textual-based terminal UI with live-updating now-playing, volume control, and remote buttons
• 🔍 Auto-discovery — Find every Apple TV on your network with one command
• 🔗 Interactive pairing — Guided PIN-based pairing flow, credentials saved automatically
• 📊 Rich terminal output — Beautiful tables, panels, and formatted text via Rich
• 🤖 JSON mode — Pipe --json output to jq for scripting and automation
• 📺 Real-time monitor — Live-updating now-playing display with Rich Live
• 🐚 Interactive shell — REPL mode for rapid-fire commands
• 🌐 AirPlay streaming — Stream URLs and local files to your TV
• 👆 Touch gestures — Swipes, taps, double-taps, and long presses
• ⌨️ Virtual keyboard — Type text directly into Apple TV search fields
• 💾 Multi-device support — Pair and switch between multiple Apple TVs
• 🐍 Python 3.10–3.14 — Runs on modern Python with zero configuration

---

🤔 Why pyatv-cli?

If you've used atvremote (the built-in CLI from pyatv), you'll appreciate what pyatv-cli brings to the table:

Feature	atvremote	pyatv-cli
Beautiful Rich output	❌	✅
Full-screen TUI	❌	✅
Credential persistence	❌	✅
Multi-device management	❌	✅
JSON output for scripting	❌	✅
Interactive shell (REPL)	❌	✅
Touch gesture commands	❌	✅
Organized command groups	❌	✅
One-word atv command	❌	✅

---

👀 Preview

Scan Output

$ atv scan
ℹ Scanning for Apple TVs (timeout: 5s)...

                  🍎 Discovered Apple TVs
┌──────────────────┬───────────────┬──────────┬──────────────┐
│ Name             │ Address       │ Model    │ Services     │
├──────────────────┼───────────────┼──────────┼──────────────┤
│ Living Room      │ 192.168.1.50  │ AppleTV4K│ MRP, AirPlay │
│ Bedroom TV       │ 192.168.1.51  │ AppleTV4K│ MRP, AirPlay │
└──────────────────┴───────────────┴──────────┴──────────────┘

Found 2 device(s). Use atv pair to pair.

Now Playing

$ atv media info
╭──────────────── 🎵 Now Playing ─────────────────╮
│  Title:     Bohemian Rhapsody                    │
│  Artist:    Queen                                │
│  Album:     A Night at the Opera                 │
│  State:     ▶️  Playing                           │
│  Position:  2:31 / 5:55                          │
│  App:       Apple Music                          │
╰──────────────────────────────────────────────────╯

TUI Mode

$ atv tui
╭─────────────────── 🍎 Apple TV Remote ───────────────────╮
│                                                          │
│  🎵 Bohemian Rhapsody              ▶️  Playing            │
│  🎤 Queen                                                │
│  💿 A Night at the Opera                                 │
│  ████████████░░░░░░░░░░░░░░  2:31 / 5:55                │
│                                                          │
│          ┌──────┐                                        │
│          │  ▲   │                                        │
│     ┌────┤  OK  ├────┐                                   │
│     │ ◀  │      │ ▶  │                                   │
│     └────┤  ▼   ├────┘                                   │
│          └──────┘                                        │
│                                                          │
│  [⏮] [⏪] [⏯] [⏩] [⏭]     🔈 ━━━━━━━━━░░░ 72%       │
│                                                          │
╰─── q:Quit  Space:Play/Pause  h:Home  Esc:Menu ──────────╯

---

📦 Installation

Recommended: pipx (one command, works everywhere)

# If you don't have pipx yet:
brew install pipx && pipx ensurepath   # macOS
# sudo apt install pipx && pipx ensurepath  # Linux

# Install pyatv-cli globally:
pipx install pyatv-cli

Why pipx? It installs CLI apps in isolated environments — no dependency conflicts, no externally-managed-environment errors, no sudo. Just works. Learn more →

One-liner (macOS)

brew install pipx && pipx ensurepath && pipx install pyatv-cli

Alternative: pip with virtual environment

python3 -m venv ~/.venvs/atv && source ~/.venvs/atv/bin/activate && pip install pyatv-cli

From source (for development)

git clone https://github.com/yigitkonur/pyatv-cli.git
cd pyatv-cli
pip install -e .

Requires Python 3.10+. Dependencies (pyatv, click, rich, textual) are installed automatically.

---

🚀 Quick Start

Get up and running in three steps:

1️⃣ Discover Apple TVs on your network

atv scan

2️⃣ Pair with your Apple TV

atv pair
# A PIN will appear on your TV — enter it when prompted

3️⃣ Start controlling!

# Check power state
atv power status

# Play / pause
atv remote play-pause

# See what's playing
atv media info

# Launch an app
atv apps launch com.apple.TVMusic

# Open the full TUI
atv tui

---

📚 Complete Command Reference

🔍 Discovery & Setup

Command	Description
atv scan	Discover Apple TVs on your network
atv scan --host 192.168.1.50	Scan a specific IP address
atv scan --timeout 10	Custom scan timeout (default: 5s)
atv pair	Pair with an Apple TV (interactive PIN flow)
atv pair --protocol airplay	Pair using a specific protocol
atv unpair --protocol companion	Remove credentials for a protocol
atv unpair --all	Remove device entirely
atv devices	List all paired devices
atv default <id>	Set the default device
atv default	Show current default device

⚡ Power Control

Command	Description
atv power status	Show current power state
atv power on	Turn on
atv power off	Turn off
atv power toggle	Toggle power state

🎮 Remote Control

Full Siri Remote emulation with 27 commands:

Command	Description
atv remote up	Navigate up
atv remote down	Navigate down
atv remote left	Navigate left
atv remote right	Navigate right
atv remote select	Confirm selection (OK)
atv remote menu	Menu / Back
atv remote home	Home button
atv remote home-hold	Long-press Home
atv remote top-menu	Top menu
atv remote play	Play
atv remote pause	Pause
atv remote stop	Stop
atv remote play-pause	Toggle play/pause
atv remote next	Next track
atv remote previous	Previous track
atv remote skip-forward	Skip forward
atv remote skip-backward	Skip backward
atv remote volume-up	Volume up
atv remote volume-down	Volume down
atv remote channel-up	Channel up
atv remote channel-down	Channel down
atv remote screensaver	Activate screensaver
atv remote guide	Open guide
atv remote control-center	Open Control Center
atv remote set-position <sec>	Seek to position (seconds)
atv remote set-shuffle off|songs|albums	Set shuffle mode
atv remote set-repeat off|track|all	Set repeat mode

🎵 Media / Now Playing

Command	Description
atv media info	Show current track info (title, artist, album, state, position)
atv media artwork -o cover.png	Download current artwork to a file (-w/--width, --height to resize)

📱 App Management

Command	Description
atv apps list	List installed apps (name + bundle ID)
atv apps launch <bundle_id>	Launch an app by bundle identifier

🔊 Audio Control

Command	Description
atv audio get	Show current volume level
atv audio set <0-100>	Set volume to a specific level
atv audio up	Increase volume
atv audio down	Decrease volume
atv audio devices	List audio output devices

⌨️ Virtual Keyboard

Command	Description
atv keyboard status	Check if keyboard is focused
atv keyboard get	Get current text in the field
atv keyboard set <text>	Replace text in the field
atv keyboard append <text>	Append text to the field
atv keyboard clear	Clear the text field

👆 Touch Gestures

Command	Description
atv touch swipe up|down|left|right	Directional swipe gesture
atv touch swipe-custom <x1> <y1> <x2> <y2>	Custom swipe between coordinates
atv touch tap	Single tap
atv touch double-tap	Double tap
atv touch hold	Long press

🌐 Streaming

Command	Description
atv stream url <url>	Stream media from a URL
atv stream file <path>	Stream a local file via AirPlay

💻 System Information

Command	Description
atv system info	Show device info (model, OS, version)
atv system features	List supported features with status table

👤 User Accounts

Command	Description
atv accounts list	List user accounts on the device
atv accounts switch <id>	Switch to a different account

📊 Live Monitoring

Command	Description
atv monitor	Real-time now-playing display with Rich Live (Ctrl+C to stop)

⚙️ Settings

Command	Description
atv settings show	Show current configuration
atv settings set <key> <value>	Change a setting
atv settings remove <key>	Remove a setting

🐚 Interactive Shell

Command	Description
atv shell	Launch interactive REPL for rapid-fire commands

🌍 Global Options

Option	Description
--json	Output in JSON format for scripting and piping
--version	Show version number

Note: --device <id> and --host <ip> are not global options — they are available on most subcommands to target a specific paired device or connect by IP address.

---

🖥️ TUI Mode

Launch a full-screen interactive terminal UI to control your Apple TV:

atv tui

The TUI provides:

• 🎵 Live now-playing panel — Title, artist, album, progress bar updated in real-time
• 🎮 Visual remote control — On-screen directional pad and media buttons
• 🔊 Volume control — Real-time volume indicator
• 📱 App info — See which app is currently running
• 🎨 Dark/light theme — Toggle with d

⌨️ Keyboard Shortcuts

Key	Action
↑ ↓ ← →	Navigate
Enter	Select / OK
Space	Play / Pause
Esc or m	Menu / Back
h	Home
n	Next track
p	Previous track
]	Volume up
[	Volume down
d	Toggle dark/light theme
q	Quit TUI

---

🔧 JSON Scripting

Every command supports --json for easy scripting and automation:

# Get all device names on your network
atv --json scan | jq '.[].name'

# Get the currently playing song title
atv --json media info | jq -r '.Title'

# Get volume as a number
atv --json audio get | jq '.volume'

# List all app bundle IDs
atv --json apps list | jq '.[].identifier'

# Check if the TV is on
atv --json power status | jq -r '.power_state'

Automation Examples

# Turn off TV at midnight (cron)
0 0 * * * /usr/local/bin/atv power off

# Play/pause from a Stream Deck or shortcut
atv remote play-pause

# Build a dashboard with watch
watch -n 2 'atv --json media info | jq "{title: .Title, artist: .Artist, state: .State}"'

# Notify when song changes (macOS)
while true; do
  TITLE=$(atv --json media info | jq -r '.Title // empty')
  [ -n "$TITLE" ] && osascript -e "display notification \"$TITLE\" with title \"Now Playing\""
  sleep 10
done

---

⚙️ Configuration

Config File Location

Credentials and device settings are persisted at:

~/.config/pyatv-cli/config.json

Config Structure

{
  "default_device": "AA:BB:CC:DD:EE:FF",
  "devices": {
    "AA:BB:CC:DD:EE:FF": {
      "name": "Living Room",
      "address": "192.168.1.50",
      "identifier": "AA:BB:CC:DD:EE:FF",
      "credentials": {
        "companion": "...",
        "airplay": "..."
      }
    }
  }
}

Multi-Device Support

# Pair multiple devices
atv pair --host 192.168.1.50
atv pair --host 192.168.1.51

# Switch default device
atv default <device-id>

# Target a specific device for one command
atv --device <device-id> power on
atv --host 192.168.1.51 remote play

---

📡 Protocol Support

pyatv-cli supports all four Apple TV protocols via pyatv:

Protocol	What It Unlocks
Companion	Remote control commands, app launching, power management, keyboard input — the primary protocol for tvOS control
AirPlay	Media streaming (URLs, local files), artwork, audio routing
MRP (Media Remote Protocol)	Now-playing info, playback control, volume, media metadata
RAOP (Remote Audio Output Protocol)	Audio-only streaming to AirPlay speakers and Apple TVs

Pairing by Protocol

# Pair Companion (recommended first)
atv pair --protocol companion

# Pair AirPlay (for streaming)
atv pair --protocol airplay

# Check which protocols are paired
atv devices

Tip: Pair with Companion first — it covers most commands. Add AirPlay if you need streaming.

---

🔍 Troubleshooting

Device not found during scan

⚠ No Apple TVs found.

• Ensure your Apple TV and computer are on the same network and subnet
• Check that your Apple TV is powered on (not just in standby for first-time discovery)
• Try scanning a specific IP: atv scan --host 192.168.1.50
• Increase timeout: atv scan --timeout 15
• Make sure multicast/mDNS traffic isn't blocked by your router or firewall

Pairing fails or PIN not appearing

• Restart the pairing: atv pair
• Try a different protocol: atv pair --protocol airplay
• On your Apple TV: Settings → Remotes and Devices → Remote App and Devices — ensure it's set to allow pairing
• Restart your Apple TV and try again

"Feature unavailable" errors

• Some features require specific protocols — pair with Companion and AirPlay
• Check supported features: atv system features
• Certain features only work while media is actively playing

Connection drops or timeouts

• Apple TVs can be slow to respond from standby — try atv power on first
• Ensure no other remote apps are conflicting
• Re-pair if credentials become stale: atv unpair --all && atv pair

---

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Found a bug or have a feature request? Open an issue.

---

📄 License

MIT License — see MIT for details.

---

🙏 Credits

Built on the shoulders of these excellent projects:

Project	Role
pyatv	Core Apple TV protocol library — the engine behind everything
Click	CLI framework powering all 50+ commands
Rich	Beautiful terminal output — tables, panels, colors
Textual	Full-screen TUI framework for the interactive mode

---

Made with ❤️ by Yigit Konur