scrcpy-cli

A command-line interface and background daemon for controlling Android devices with ADB and scrcpy.

scrcpy-cli can run commands directly through ADB, or route them through a long-lived daemon that keeps a scrcpy control session open. The daemon path avoids spawning a new ADB shell for every action, making repeated taps, key events, swipes, clipboard operations, and screenshots much faster.

Features

• Fast daemon mode: Keep a scrcpy session open for low-latency control and capture.
• ADB fallback: Commands automatically fall back to direct ADB when the daemon is offline.
• Device automation commands: Tap, swipe, scroll, type text, press keys, capture screenshots, dump UI XML, and manage apps.
• Clipboard support: Uses scrcpy clipboard messages when possible, with ADB fallback.
• Workspace config: Read defaults from .scrcpyrc or .env in the current directory or a parent directory.
• Multi-device friendly: Use --serial, ANDROID_SERIAL, or workspace config to target a specific device.

Prerequisites

| Requirement | Why | Verify | | --- | --- | --- | | Node.js 22+ | Runs the CLI | node --version | | ADB / Android Platform Tools | Talks to Android devices | adb version | | Android device with USB debugging | Target device | adb devices |

Note: You do not need to install the desktop scrcpy client! The official scrcpy-server binary is bundled directly with scrcpy-cli and automatically downloaded from GitHub Releases if missing.

Installation

npm install -g @impeterwayne/scrcpy-cli

Quick Start

# Confirm your device is visible
adb devices

# Start the fast background session
scrcpy-cli daemon start

# Run actions
scrcpy-cli tap 500 1200
scrcpy-cli key HOME
scrcpy-cli screenshot screen.png

# Stop the daemon when done
scrcpy-cli daemon stop

If the daemon is not running, action commands still run through direct ADB where possible.

Usage

scrcpy-cli [options] <command> [args]

Global Options

| Option | Description | | --- | --- | | -s, --serial <serial> | Target Android device serial | | --port <port> | Daemon port, default 27184 | | --max-size <size> | Maximum scrcpy video size | | --max-fps <fps> | Maximum scrcpy video FPS | | --video-bit-rate <rate> | scrcpy video bitrate | | --video-encoder <encoder> | scrcpy video encoder | | -h, --help | Show help |

Daemon Commands

| Command | Description | | --- | --- | | scrcpy-cli daemon start | Start the daemon in the background | | scrcpy-cli daemon run | Run the daemon in the foreground | | scrcpy-cli daemon status | Check whether the daemon is running | | scrcpy-cli daemon stop | Stop the daemon and active sessions |

Examples:

scrcpy-cli daemon start --serial emulator-5554 --max-size 1280 --max-fps 60
scrcpy-cli daemon status
scrcpy-cli daemon stop

Action Commands

These commands prefer the daemon when it is active and fall back to ADB when possible.

| Command | Usage | Description | | --- | --- | --- | | mirror | scrcpy-cli mirror [scrcpy-args] | Launch official desktop scrcpy screen mirror window | | tap | scrcpy-cli tap <x> <y> | Tap screen coordinates | | swipe | scrcpy-cli swipe <x1> <y1> <x2> <y2> [duration] | Swipe between coordinates; duration defaults to 300 ms | | write | scrcpy-cli write <text> | Type text into the focused field | | key | scrcpy-cli key <keycode> | Press an Android keycode or friendly key name | | scroll | scrcpy-cli scroll <x> <y> <dx> <dy> | Scroll at a screen coordinate | | screenshot | scrcpy-cli screenshot [file] | Save a screenshot; default screenshot.png | | ui-dump | scrcpy-cli ui-dump [file] | Save UI hierarchy XML; default ui-dump.xml | | clipboard-get | scrcpy-cli clipboard-get | Read device clipboard text | | clipboard-set | scrcpy-cli clipboard-set <text> | Set device clipboard text | | app-start | scrcpy-cli app-start <package> | Launch an app; prefix with + to force-stop first | | app-stop | scrcpy-cli app-stop <package> | Force-stop an app | | app-list | scrcpy-cli app-list | List installed package names | | device-info | scrcpy-cli device-info | Show model, Android version, SDK, and screen size | | device-list | scrcpy-cli device-list | List connected Android devices |

Supported Key Names

The key command accepts numeric Android keycodes or these friendly names:

