@dimzxzzx07/adb-commander-js

Table of Contents

· Overview · Features · Why ADB Commander? · Installation · Quick Start · API Reference · Usage Examples · Device Management · Screenshot & Recording · Input Automation · Package Management · File Management · Network Commands · Shell Commands · Logcat Monitoring · Project Structure · Termux Setup · Error Handling · Contributing · License

Overview

ADB Commander is a Termux-friendly Node.js library that wraps Android Debug Bridge (ADB) commands into clean, promise-based JavaScript functions. No more typing long ADB commands - just use simple, intuitive methods.

Built specifically for Termux users who frequently work with ADB for automation, pentesting, or development. This library turns complex ADB commands into elegant JavaScript code.

Features

Category Features Device Management List devices, get device info, connect/disconnect, check root status Screenshot Capture screenshots, save to file, get as buffer/base64, find colors Screen Recording Record screen, save to file, get recording info Input Automation Tap, swipe, text input, key events, gestures Package Management Install/uninstall apps, list packages, grant permissions File Management Push/pull files, list directories, create/delete/move files Network Get IP/MAC, ping, traceroute, enable/disable WiFi/data, port forwarding Shell Execute shell commands, get process list, kill processes Logcat Monitor logs, filter by tag/level, dump logs

Why ADB Commander?

Before (Raw ADB)

adb shell screencap /sdcard/screen.png
adb pull /sdcard/screen.png ./screen.png
adb shell rm /sdcard/screen.png
adb shell input tap 500 500
adb install app.apk

After (ADB Commander)

await adb.screenshot.capture().toFile('screen.png')
await adb.input.tap(500, 500)
await adb.package.install('app.apk')

Installation

From NPM

# Install as dependency
npm install @dimzxzzx07/adb-commander-js

# Install globally
npm install -g @dimzxzzx07/adb-commander-js

From Repository

git clone https://github.com/Dimzxzzx07/adb-commander-js.git
cd adb-commander-js
npm install
npm run build

Requirements

Requirement Minimum Recommended Node.js 14.0.0 18.0.0 or higher ADB 1.0.32 Latest version Termux Latest Latest RAM 256 MB 512 MB Storage 50 MB 100 MB

Quick Start

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function main() {
    try {
        const devices = await adb.device.list();
        console.log('Devices:', devices);

        if (devices.length > 0) {
            adb.setDevice(devices[0].serial);

            const screenshot = await adb.screenshot.capture();
            await screenshot.toFile('screenshot.png');
            console.log('Screenshot saved');

            await adb.input.tap(500, 500);
            console.log('Tapped at (500, 500)');
        }
    } catch (error) {
        console.error('Error:', error);
    }
}

main();

API Reference

ADB Class

class ADB {
    constructor(deviceSerial?: string);
    
    // Properties
    device: DeviceManager;
    screenshot: Screenshot;
    screenrecord: ScreenRecord;
    input: Input;
    package: PackageManager;
    file: FileManager;
    network: Network;
    shell: Shell;
    logcat: Logcat;

    // Methods
    async version(): Promise<string>;
    async killServer(): Promise<void>;
    async startServer(): Promise<void>;
    async reconnect(): Promise<void>;
    async getState(): Promise<string>;
    async waitForDevice(timeout?: number): Promise<void>;
    async root(): Promise<void>;
    async unroot(): Promise<void>;
    async reboot(mode?: 'bootloader' | 'recovery' | 'sideload'): Promise<void>;
    async remount(): Promise<void>;
    async disableVerity(): Promise<void>;
    async enableVerity(): Promise<void>;
    async setDevice(serial: string): Promise<void>;
}

DeviceManager Class

class DeviceManager {
    async list(): Promise<DeviceInfo[]>;
    async getInfo(serial?: string): Promise<DeviceInfo>;
    async getBatteryLevel(): Promise<number>;
    async getScreenSize(): Promise<{ width: number; height: number }>;
    async checkRoot(): Promise<boolean>;
    async connect(host: string, port?: number): Promise<void>;
    async disconnect(host?: string, port?: number): Promise<void>;
    async waitForDevice(): Promise<void>;
    async isOnline(): Promise<boolean>;
}

