🥽 QuestControl (questctl)

A cross-platform terminal controller and developer companion for Meta Quest headsets (Quest 2, Quest 3, Quest Pro). Built in C# (.NET 10) with Spectre.Console, it provides an interactive Terminal User Interface (TUI) alongside scriptable command-line tooling for rapid app lifecycle management, real-time PC audio broadcasting via scrcpy, and multi-headset IP color-tag synchronization.

---

⚡ Core Functions

• 🔀 Multi-Headset Switching: Switch active headset target seamlessly when multiple Quest devices are connected.
• ⚡ App Lifecycle Management: Real-time foreground app detection, one-click app restart, termination, launching from a searchable package list, or sideloading .apk files.
• 🔊 Live Audio Streaming to PC: Broadcast Quest audio to PC speakers with low latency using scrcpy (supports PC-only redirection or dual PC + Headset playback).
• 🔌 Reset to Port 5555: One-click ADB restart on TCP/IP port 5555 (adb tcpip 5555) so external network tools and web platforms can interface with the headset.
• 🎨 Webplatform IP & Color Mapping: Directly configure and update IP-to-color mappings in simple.webplatform's src/common/constants.ts (supports automatic folder detection and --set-path).
• 🔁 Reboot Device: Safely reboot connected Quest headsets directly from the terminal.

---

📋 Prerequisites

1. .NET 10 SDK: Required to run or compile the source code (Download .NET 10).
2. Meta Quest Headset: Developer Mode & USB debugging enabled.
3. Android Debug Bridge (adb):
   • Windows: Bundled with Android Studio, SideQuest, or Platform-Tools.
   • macOS: brew install android-platform-tools
   • Linux: sudo apt install adb (or your distribution's package manager)
4. scrcpy (Optional, v2.0+): Required only for PC audio streaming:
   • Windows: Download from scrcpy releases
   • macOS: brew install scrcpy
   • Linux: sudo apt install scrcpy

---

🚀 Running from Source (Quick Start)

You can run questctl directly using the .NET CLI without needing to manually build an executable:

1. Clone the repository

git clone https://github.com/<your-username>/QuestControl.git
cd QuestControl

2. Launch Interactive Terminal UI (TUI)

dotnet run

3. Run Direct CLI Commands

Pass any command after --:

# Check headset status
dotnet run -- status

# Restart current foreground app
dotnet run -- restart

# Broadcast audio to PC
dotnet run -- audio

# Set headset to port 5555
dotnet run -- tcpip

---

📦 Building a Standalone Binary

If you want a standalone executable you can put in your PATH (e.g. /usr/local/bin or C:\Tools), publish a single-file self-contained binary for your operating system:

# Windows (x64)
dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o ./publish

# macOS Apple Silicon (M1/M2/M3/M4)
dotnet publish -c Release -r osx-arm64 --self-contained true -p:PublishSingleFile=true -o ./publish

# macOS Intel (x64)
dotnet publish -c Release -r osx-x64 --self-contained true -p:PublishSingleFile=true -o ./publish

# Linux (x64)
dotnet publish -c Release -r linux-x64 --self-contained true -p:PublishSingleFile=true -o ./publish

After publishing, the executable in ./publish/ (questctl.exe on Windows, questctl on macOS/Linux) can be run directly from anywhere:

questctl status
questctl audio --dup

---

💻 CLI Commands Reference

When using the built binary (questctl) or running via source (dotnet run -- <cmd>):

Command	Alias	Description	Example
status	s	View active headset and current foreground package	questctl status
restart [pkg]	r	Restart active app (or specified package)	questctl restart questctl r com.company.app
kill [pkg]	k, stop	Stop active app (or specified package)	questctl kill
run <pkg>	start	Launch an installed application	questctl run com.oculus.browser
list [--all]	ls	List installed apps (--all includes system packages)	questctl list
install <file.apk>	i	Sideload an APK file	questctl install build.apk
tcpip	port5555	Restart ADB on TCP/IP port 5555	questctl tcpip
audio	a	Stream Quest audio to PC speakers	questctl audio
audio --dup	a -d	Stream audio to PC and keep headset audio on	questctl audio --dup
audio --set-path <exe>	a -p	Set custom path to scrcpy executable	questctl audio --set-path "/opt/homebrew/bin/scrcpy"
reboot	—	Reboot the headset	questctl reboot
color list	color ls	List current IP suffix color mappings	questctl color list
color add <ip> <color>	color set	Map IP suffix to color (blue, green, orange, purple, yellow, black)	questctl color add 105 green
color reset	—	Reset color mappings to default (101–106)	questctl color reset
color --set-path <path>	color -p	Set path to simple.webplatform directory	questctl color --set-path "../simple.webplatform"

---

📄 License

This project is licensed under the MIT License.