HOME, BACK, CALL, END_CALL, VOLUME_UP, VOLUME_DOWN, POWER, CAMERA,
ENTER, DELETE, TAB, MENU, APP_SWITCH, DPAD_UP, DPAD_DOWN,
DPAD_LEFT, DPAD_RIGHT, DPAD_CENTER, WAKEUP, SLEEP,
MEDIA_PLAY_PAUSE, MEDIA_NEXT, MEDIA_PREVIOUS,
BRIGHTNESS_UP, BRIGHTNESS_DOWN, NOTIFICATION

Examples:

scrcpy-cli key HOME
scrcpy-cli key back
scrcpy-cli key 26

Configuration

scrcpy-cli looks for .scrcpyrc or .env in the current directory, then walks up parent directories until it finds config. CLI flags override config values.

.scrcpyrc

{
  "serial": "emulator-5554",
  "port": 27184,
  "maxSize": 1280,
  "maxFps": 60,
  "videoBitRate": 8000000,
  "videoEncoder": "c2.android.avc.encoder"
}

Snake-case keys are also supported for scrcpy options: max_size, max_fps, video_bit_rate, and video_encoder.

.env

ANDROID_SERIAL=emulator-5554
SCRCPY_PORT=27184
SCRCPY_MAX_SIZE=1280
SCRCPY_MAX_FPS=60
SCRCPY_VIDEO_BIT_RATE=8000000
SCRCPY_VIDEO_ENCODER=c2.android.avc.encoder

Fallback names are also supported: PORT, MAX_SIZE, MAX_FPS, VIDEO_BIT_RATE, and VIDEO_ENCODER.

Environment Variables

| Variable | Default | Description | | --- | --- | --- | | ADB_PATH | adb / bundled | Custom ADB binary path | | ANDROID_SERIAL | none | Default target device serial | | SCRCPY_PATH | auto-detect | Host path to scrcpy client executable | | SCRCPY_SERVER_PATH | auto-detect | Host path to scrcpy-server / scrcpy-server.jar | | SCRCPY_SERVER_VERSION | auto-detect | Override scrcpy server version | | SCRCPY_PORT / PORT | 27184 | Daemon port via .env config | | SCRCPY_MAX_SIZE / MAX_SIZE | 0 | Maximum video size; 0 means scrcpy default | | SCRCPY_MAX_FPS / MAX_FPS | 0 | Maximum video FPS; 0 means scrcpy default | | SCRCPY_VIDEO_BIT_RATE / VIDEO_BIT_RATE | 0 | Video bitrate; 0 means scrcpy default | | SCRCPY_VIDEO_ENCODER / VIDEO_ENCODER | none | Video encoder name |

Performance

Actual numbers depend on device, USB connection, host OS, and scrcpy settings.

| Operation | Daemon active | ADB fallback | | --- | --- | --- | | Tap / swipe / key | Usually milliseconds | Typically slower due to shell startup | | Screenshot | Uses active scrcpy video stream | Runs adb exec-out screencap -p | | Clipboard | Uses scrcpy clipboard protocol | Uses Android clipboard shell/service fallbacks |

Troubleshooting

adb devices shows unauthorized

Accept the RSA fingerprint prompt on the device. If it does not appear, revoke USB debugging authorizations in Developer Options, then reconnect the device.

Multiple devices are connected

Pass --serial <serial>, set ANDROID_SERIAL, or add serial to .scrcpyrc.

Daemon starts but commands fail

Check daemon status and confirm the configured device is connected:

scrcpy-cli daemon status
adb devices

If needed, stop the daemon and start it again with explicit settings:

scrcpy-cli daemon stop
scrcpy-cli daemon start --serial <serial> --port 27184

scrcpy server cannot be found

scrcpy-cli automatically uses the bundled vendor/scrcpy-server.jar and downloads it from GitHub Releases if missing. If you want to provide your own custom server build, set SCRCPY_SERVER_PATH to the server jar file:

Examples:

# PowerShell
$env:SCRCPY_SERVER_PATH="C:\tools\scrcpy\scrcpy-server.jar"

# Bash
export SCRCPY_SERVER_PATH=/usr/share/scrcpy/scrcpy-server

Version mismatch or ClassNotFoundException

By default, the server version matches the bundled server (4.1). If using a custom scrcpy-server file with a different version, set SCRCPY_SERVER_VERSION to match:

SCRCPY_SERVER_VERSION=4.1 scrcpy-cli daemon start

Device temp path is corrupted

If a directory was accidentally pushed where the server jar should be, reset it:

adb shell rm -rf /data/local/tmp/scrcpy-server.jar

License

MIT