Metadata-Version: 2.4
Name: pyatv-cli
Version: 1.0.1
Summary: Comprehensive Apple TV CLI & TUI remote control powered by pyatv
Author-email: Yigit Konur <yigitkonur@gmail.com>
License-Expression: 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: 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

<p align="center">
  <h1 align="center">🍎 pyatv-cli</h1>
  <p align="center">
    <strong>The ultimate Apple TV remote control for your terminal</strong>
  </p>
  <p align="center">
    50+ commands · Full-screen TUI · Rich output · JSON scripting
  </p>
  <p align="center">
    <a href="https://pypi.org/project/pyatv-cli/"><img src="https://img.shields.io/pypi/v/pyatv-cli?color=blue&label=PyPI" alt="PyPI"></a>
    <a href="https://pypi.org/project/pyatv-cli/"><img src="https://img.shields.io/pypi/pyversions/pyatv-cli?color=blue" alt="Python"></a>
    <a href="https://github.com/yigitkonur/pyatv-cli/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/pyatv-cli?color=green" alt="License"></a>
    <a href="https://pypi.org/project/pyatv-cli/"><img src="https://img.shields.io/pypi/dm/pyatv-cli?color=orange" alt="Downloads"></a>
  </p>
</p>

---

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](https://github.com/postlund/pyatv) with gorgeous [Rich](https://github.com/Textualize/rich) output and a full-screen [Textual](https://github.com/Textualize/textual) TUI.

---

## 📖 Table of Contents

- [✨ Feature Highlights](#-feature-highlights)
- [🤔 Why pyatv-cli?](#-why-pyatv-cli)
- [👀 Preview](#-preview)
- [📦 Installation](#-installation)
- [🚀 Quick Start](#-quick-start)
- [📚 Complete Command Reference](#-complete-command-reference)
- [🖥️ TUI Mode](#️-tui-mode)
- [🔧 JSON Scripting](#-json-scripting)
- [⚙️ Configuration](#️-configuration)
- [📡 Protocol Support](#-protocol-support)
- [🔍 Troubleshooting](#-troubleshooting)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
- [🙏 Credits](#-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

### From PyPI (recommended)

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

### With pipx (isolated install)

```bash
pipx install pyatv-cli
```

### From source

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

```bash
atv scan
```

### 2️⃣ Pair with your Apple TV

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

### 3️⃣ Start controlling!

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

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

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

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

```json
{
  "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

```bash
# 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](https://github.com/postlund/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

```bash
# 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](https://github.com/yigitkonur/pyatv-cli/issues).

---

## 📄 License

MIT License — see [MIT](https://github.com/yigitkonur/pyatv-cli/blob/main/LICENSE) for details.

---

## 🙏 Credits

Built on the shoulders of these excellent projects:

| Project | Role |
|---------|------|
| [pyatv](https://github.com/postlund/pyatv) | Core Apple TV protocol library — the engine behind everything |
| [Click](https://click.palletsprojects.com/) | CLI framework powering all 50+ commands |
| [Rich](https://github.com/Textualize/rich) | Beautiful terminal output — tables, panels, colors |
| [Textual](https://github.com/Textualize/textual) | Full-screen TUI framework for the interactive mode |

---

<p align="center">
  Made with ❤️ by <a href="https://github.com/yigitkonur">Yigit Konur</a>
</p>
