cr-cli

Mirror your iPhone screen into the Kitty terminal via AirPlay, with touch/drag forwarding.

How it works

1. UxPlay (open-source AirPlay server) receives the screen mirror stream from your iPhone
2. UxPlay dumps raw H.264 video to a FIFO pipe
3. ffmpeg decodes the H.264 stream to raw RGB frames
4. cr-cli renders frames in Kitty using the Kitty graphics protocol
5. Mouse clicks and drags in the terminal are translated to touch events and sent to the iPhone via WebDriverAgent

Requirements

• macOS (tested on Apple Silicon)
• Kitty terminal — the only supported terminal
• Rust — 1.85+ (edition 2024)
• Homebrew

Install dependencies

brew install cmake gstreamer ffmpeg libimobiledevice

Setup

1. Clone the repo

git clone https://github.com/user/cr-cli.git
cd cr-cli

2. Build UxPlay from source

git clone https://github.com/FDH2/UxPlay.git
cd UxPlay
cmake .
make
cd ..

This creates ./UxPlay/uxplay which cr-cli expects by default.

Important: After building, open UxPlay/uxplay.cpp and verify the video dump function uses unbuffered writes. Find the fopen call for video dumping and ensure it looks like:

video_dumpfile = fopen(fn.c_str(), "wb");
if (video_dumpfile) {
    setvbuf(video_dumpfile, NULL, _IONBF, 0);
}

Without setvbuf, H.264 data gets stuck in stdio buffers and frames won't reach ffmpeg. Rebuild with make after editing.

3. Set up touch forwarding (optional)

Touch forwarding requires WebDriverAgent running on your iPhone.

git clone https://github.com/appium/WebDriverAgent.git

Then in Xcode:

1. Open WebDriverAgent/WebDriverAgent.xcodeproj
2. Select the WebDriverAgentRunner scheme
3. For both WebDriverAgentRunner and WebDriverAgentLib targets:
   • Go to Signing & Capabilities
   • Set Team to your Apple ID
   • Change Bundle Identifier to something unique (e.g. com.yourname.WebDriverAgentRunner)
4. Select your iPhone as the destination device
5. On your iPhone: Settings > General > VPN & Device Management — trust your developer certificate
6. Hit Cmd+U to build and run the test on your device

WDA runs an HTTP server on the device. Forward the port:

iproxy 8100 8100

Keep both iproxy and the Xcode test running while using cr-cli.

4. Build cr-cli

cargo build --release

Usage

# Basic — mirror only, no touch (defaults to iPhone 15 Pro resolution)
cargo run -- --no-touch

# With touch forwarding (requires WDA + iproxy running)
cargo run

# Specify your device's screen resolution
cargo run -- --screen 1170x2532

# All options
cargo run -- --screen 1179x2556 --fps 30 --name my-phone --wda http://localhost:8100

Options

Flag	Default	Description
--screen WxH	1179x2556	Device screen resolution in pixels
--fps N	30	Frames per second
--name NAME	cr-cli	AirPlay receiver name (shown on iPhone)
--no-touch	off	Disable touch forwarding
--wda URL	http://localhost:8100	WebDriverAgent URL
--uxplay PATH	./UxPlay/uxplay	Path to UxPlay binary

Controls

• Click — tap on the iPhone
• Click + drag — drag on the iPhone (e.g. deploying troops in Clash Royale)
• Ctrl+C — quit

Connecting your iPhone

1. Run cargo run
2. On your iPhone, open Control Center
3. Tap Screen Mirroring
4. Select the AirPlay receiver name (default: cr-cli)

Limitations

• Kitty terminal only — uses the Kitty graphics protocol for pixel-accurate rendering
• macOS only — depends on Homebrew paths and macOS-specific tooling
• Audio requires phone unmuted — make sure your iPhone's silent switch is off
• Touch requires WDA — WebDriverAgent must be running on the iPhone via Xcode, and iproxy must be forwarding port 8100. WDA stops when the Xcode test stops
• Free Apple developer accounts — WDA needs to be re-deployed every 7 days (provisioning profile expiry)

Disclaimer

i don't know if the libraries being used are safe or not... yolo! maybe don't run this on your own, but you've seen me running it on my phone.