Screenshot Class

class Screenshot {
    async capture(): Promise<ScreenshotResult>;
    async captureAndSave(filePath: string): Promise<string>;
    async captureBase64(): Promise<string>;
    async compareWithLast(): Promise<boolean>;
    async findColor(color: string, tolerance?: number): Promise<{ x: number; y: number } | null>;
}

class ScreenshotResult {
    async toFile(filePath: string): Promise<string>;
    async toBuffer(): Promise<Buffer>;
    async toBase64(): Promise<string>;
    async saveAs(filePath: string): Promise<string>;
    async getSize(): Promise<number>;
    async getDimensions(): Promise<{ width: number; height: number }>;
}

ScreenRecord Class

class ScreenRecord {
    async start(options?: ScreenRecordOptions): Promise<void>;
    async stop(): Promise<ScreenRecordResult>;
    async record(timeLimit: number, outputPath?: string): Promise<string>;
    isActive(): boolean;
}

interface ScreenRecordOptions {
    bitrate?: number;
    timeLimit?: number;
    size?: string;
    rotate?: boolean;
}

Input Class

class Input {
    async tap(x: number, y: number, options?: TapOptions): Promise<void>;
    async swipe(options: SwipeOptions): Promise<void>;
    async text(options: TextOptions): Promise<void>;
    async keyevent(key: string | number, longPress?: boolean): Promise<void>;
    async home(): Promise<void>;
    async back(): Promise<void>;
    async menu(): Promise<void>;
    async power(): Promise<void>;
    async volumeUp(): Promise<void>;
    async volumeDown(): Promise<void>;
    async enter(): Promise<void>;
    async delete(): Promise<void>;
    async space(): Promise<void>;
    async tab(): Promise<void>;
    async escape(): Promise<void>;
    async dpadUp(): Promise<void>;
    async dpadDown(): Promise<void>;
    async dpadLeft(): Promise<void>;
    async dpadRight(): Promise<void>;
    async dpadCenter(): Promise<void>;
    async notification(): Promise<void>;
    async quickSettings(): Promise<void>;
    async unlock(): Promise<void>;
    async type(text: string, delay?: number): Promise<void>;
}

PackageManager Class

class PackageManager {
    async install(apkPath: string, options?: InstallOptions): Promise<void>;
    async installRemote(apkPath: string, options?: InstallOptions): Promise<void>;
    async uninstall(packageName: string, keepData?: boolean): Promise<void>;
    async list(filter?: string): Promise<string[]>;
    async listThirdParty(): Promise<string[]>;
    async listSystem(): Promise<string[]>;
    async info(packageName: string): Promise<any>;
    async enable(packageName: string): Promise<void>;
    async disable(packageName: string): Promise<void>;
    async clear(packageName: string): Promise<void>;
    async forceStop(packageName: string): Promise<void>;
    async start(packageName: string, activity?: string): Promise<void>;
    async grantPermission(packageName: string, permission: string): Promise<void>;
    async revokePermission(packageName: string, permission: string): Promise<void>;
    async listPermissions(packageName: string): Promise<string[]>;
}

FileManager Class

class FileManager {
    async push(localPath: string, remotePath: string): Promise<void>;
    async pull(remotePath: string, localPath?: string): Promise<string>;
    async list(remotePath?: string): Promise<FileInfo[]>;
    async mkdir(remotePath: string): Promise<void>;
    async rm(remotePath: string, recursive?: boolean): Promise<void>;
    async mv(source: string, destination: string): Promise<void>;
    async cp(source: string, destination: string): Promise<void>;
    async chmod(remotePath: string, mode: string): Promise<void>;
    async exists(remotePath: string): Promise<boolean>;
    async stat(remotePath: string): Promise<FileInfo>;
    async cat(remotePath: string): Promise<string>;
    async echo(text: string, remotePath: string): Promise<void>;
    async append(text: string, remotePath: string): Promise<void>;
    async downloadFolder(remoteFolder: string, localFolder: string): Promise<void>;
    async uploadFolder(localFolder: string, remoteFolder: string): Promise<void>;
    async sync(source: string, destination: string): Promise<void>;
}

