Metadata-Version: 2.4
Name: pyatv-cli
Version: 1.0.0
Summary: Comprehensive Apple TV CLI & TUI remote control powered by pyatv
Author-email: Yigit Konur <yigitkonur@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yigitkonur/pyatv-cli
Project-URL: Repository, https://github.com/yigitkonur/pyatv-cli
Project-URL: Bug Tracker, https://github.com/yigitkonur/pyatv-cli/issues
Project-URL: Documentation, https://github.com/yigitkonur/pyatv-cli#readme
Keywords: apple-tv,remote-control,cli,tui,pyatv,airplay,tvos
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: Multimedia
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyatv>=0.15.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.40.0
Dynamic: license-file

# 🍎 pyatv-cli — Apple TV Remote Control

[![PyPI](https://img.shields.io/pypi/v/pyatv-cli)](https://pypi.org/project/pyatv-cli/)
[![Python](https://img.shields.io/pypi/pyversions/pyatv-cli)](https://pypi.org/project/pyatv-cli/)
[![License](https://img.shields.io/pypi/l/pyatv-cli)](https://github.com/yigitkonur/pyatv-cli/blob/main/LICENSE)

A comprehensive CLI app to control your Apple TV entirely from the terminal. Built on [pyatv](https://github.com/postlund/pyatv) with beautiful Rich terminal output.

## Installation

```bash
pip install pyatv-cli
```

Or install from source:

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

## Quick Start

```bash
# 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:

```bash
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:

```bash
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

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

## License

MIT
