Android TV Remote CLI is a Node.js terminal application that lets you drive any Android TV / Google TV device from your keyboard. It bundles encrypted pairing, an interactive menu, and a D-pad mode so you can mute, power toggle, and navigate the operating system without picking up the hardware remote.

• Interactive terminal UI with menu shortcuts for power, mute, home, debug, and exit.
• Non-interactive tvrc config command that prints the settings file location.
• Full keyboard-driven D-pad mode with on-screen guidance and number key support.
• Secure certificate-based pairing; credentials persist between sessions.
• One-time host discovery that stores the Android TV IP address for reuse.
• Optional debug mode to trace every command sent to the TV.
• Build pipeline that produces a single bundled executable (build/tvrc).

• Node.js ≥ 22 (Volta pin: 22.13.1).
• pnpm ≥ 10 (the repo is configured with pnpm).
• Android TV or Google TV device on the same local network with pairing enabled.
• Access to TCP ports 6466 (remote) and 6467 (pairing) between your machine and the TV.
• A TTY-capable terminal for the interactive menu and D-pad mode.

git clone https://github.com/<your-user>/androidtv-remote-cli.git
cd androidtv-remote-cli
pnpm install

If you rely on Volta, the pinned versions in package.json will be picked up automatically. Otherwise ensure your global Node and pnpm versions satisfy the requirements above.

Bundle the CLI into build/tvrc:

pnpm build

The build step runs esbuild, injects a shebang with the current node path, and marks the output executable. Run the bundled binary directly:

./build/tvrc

Copy build/tvrc to a directory on your PATH (for example ~/bin or /usr/local/bin) to invoke tvrc globally without specifying the build folder.

For a one-off session without bundling:

pnpm start

During development you can keep a live TypeScript session with:

pnpm dev

1. Make sure your TV is powered on and reachable on the network (ping it if unsure).
2. Run pnpm start (or ./build/tvrc after a build).
3. When prompted, enter the TV’s IP address. The address is saved via conf so you only do this once.
4. The TV will display a pairing code on screen. Enter the code in the terminal prompt.
5. Pairing certificates are stored in your OS-specific config directory (e.g. ~/Library/Preferences/androidtv/settings.json on macOS, %APPDATA%/androidtv/settings.json on Windows, ~/.config/androidtv/settings.json on Linux). Run tvrc config any time to print the exact path for your machine.

Subsequent launches reuse the stored host and certificate, skipping the prompts unless the TV invalidates them.

You can launch straight into different modes:

./build/tvrc         # Start with the interactive menu
./build/tvrc dpad    # Jump directly to D-pad mode
./build/tvrc help    # Show the help screen first
./build/tvrc config  # Print the config file path and exit

• ↑ / ↓ arrows: Move through menu items.
• Enter: Run the selected command.
• Esc, Ctrl+C, or q: Exit the application.

Each menu item also has an instant shortcut key that runs the action without moving through the list:

Once activated, the terminal renders a virtual remote. Controls:

D-pad and help modes both require a TTY; if one isn’t available the app falls back to the menu and shows a status warning.

Settings persist across runs:

• host: Android TV IP address.
• cert: Pairing certificate and key.

To reset pairing, delete the settings file (see tvrc config for the precise path) and rerun the CLI.

Vitest test files live under tests/ and mirror the src/ structure, covering the interactive UI, pairing flows, and the vendored Android TV remote implementation. Use pnpm test:coverage to audit coverage output in coverage/.

• Pairing fails immediately: Confirm the TV displays a pairing code and that ports 6466/6467 are open.
• TTY errors: Ensure you’re running in an interactive terminal (no piping or background execution).
• Device disconnected mid-session: The remote manager auto-reconnects, but you may need to rerun the CLI if the TV power cycles.
• Need to re-pair: Delete the stored config file (run tvrc config to locate it) and start over.
• Debugging: Toggle the debug option in the menu to see raw event logs in the terminal.

This project builds on androidtvremote2 by TroniKOS. The upstream library is Apache-2.0 licensed; we vendor a modified copy of that package under src/lib/androidtv-remote so we can ship our CLI-specific fixes while we work to upstream them.

If you rely on the vendored code, please review the LICENSE-APACHE terms from the original project.

MIT © Martín M.