Network Class

class Network {
    async getIP(): Promise<string>;
    async getMac(): Promise<string>;
    async getInterfaces(): Promise<NetworkInfo[]>;
    async ping(host: string, count?: number): Promise<boolean>;
    async traceroute(host: string): Promise<string>;
    async netstat(): Promise<any[]>;
    async enableWifi(): Promise<void>;
    async disableWifi(): Promise<void>;
    async enableData(): Promise<void>;
    async disableData(): Promise<void>;
    async enableAirplane(): Promise<void>;
    async disableAirplane(): Promise<void>;
    async forward(localPort: number, remotePort: number): Promise<void>;
    async reverse(localPort: number, remotePort: number): Promise<void>;
    async listForward(): Promise<string>;
    async listReverse(): Promise<string>;
    async removeForward(localPort: number): Promise<void>;
    async removeReverse(remotePort: number): Promise<void>;
    async removeAllForward(): Promise<void>;
    async removeAllReverse(): Promise<void>;
}

Shell Class

class Shell {
    async exec(command: string): Promise<string>;
    async execWithOutput(command: string): Promise<{ stdout: string; stderr: string }>;
    async ps(): Promise<ProcessInfo[]>;
    async top(limit?: number): Promise<ProcessInfo[]>;
    async kill(pid: number): Promise<void>;
    async killAll(processName: string): Promise<void>;
    async date(): Promise<Date>;
    async uptime(): Promise<number>;
    async env(): Promise<Record<string, string>>;
    async whoami(): Promise<string>;
    async id(): Promise<string>;
    async print(text: string): Promise<void>;
    async sleep(seconds: number): Promise<void>;
    async reboot(): Promise<void>;
    async shutdown(): Promise<void>;
}

Logcat Class

class Logcat extends EventEmitter {
    async clear(): Promise<void>;
    async dump(): Promise<string>;
    async dumpBuffer(buffer: 'main' | 'system' | 'events' | 'crash'): Promise<string>;
    async filter(tag: string, level?: string): Promise<string>;
    start(options?: { clear?: boolean; buffer?: string }): void;
    stop(): void;
    async monitor(packageName: string, callback: (line: string) => void): Promise<void>;
    isActive(): boolean;

    // Events
    on(event: 'log', listener: (entry: LogEntry) => void): this;
    on(event: 'error', listener: (error: string) => void): this;
    on(event: 'stop', listener: (data: { code: number }) => void): this;
}

Usage Examples

Basic Device Operations

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function deviceOps() {
    const devices = await adb.device.list();
    console.log('Connected devices:', devices);

    if (devices.length > 0) {
        adb.setDevice(devices[0].serial);

        const info = await adb.device.getInfo();
        console.log('Device info:', info);

        const battery = await adb.device.getBatteryLevel();
        console.log('Battery level:', battery + '%');

        const isRooted = await adb.device.checkRoot();
        console.log('Is rooted:', isRooted);
    }
}

deviceOps();

Screenshot Automation

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function screenshotDemo() {
    const screenshot = await adb.screenshot.capture();

    await screenshot.toFile('screen.png');
    console.log('Saved to screen.png');

    const buffer = await screenshot.toBuffer();
    console.log('Size:', buffer.length, 'bytes');

    const base64 = await screenshot.toBase64();
    console.log('Base64 length:', base64.length);

    const dimensions = await screenshot.getDimensions();
    console.log('Dimensions:', dimensions);

    const colorPos = await adb.screenshot.findColor('#FF0000');
    if (colorPos) {
        console.log('Found red at:', colorPos);
        await adb.input.tap(colorPos.x, colorPos.y);
    }
}

screenshotDemo();

