👋 Introduction

gtv drives a Google TV from your terminal. It speaks the Android TV Remote v2 protocol directly — the same channel the official mobile remote uses — so there's no companion app, no cloud account, and nothing left running in the background. Pair once over your local network and the connection is saved for next time.

🧭 Two ways to drive your TV

gtv is built around one idea: the same remote, two surfaces.

• The interactive remote — run gtv with no arguments for a fullscreen terminal UI: D-pad navigation, playback, volume, an app launcher, and a keyboard mode (Tab) that types straight into TV text fields.
• One-shot commands — when you'd rather not open the UI, every action is also a plain command: gtv key up, gtv app youtube, gtv status. Ideal for scripts, hotkeys, and automations.

Both talk to the same paired device — pick whichever fits the moment.

📦 Quick start

npm install -g @kud/gtv-cli   # requires Node.js ≥ 22
gtv                           # discovers + pairs on first run, then opens the remote

📖 What's here

• 🧰 Commands — the full reference: pairing and discovery (pair, discover, switch, devices), diagnostics (status, doctor), and one-shot input (key, app, navigation, and volume).