Apple TV

Control Apple TV via pyatv. Use for play/pause, navigation, volume, launching apps, power control, and checking what's playing. Triggers on "Apple TV", "TV", "what's playing", "pause TV", "play TV", "turn off TV".

Security Scan

The skill's code, instructions, and requirements are consistent with an Apple TV control utility using pyatv — it only needs local pairing tokens and calls the pyatv/atvremote CLI to talk to devices on your LAN.

Purpose & Capability

Name/description match the included script and README: the skill controls Apple TV via pyatv/atvremote. No unrelated binaries, cloud APIs, or credentials are requested.

Instruction Scope

SKILL.md instructs installing pyatv and performing local pairing, which is appropriate. The instructions and script require a local config file containing companion/airplay credentials; the skill does not attempt to read other system files or external endpoints. Note: credentials are stored as JSON in the user's home directory and the script passes them on the command line to atvremote (visible to local process listings) — a normal tradeoff for this tooling but a local secrecy consideration.

Install Mechanism

No install spec in the registry; SKILL.md suggests installing pyatv via pipx — a reasonable, minimal instruction. There are no downloads from untrusted URLs or archive extraction steps in the skill package.

Credentials

The skill requests no environment variables and only needs locally generated Apple TV pairing credentials stored in a config file. The number and type of secrets (companion/airplay tokens) are proportional to the stated purpose.

Persistence & Privilege

always is false and the skill does not request elevated or persistent platform privileges. It reads/writes only its own config paths and does not modify other skills or global agent settings.

Assessment

This skill appears to do what it says: control Apple TV locally via pyatv/atvremote. Before installing, consider: (1) Pairing generates companion/airplay tokens that are stored in a JSON file under your home directory — protect that file (set restrictive permissions) because those tokens grant control of the device. (2) The script passes credentials on the command line to atvremote, which can make them visible to local users via process listings — run on a trusted machine. (3) Install pyatv with pipx as instructed and verify you trust that package source. (4) The config path referenced in SKILL.md (~/clawd/config/appletv.json) matches one of the script's lookup paths, but the script also checks ~/.config/clawdbot/appletv.json — be aware of which file you populate. If you need stronger protection for credentials, consider storing them in a secure store rather than plaintext JSON. If you want additional assurance, review the included appletv.py source yourself (it is short and straightforward).

Apple TV Control

Control Apple TV via the pyatv library.

Requirements

pipx install pyatv --python python3.11

Note: pyatv requires Python ≤3.13. Python 3.14+ has breaking asyncio changes. Use --python python3.11 or python3.13 with pipx.

Configuration

Config file at ~/clawd/config/appletv.json:

{
  "name": "Living Room",
  "id": "DEVICE_ID",
  "ip": "192.168.x.x",
  "credentials": {
    "companion": "...",
    "airplay": "..."
  }
}

First-Time Pairing

# Find your Apple TV
atvremote scan

# Pair Companion protocol (required)
atvremote --id <DEVICE_ID> --protocol companion pair

# Pair AirPlay protocol (for media)
atvremote --id <DEVICE_ID> --protocol airplay pair

Save the credentials to the config file.

Quick Commands

Status & Playing

scripts/appletv.py status     # Full status with now playing
scripts/appletv.py playing    # What's currently playing

Playback Control

scripts/appletv.py play       # Play/resume
scripts/appletv.py pause      # Pause
scripts/appletv.py stop       # Stop
scripts/appletv.py next       # Next track/chapter
scripts/appletv.py prev       # Previous

Navigation

scripts/appletv.py up         # Navigate up
scripts/appletv.py down       # Navigate down
scripts/appletv.py left       # Navigate left
scripts/appletv.py right      # Navigate right
scripts/appletv.py select     # Press select/OK
scripts/appletv.py menu       # Menu button
scripts/appletv.py home       # Home screen

Volume

scripts/appletv.py volume_up
scripts/appletv.py volume_down

Power

scripts/appletv.py turn_on    # Wake from sleep
scripts/appletv.py turn_off   # Put to sleep
scripts/appletv.py power      # Toggle

Apps

scripts/appletv.py apps       # List installed apps
scripts/appletv.py app Netflix
scripts/appletv.py app YouTube
scripts/appletv.py app "Disney+"

Discovery

scripts/appletv.py scan       # Find Apple TVs on network

Example Interactions

• "What's playing on the TV?" → scripts/appletv.py status
• "Pause the TV" → scripts/appletv.py pause
• "Turn off the Apple TV" → scripts/appletv.py turn_off
• "Open Netflix on TV" → scripts/appletv.py app Netflix