Screen Recording

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function recordDemo() {
    await adb.screenrecord.start({
        bitrate: 4000000,
        timeLimit: 30,
        size: '720x1280'
    });

    console.log('Recording for 10 seconds...');
    await new Promise(resolve => setTimeout(resolve, 10000));

    const result = await adb.screenrecord.stop();
    await result.toFile('recording.mp4');
    console.log('Recording saved');
}

recordDemo();

Input Automation

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function inputDemo() {
    await adb.input.home();
    await adb.input.text({ text: 'Hello World' });
    await adb.input.enter();

    await adb.input.tap(500, 500);
    await adb.input.swipe({
        x1: 500, y1: 1000,
        x2: 500, y2: 500,
        duration: 500
    });

    await adb.input.volumeUp();
    await adb.input.volumeDown();

    await adb.input.type('This is typed slowly', 100);
    console.log('Input automation completed');
}

inputDemo();

Package Management

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function packageDemo() {
    await adb.package.install('app.apk', {
        reinstall: true,
        grantPermissions: true
    });

    await adb.package.installRemote('app.apk');

    const packages = await adb.package.listThirdParty();
    console.log('Third party apps:', packages);

    const info = await adb.package.info('com.example.app');
    console.log('App info:', info);

    await adb.package.grantPermission('com.example.app', 'android.permission.CAMERA');
    await adb.package.clear('com.example.app');
}

packageDemo();

File Operations

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function fileDemo() {
    await adb.file.push('local.txt', '/sdcard/remote.txt');

    const downloaded = await adb.file.pull('/sdcard/remote.txt', './downloaded.txt');
    console.log('Downloaded to:', downloaded);

    const files = await adb.file.list('/sdcard');
    console.log('Files:', files);

    await adb.file.mkdir('/sdcard/newfolder');
    await adb.file.echo('Hello', '/sdcard/newfolder/hello.txt');
    const content = await adb.file.cat('/sdcard/newfolder/hello.txt');
    console.log('Content:', content);

    await adb.file.downloadFolder('/sdcard/DCIM', './photos');
}

fileDemo();

Network Operations

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function networkDemo() {
    const ip = await adb.network.getIP();
    console.log('IP:', ip);

    const mac = await adb.network.getMac();
    console.log('MAC:', mac);

    const online = await adb.network.ping('8.8.8.8');
    console.log('Internet online:', online);

    await adb.network.enableWifi();
    await adb.network.forward(8080, 8080);

    const forwards = await adb.network.listForward();
    console.log('Forwards:', forwards);

    await adb.network.removeAllForward();
}

networkDemo();

Shell Commands

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function shellDemo() {
    const output = await adb.shell.exec('ls -la /sdcard');
    console.log('ls output:', output);

    const processes = await adb.shell.top(5);
    console.log('Top processes:', processes);

    const date = await adb.shell.date();
    console.log('Device date:', date);

    const uptime = await adb.shell.uptime();
    console.log('Uptime:', uptime, 'seconds');

    const env = await adb.shell.env();
    console.log('Environment:', env);
}

shellDemo();

Logcat Monitoring

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function logcatDemo() {
    adb.logcat.on('log', (entry) => {
        console.log(`[${entry.tag}] ${entry.message}`);
    });

    adb.logcat.on('error', (error) => {
        console.error('Logcat error:', error);
    });

    adb.logcat.start({ clear: true });

    setTimeout(() => {
        adb.logcat.stop();
    }, 30000);

    const dump = await adb.logcat.filter('SystemServer', 'I');
    console.log('SystemServer logs:', dump);
}

logcatDemo();

Complete Automation Example

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function automateApp() {
    try {
        await adb.waitForDevice();

        await adb.input.home();
        await adb.input.text({ text: 'Camera' });
        await adb.input.enter();

        await new Promise(resolve => setTimeout(resolve, 2000));

        const screenshot = await adb.screenshot.capture();
        await screenshot.toFile('app_screen.png');

        await adb.input.tap(500, 800);

        await new Promise(resolve => setTimeout(resolve, 3000));

        const result = await adb.screenrecord.record(10, 'recording.mp4');
        console.log('Recording saved:', result);

        await adb.file.pull('/sdcard/recording.mp4', './recording.mp4');

        console.log('Automation completed successfully');

    } catch (error) {
        console.error('Automation failed:', error);
    }
}

