# Apple TV Remote for Raycast

URL: https://www.raycast.com/camschroedes/apple-tv-remote

> Control your Apple TV with an on-screen remote, launch apps, type text, sleep or wake it, and use natural-language AI commands.

- Install: raycast://extensions/camschroedes/apple-tv-remote
- Author: [Cameron Schroeder](https://www.raycast.com/camschroedes)
- Installs: 236
- Platforms: macOS
- Categories: Media, Applications, AI Extensions
- Updated: 2026-11-16
- Source: https://github.com/raycast/extensions/tree/3627d9b15ba4506ca8c8ac9d93c4585c5d2ec7ae/extensions/apple-tv-remote/

## Commands

- **Apple TV Remote**: On-screen remote with d-pad, playback, volume, and text input.
- **Ask Apple TV**: One-off natural-language commands: pause, open Netflix, play a show.
- **Set up Apple TV**: Discover and pair with an Apple TV on your network.
- **Launch Apple TV App**: Browse and open apps installed on your Apple TV.
- **Play/Pause**: Toggle playback on your Apple TV.
- **Go to Home Screen**: Jump to the Apple TV home screen.
- **Apple TV Menu Bar**: Quick Apple TV controls from your menu bar.
- **Volume up**: Turn the Apple TV volume up.
- **Volume Down**: Turn the Apple TV volume down.
- **Type Text on Apple TV**: Send text into the focused field on the Apple TV (e.g. a search box).

## AI tools

- **Press Remote Key**: Press a button on the Apple TV remote: up, down, left, right, select, menu (back), home, play_pause, volume_up, volume_down, next, previous.
- **Launch App**: Open an app on the Apple TV by name, e.g. Netflix, YouTube, Disney+.
- **Play Content**: Open a specific show or movie on the Apple TV, optionally in a specific streaming app. Resolves the title to a deep link when possible, otherwise opens the app.
- **Power**: Put the Apple TV to sleep or wake it up.

## README

### Apple TV Remote

Control your Apple TV from Raycast. No Python, no helper apps, nothing to install beyond the extension. It talks to the Apple TV directly over Apple's Companion protocol in pure TypeScript.

![The remote](https://github.com/raycast/extensions/raw/3627d9b15ba4506ca8c8ac9d93c4585c5d2ec7ae/extensions/apple-tv-remote//media/remote.png)

#### Features

- **Apple TV Remote.** A clickable on-screen remote that keeps one live connection open, so every press lands instantly. D-pad, select, back, home, hold-select context menu, app switcher, Control Center, playback, 10-second skip, and typing into TV search fields.
- **Launch Apple TV App.** A grid of the apps on your Apple TV. Open any of them, or save one as a hotkey-able Quicklink.
- **Ask Apple TV.** One-off natural language, like `pause`, `open netflix`, `play severance`, `type stranger things`, or `sleep`.
- **Menu bar.** Quick taps for play/pause, skip, navigation, opening apps, and sleep/wake, plus one click through to the full remote.
- **Per-key hotkey commands.** Every remote function is also its own command (most are off by default). Enable the ones you want and give them global hotkeys.
- **AI tools.** Drive it from Raycast AI, like `@apple-tv-remote pause` or `@apple-tv-remote play Rick and Morty on Netflix` (needs Raycast Pro).

![Every function, one search away](https://github.com/raycast/extensions/raw/3627d9b15ba4506ca8c8ac9d93c4585c5d2ec7ae/extensions/apple-tv-remote//media/commands.png)

#### Setup

1. Run **Set up Apple TV**.
2. Pick your Apple TV from the list, or add it by IP and port if discovery is blocked on your network.
3. Type the 4-digit PIN that appears on the TV.

Pairing is interactive because the Apple TV shows the PIN on screen, which is why setup is a command rather than an extension preference.

#### The remote

Open **Apple TV Remote** and either click the buttons or use the keyboard.

| Control                    | Bare key                             | With ⌥              |
| -------------------------- | ------------------------------------ | ------------------- |
| Navigate                   | `W` `A` `S` `D` (or `H` `J` `K` `L`) | `⌥↑` `⌥↓` `⌥←` `⌥→` |
| Select                     | `F` (or `G`)                         | `⌥↩`                |
| Back                       | `B`                                  | `⌥⌫`                |
| Home                       | `Q`                                  |                     |
| Play/Pause                 | `Space`                              | `⌥P`                |
| Skip 10s                   | `,` / `.`                            |                     |
| Previous / Next            | `[` / `]`                            |                     |
| Context menu (hold select) | `V`                                  |                     |
| App switcher               | `X`                                  |                     |
| Control Center             | `C`                                  |                     |
| Type text on TV            | `T`                                  |                     |
| Screensaver                |                                      | `⌥S`                |

The bare keys work because the view treats your typing as button presses, so no modifiers are needed. Volume has optional hotkey commands (`Volume Up` and `Volume Down`), but they only do anything when the Apple TV controls volume over HDMI-CEC. Most TVs handle volume themselves.

#### Playing a show

`play <title> [on <app>]` looks the title up on JustWatch and opens a real provider deep link where tvOS supports one (Apple TV+, Disney+, Max, YouTube, and others). It does not guess at app IDs. Netflix dropped tvOS deep links in late 2025, so for Netflix and for anything that does not resolve, the extension opens the Apple TV's universal Search and types the title for you, then you pick the result on screen. The **Search Automation** preference sets how far it goes.

#### Preferences

- **Streaming Country.** Two-letter code for the where-to-watch lookup. Leave it blank to detect your Mac's region.
- **Search Automation.** What happens after a title is typed into Apple TV Search: stop there, open the top result (the default), or also press Play. Pressing Play can start the wrong app, since the title page usually lists several.
- **Connection Timeout.** How long a command waits to reach the Apple TV.

#### How it works

The extension speaks Apple's Companion protocol, the same one the iOS Remote uses, straight from Raycast's Node runtime through [`@bharper/atv-js`](https://github.com/bsharper/atvjs), a pure-TypeScript port of [pyatv](https://pyatv.dev). Discovery is Bonjour, pairing is HAP SRP with the on-screen PIN, and the session is chacha20-poly1305 encrypted. App launching, app listing, sleep/wake, Control Center, hold-select, and 10-second skip are built on top of the library in this extension, ported from pyatv's reference implementation.

##### Credential storage

Pairing produces machine-generated key material rather than a password you type, so it lives in Raycast's encrypted [LocalStorage](https://developers.raycast.com/api-reference/storage), scoped to this extension. The extension never touches the macOS Keychain, and it sends nothing off your local network. The only internet request is the optional JustWatch title lookup.

#### Development

```bash
npm install
npm run dev      # ray develop, hot-reloads into Raycast
npm run lint     # ray lint
npm run build    # ray build
```

| Module                                 | Role                                                                                           |
| -------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `src/lib/connection.ts`                | Persistent session for the remote view, plus per-command `withConnection()`                    |
| `src/lib/companion-extras.ts`          | Companion payloads ported from pyatv (launch app, app list, power, Control Center, hold, skip) |
| `src/lib/credentials.ts`, `devices.ts` | Pairing credentials and selected device in LocalStorage                                        |
| `src/lib/justwatch.ts`                 | Title to deep-link resolution (keyless GraphQL, cached)                                        |
| `src/lib/play-flow.ts`                 | Deep link, then universal-search typing, then app launch                                       |
| `src/lib/deep-links.ts`                | Curated app and bundle map, plus installed-app cache                                           |
| `src/lib/errors.ts`                    | Typed errors turned into actionable toasts                                                     |

#### Credits

- [pyatv](https://pyatv.dev) by Pierre Ståhl (MIT). The reference implementation and protocol docs this extension is built on. The Companion payloads for app launching, app listing, power, and gestures are ported from it.
- [`@bharper/atv-js`](https://github.com/bsharper/atvjs) by Brian Harper (MIT). The TypeScript Companion-protocol port, itself derived from pyatv (© Pierre Ståhl).

See [NOTICE](https://github.com/raycast/extensions/raw/3627d9b15ba4506ca8c8ac9d93c4585c5d2ec7ae/extensions/apple-tv-remote//NOTICE) for third-party license details.

#### License

MIT
