Control Apple TV, HomePod, and AirPlay devices via pyatv (scan, stream, playback, volume, navigation).
Control Apple TV, HomePod, and AirPlay devices from the command line using atvremote.
--python python3.13 (or any version ≤3.13) when installing.~/.local/bin isn't on your PATH after install, run: pipx ensurepathpython3.13 -m pyatv.scripts.atvremote <command>atvremote scan
atvremote --scan-hosts 10.0.0.50 scan # Scan specific IP (faster)
atvremote --scan-hosts 10.0.0.50,10.0.0.51 scan # Multiple IPs
Returns all discoverable Apple TV, HomePod, and AirPlay devices on the local network with their names, addresses, protocols, and pairing status.
Use -n <name> (device name), -s <ip> (address), or -i <id> (identifier) to target:
atvremote -n "Kitchen" <command>
atvremote -s 10.0.0.50 <command>
atvremote -i AA:BB:CC:DD:EE:FF <command>
atvremote -n "Kitchen" playing # Now playing info (title, artist, album, position, etc.)
atvremote -n "Kitchen" play # Resume playback
atvremote -n "Kitchen" pause # Pause playback (resumable with play)
atvremote -n "Kitchen" play_pause # Toggle play/pause
atvremote -n "Kitchen" stop # Stop playback (ends session, cannot resume)
atvremote -n "Kitchen" next # Next track
atvremote -n "Kitchen" previous # Previous track
atvremote -n "Kitchen" skip_forward # Skip forward (~10-30s, app-dependent)
atvremote -n "Kitchen" skip_backward # Skip backward (~10-30s, app-dependent)
atvremote -n "Kitchen" skip_forward=30 # Skip forward specific seconds
atvremote -n "Kitchen" set_position=120 # Seek to position (seconds)
atvremote -n "Kitchen" set_shuffle=Songs # Shuffle: Off, Songs, Albums
atvremote -n "Kitchen" set_repeat=All # Repeat: Off, Track, All
atvremote -n "Kitchen" volume # Get current volume (0-100)
atvremote -n "Kitchen" set_volume=50 # Set volume (0-100)
atvremote -n "Kitchen" volume_up # Step up (~2.5%)
atvremote -n "Kitchen" volume_down # Step down (~2.5%)
Stream local files or URLs to a device:
atvremote -n "Kitchen" stream_file=/path/to/audio.mp3 # Local file
atvremote -n "Kitchen" play_url=http://example.com/stream.mp3 # Remote URL
Supports common audio formats (MP3, WAV, AAC, FLAC, etc.).
atvremote -n "Apple TV" power_state # Check power state
atvremote -n "Apple TV" turn_on # Wake device
atvremote -n "Apple TV" turn_off # Sleep device
atvremote -n "Apple TV" up # D-pad up
atvremote -n "Apple TV" down # D-pad down
atvremote -n "Apple TV" left # D-pad left
atvremote -n "Apple TV" right # D-pad right
atvremote -n "Apple TV" select # Press select/enter
atvremote -n "Apple TV" menu # Back/menu button
atvremote -n "Apple TV" home # Home button
atvremote -n "Apple TV" home_hold # Long press home (app switcher)
atvremote -n "Apple TV" top_menu # Go to main menu
atvremote -n "Apple TV" control_center # Open control center
atvremote -n "Apple TV" guide # Show EPG/guide
atvremote -n "Apple TV" channel_up # Next channel
atvremote -n "Apple TV" channel_down # Previous channel
atvremote -n "Apple TV" screensaver # Activate screensaver
When a text field is focused:
atvremote -n "Apple TV" text_get # Get current text
atvremote -n "Apple TV" text_set="search query" # Replace text
atvremote -n "Apple TV" text_append=" more" # Append text
atvremote -n "Apple TV" text_clear # Clear text
atvremote -n "Apple TV" app_list # List installed apps
atvremote -n "Apple TV" launch_app=com.apple.TVMusic # Launch by bundle ID or URL
Manage connected audio outputs (e.g. grouping HomePods):
atvremote -n "Apple TV" output_devices # List current output device IDs
atvremote -n "Apple TV" add_output_devices=<device_id> # Add speaker to group
atvremote -n "Apple TV" remove_output_devices=<device_id> # Remove from group
atvremote -n "Apple TV" set_output_devices=<device_id> # Set specific output(s)
Watch for real-time playback changes:
atvremote -n "Kitchen" push_updates # Prints updates as they occur (ENTER to stop)
Some devices (especially Apple TV) require pairing before control:
atvremote -n "Living Room" pair # Pair (follow PIN prompt)
atvremote -n "Living Room" --protocol airplay pair # Pair specific protocol
atvremote wizard # Interactive guided setup
Credentials are stored automatically in ~/.pyatv.conf after pairing.
atvremote -n "Kitchen" device_info # Model, OS version, MAC
atvremote -n "Kitchen" features # List all supported features
atvremote -n "Kitchen" app # Current app playing media
pause/play to suspend and resume. stop ends the session entirely — playback must be restarted from the source (Siri, Home app, etc.)playing command shows media type, title, artist, position, shuffle/repeat state--scan-hosts for faster targeting when you know the device IP