adbshell

A minimal Rust wrapper around the adb command-line tool with a persistent shell session.

adbshell exposes [AdbShell], a stateful handle that maintains a long-lived adb shell connection for low-latency device queries. Each shell command (getprop, dumpsys, wm) reuses the same session instead of spawning a fresh adb subprocess, reducing per-call overhead. File transfers and JAR execution still use individual adb subprocesses.

Features

Persistent adb shell session with automatic reconnect on failure.
Sentinel-based output framing — reliable output capture without per-process overhead.
Device discovery: serial number, connection state, screen size and orientation.
System property queries via getprop.
File transfer with adb push.
Reverse-tunnel setup and teardown (adb reverse).
app_process JAR execution for launching Android server processes.
No async runtime required — pure std threads.

Quick start

Add to your Cargo.toml:

[dependencies]
adbshell = "0.2"

use adbshell::{AdbResult, AdbShell};

AdbShell::verify_adb_available().expect("adb not found in PATH");

let serial = AdbShell::get_device_serial().expect("no device connected");

// Open a persistent shell session
let shell = AdbShell::new(&serial).expect("failed to open shell");

let sdk = shell.get_prop("ro.build.version.sdk").unwrap();
println!("Android SDK: {sdk}");

let state = AdbShell::get_device_state(&serial).unwrap();
println!("Device state: {:?}", state);

API overview

Static helpers (no instance required)

Function	Description
`AdbShell::verify_adb_available()`	Verify `adb` is installed and in `PATH`
`AdbShell::get_device_serial()`	Return the first connected device serial
`AdbShell::get_device_state(serial)`	Return `Connected`, `Disconnected`, or `Unknown`

Instance methods (persistent shell session)

Method	Description
`AdbShell::new(serial)`	Open a persistent `adb shell` session
`shell.serial()`	Return the device serial
`shell.get_prop(key)`	Read an Android system property
`shell.get_android_version()`	Return the API level as `u32`
`shell.get_platform()`	Return board/hardware platform string
`shell.get_physical_screen_size()`	Return `(width, height)` in pixels
`shell.get_screen_orientation()`	Return orientation 0–3
`shell.get_ime_state()`	Return whether the soft keyboard is visible

Instance methods (individual subprocesses)

Method	Description
`shell.push_file(src, dst)`	Push a local file to the device
`shell.execute_jar(jar, …)`	Launch a JAR via `app_process`
`shell.setup_reverse_tunnel(name, port)`	Create an ADB reverse tunnel
`shell.remove_reverse_tunnel(name)`	Remove an ADB reverse tunnel

Error handling

All functions return AdbResult<T> (an alias for Result<T, AdbError>).

pub enum AdbError {
    NotFound(String),       // adb binary missing or failed to spawn
    CommandFailed(String),  // adb exited with non-zero status
    Timeout,                // command exceeded the given duration
    DeviceNotFound(String), // requested device not connected
}

Requirements

adb (Android platform-tools) must be installed and in PATH.
Rust 1.85+

License

Licensed under either of

at your option.

adbshell 0.2.0