pyatv-cli 1.0.0

Comprehensive Apple TV CLI & TUI remote control powered by pyatv

🍎 pyatv-cli — Apple TV Remote Control

A comprehensive CLI app to control your Apple TV entirely from the terminal. Built on pyatv with beautiful Rich terminal output.

Installation

pip install pyatv-cli

Or install from source:

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

Quick Start

# 1. Discover Apple TVs on your network
atv scan

# 2. Pair with your Apple TV
atv pair

# 3. Control it!
atv power status
atv remote play
atv media info

Commands

Discovery & Setup

Command	Description
atv scan	Discover Apple TVs on your network
atv pair	Pair with an Apple TV (interactive PIN flow)
atv unpair	Remove pairing credentials
atv devices	List all paired devices
atv default <id>	Set default device

Power Control

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

Remote Control (27 commands)

Command	Description
atv remote up/down/left/right	Navigation
atv remote select	Confirm selection
atv remote menu	Back/menu button
atv remote home	Home button
atv remote play/pause/stop	Playback control
atv remote next/previous	Track navigation
atv remote skip-forward/skip-backward	Skip
atv remote set-position <seconds>	Seek to position
atv remote set-shuffle off|songs|albums	Shuffle mode
atv remote set-repeat off|track|all	Repeat mode
atv remote screensaver	Activate screensaver
atv remote guide	Open guide
atv remote control-center	Open control center

Media / Now Playing

Command	Description
atv media info	Show current track info
atv media artwork -o file.png	Download artwork

App Management

Command	Description
atv apps list	List installed apps
atv apps launch <bundle_id>	Launch an app

Audio Control

Command	Description
atv audio get	Show volume level
atv audio set <0-100>	Set volume
atv audio up/down	Adjust volume
atv audio devices	List output devices

Virtual Keyboard

Command	Description
atv keyboard status	Focus state
atv keyboard get	Current text
atv keyboard set <text>	Replace text
atv keyboard append <text>	Append text
atv keyboard clear	Clear text

Touch Gestures

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

Streaming

Command	Description
atv stream url <url>	Stream from URL
atv stream file <path>	Stream local file

System Information

Command	Description
atv system info	Device info
atv system features	Feature support table

User Accounts

Command	Description
atv accounts list	List accounts
atv accounts switch <id>	Switch account

Device Settings

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

Live & Interactive

Command	Description
atv monitor	Real-time playback status (Rich Live)
atv shell	Interactive REPL shell

TUI Mode

Launch a full-screen interactive terminal UI for controlling your Apple TV:

atv tui

The TUI provides a visual remote control with real-time playback status, volume control, and navigation — all in your terminal.

Global Options

Option	Description
--json	Output in JSON format for scripting
--version	Show version
--device <id>	Target specific device
--host <ip>	Connect by IP address

JSON Mode

All commands support --json for scripting:

atv --json scan | jq '.[].name'
atv --json media info | jq '.Title'
atv --json audio get | jq '.volume'

Configuration

Credentials and device config stored at ~/.config/pyatv-cli/config.json.

Publishing

pip install build twine
python -m build
twine upload dist/*

License

MIT