automateApp();

Project Structure

adb-commander-js/
├── src/
│   ├── core/
│   │   ├── ADB.ts
│   │   ├── DeviceManager.ts
│   │   └── CommandBuilder.ts
│   ├── commands/
│   │   ├── Screenshot.ts
│   │   ├── ScreenRecord.ts
│   │   ├── Input.ts
│   │   ├── PackageManager.ts
│   │   ├── FileManager.ts
│   │   ├── Network.ts
│   │   ├── Shell.ts
│   │   └── Logcat.ts
│   ├── utils/
│   │   ├── ADBExecutor.ts
│   │   ├── FileUtils.ts
│   │   ├── Logger.ts
│   │   └── Validator.ts
│   └── index.ts
├── examples/
│   ├── basic-usage.ts
│   ├── automation.ts
│   └── monitor.ts
├── tests/
├── dist/
├── package.json
├── tsconfig.json
└── README.md

Termux Setup

Install ADB in Termux

pkg update && pkg upgrade
pkg install android-tools
adb devices

Enable USB Debugging on Android

1. Go to Settings > About Phone
2. Tap Build Number 7 times to enable Developer Options
3. Go to Settings > Developer Options
4. Enable USB Debugging
5. Connect phone to Termux via USB
6. Run adb devices and accept the authorization on phone

Wireless Debugging

# Connect via TCP/IP
adb tcpip 5555
adb connect 192.168.1.100:5555

Using ADB Commander in Termux

# Create project
mkdir my-adb-project
cd my-adb-project
npm init -y
npm install @dimzxzzx07/adb-commander-js

# Create script
echo "const ADB = require('@dimzxzzx07/adb-commander-js');" > index.js
echo "const adb = new ADB();" >> index.js
echo "adb.device.list().then(console.log).catch(console.error);" >> index.js

# Run
node index.js

Error Handling

Common Errors

Error Cause Solution ADB not found ADB not installed Install android-tools Device not found No device connected Connect device via USB/WiFi Permission denied USB debugging not authorized Accept on device Device offline Device disconnected Reconnect device Command failed Invalid ADB command Check parameters

Error Handling Example

import ADB from '@dimzxzzx07/adb-commander-js';

const adb = new ADB();

async function safeExecute() {
    try {
        await adb.waitForDevice(5000);
        await adb.input.tap(500, 500);
    } catch (error) {
        if (error.message.includes('not found')) {
            console.log('ADB not installed. Run: pkg install android-tools');
        } else if (error.message.includes('no devices')) {
            console.log('No device connected. Connect via USB/WiFi');
        } else {
            console.error('Unknown error:', error);
        }
    }
}

safeExecute();

Retry Logic

async function withRetry(fn: () => Promise<any>, retries = 3, delay = 1000) {
    for (let i = 0; i < retries; i++) {
        try {
            return await fn();
        } catch (error) {
            if (i === retries - 1) throw error;
            console.log(`Attempt ${i + 1} failed, retrying...`);
            await new Promise(resolve => setTimeout(resolve, delay));
        }
    }
}

await withRetry(() => adb.screenshot.capture());

Contributing

Development Setup

git clone https://github.com/Dimzxzzx07/adb-commander-js.git
cd adb-commander-js
npm install
npm run build
npm test

Adding New Commands

1. Create new file in src/commands/
2. Implement class with methods
3. Add to src/core/ADB.ts
4. Export in src/index.ts
5. Add tests
6. Update documentation

Pull Request Process

1. Fork the repository
2. Create feature branch
3. Commit changes
4. Push to branch
5. Open pull request

License

UNLICENSED - Proprietary software. All rights reserved.

This software and its source code are the exclusive property of Dimzxzzx07. Unauthorized copying, modification, distribution, or use of this software is strictly prohibited without express written permission.