{"id":45261665,"url":"https://github.com/skydiver/androidtv-remote-cli","last_synced_at":"2026-02-21T00:27:56.154Z","repository":{"id":318761666,"uuid":"1072548139","full_name":"skydiver/androidtv-remote-cli","owner":"skydiver","description":"Android TV remote control CLI","archived":false,"fork":false,"pushed_at":"2025-12-13T04:19:48.000Z","size":304,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-14T16:39:25.639Z","etag":null,"topics":["android","androidtv","cli","remote","remote-control","smart-tv","tv"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skydiver.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-08T21:58:04.000Z","updated_at":"2025-12-13T04:19:51.000Z","dependencies_parsed_at":"2025-10-15T07:21:53.939Z","dependency_job_id":"944b9fad-446d-4883-8778-96947293bcaf","html_url":"https://github.com/skydiver/androidtv-remote-cli","commit_stats":null,"previous_names":["skydiver/androidtv-remote-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/skydiver/androidtv-remote-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydiver%2Fandroidtv-remote-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydiver%2Fandroidtv-remote-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydiver%2Fandroidtv-remote-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydiver%2Fandroidtv-remote-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skydiver","download_url":"https://codeload.github.com/skydiver/androidtv-remote-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skydiver%2Fandroidtv-remote-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29668685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T00:11:43.526Z","status":"ssl_error","status_checked_at":"2026-02-20T23:52:33.807Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","androidtv","cli","remote","remote-control","smart-tv","tv"],"created_at":"2026-02-21T00:27:53.867Z","updated_at":"2026-02-21T00:27:56.148Z","avatar_url":"https://github.com/skydiver.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Android TV Remote CLI\n\nAndroid 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.\n\n---\n\n## Features\n\n- Interactive terminal UI with menu shortcuts for power, mute, home, debug, and exit.\n- Non-interactive `tvrc config` command that prints the settings file location.\n- Full keyboard-driven D-pad mode with on-screen guidance and number key support.\n- Secure certificate-based pairing; credentials persist between sessions.\n- One-time host discovery that stores the Android TV IP address for reuse.\n- Optional debug mode to trace every command sent to the TV.\n- Build pipeline that produces a single bundled executable (`build/tvrc`).\n\n---\n\n## Requirements\n\n- Node.js ≥ 22 (Volta pin: 22.13.1).\n- pnpm ≥ 10 (the repo is configured with pnpm).\n- Android TV or Google TV device on the same local network with pairing enabled.\n- Access to TCP ports 6466 (remote) and 6467 (pairing) between your machine and the TV.\n- A TTY-capable terminal for the interactive menu and D-pad mode.\n\n---\n\n## Installation\n\n```bash\ngit clone https://github.com/\u003cyour-user\u003e/androidtv-remote-cli.git\ncd androidtv-remote-cli\npnpm install\n```\n\nIf 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.\n\n---\n\n## Building\n\nBundle the CLI into `build/tvrc`:\n\n```bash\npnpm build\n```\n\nThe build step runs esbuild, injects a shebang with the current `node` path, and marks the output executable. Run the bundled binary directly:\n\n```bash\n./build/tvrc\n```\n\nCopy `build/tvrc` to a directory on your `PATH` (for example `~/bin` or `/usr/local/bin`) to invoke `tvrc` globally without specifying the build folder.\n\n---\n\n## Running from Source\n\nFor a one-off session without bundling:\n\n```bash\npnpm start\n```\n\nDuring development you can keep a live TypeScript session with:\n\n```bash\npnpm dev\n```\n\n---\n\n## First-Time Setup \u0026 Pairing\n\n1. Make sure your TV is powered on and reachable on the network (ping it if unsure).\n2. Run `pnpm start` (or `./build/tvrc` after a build).\n3. When prompted, enter the TV’s IP address. The address is saved via [`conf`](https://github.com/sindresorhus/conf) so you only do this once.\n4. The TV will display a pairing code on screen. Enter the code in the terminal prompt.\n5. 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.\n\nSubsequent launches reuse the stored host and certificate, skipping the prompts unless the TV invalidates them.\n\n---\n\n## CLI Usage\n\nYou can launch straight into different modes:\n\n```bash\n./build/tvrc         # Start with the interactive menu\n./build/tvrc dpad    # Jump directly to D-pad mode\n./build/tvrc help    # Show the help screen first\n./build/tvrc config  # Print the config file path and exit\n```\n\n### Main Menu Controls\n\n- `↑` / `↓` arrows: Move through menu items.\n- `Enter`: Run the selected command.\n- `Esc`, `Ctrl+C`, or `q`: Exit the application.\n\nEach menu item also has an instant shortcut key that runs the action without moving through the list:\n\n| Menu Item        | Shortcut | Action                                         |\n| ---------------- | -------- | ---------------------------------------------- |\n| 🎮 D-pad Controls | `D`      | Switch to keyboard-driven remote mode.        |\n| 🏠 Home           | `H`      | Send the HOME command.                         |\n| 🔇 Mute           | `M`      | Toggle mute.                                   |\n| 🔌 Power          | `P`      | Toggle device power.                           |\n| 🐞 Debug          | `G`      | Enable or disable verbose console logging.     |\n| ℹ️ Help           | `I`      | Display in-terminal usage instructions.        |\n| 🚪 Exit           | `E`      | Close the app.                                 |\n\n### D-pad Mode\n\nOnce activated, the terminal renders a virtual remote. Controls:\n\n| Input            | Action                     |\n| ---------------- | -------------------------- |\n| Arrow keys       | D-pad navigation.          |\n| `Enter` / `Space`| Select / OK.               |\n| `Backspace`      | Back.                      |\n| `h`              | Home.                      |\n| `m`              | Mute.                      |\n| `+` / `-`        | Volume up / down.          |\n| `0`–`9`          | Number pad.                |\n| `Esc`            | Return to menu.            |\n| `Ctrl+C`         | Exit the application.      |\n\nD-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.\n\n---\n\n## Stored Configuration\n\nSettings persist across runs:\n\n- `host`: Android TV IP address.\n- `cert`: Pairing certificate and key.\n\nTo reset pairing, delete the settings file (see `tvrc config` for the precise path) and rerun the CLI.\n\n---\n\n## Development Scripts\n\n| Command             | Purpose                                            |\n| ------------------- | -------------------------------------------------- |\n| `pnpm start`        | Run the CLI via TSX (ideal for manual testing).    |\n| `pnpm dev`          | Watch-mode TypeScript execution with hot reload.   |\n| `pnpm build`        | Produce the bundled executable in `build/tvrc`.    |\n| `pnpm clean`        | Remove the `build` directory.                      |\n| `pnpm test`         | Run Vitest suites for CLI, UI, pairing, and remote layers. |\n| `pnpm test:coverage`| Generate a coverage report with Vitest (`coverage/`). |\n| `pnpm lint:check`   | Biome static analysis.                             |\n| `pnpm lint:fix`     | Apply Biome autofixes.                             |\n| `pnpm lint:format`  | Format source files with Biome.                    |\n\nVitest 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/`.\n\n---\n\n## Troubleshooting\n\n- **Pairing fails immediately**: Confirm the TV displays a pairing code and that ports 6466/6467 are open.\n- **TTY errors**: Ensure you’re running in an interactive terminal (no piping or background execution).\n- **Device disconnected mid-session**: The remote manager auto-reconnects, but you may need to rerun the CLI if the TV power cycles.\n- **Need to re-pair**: Delete the stored config file (run `tvrc config` to locate it) and start over.\n- **Debugging**: Toggle the debug option in the menu to see raw event logs in the terminal.\n\n---\n\n## Credits\n\nThis project builds on [`androidtvremote2`](https://github.com/tronikos/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.\n\nIf you rely on the vendored code, please review the [`LICENSE-APACHE`](https://www.apache.org/licenses/LICENSE-2.0) terms from the original project.\n\n\n## License\n\n[MIT](./LICENSE) © Martín M.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskydiver%2Fandroidtv-remote-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskydiver%2Fandroidtv-remote-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskydiver%2Fandroidtv-remote-cli/lists"}