adbex 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JSleim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# adbex
+
+A friendlier `adb` wrapper. Adds glob expansion, device selection, backups, screenshots, and more — and passes anything it doesn't recognize straight through to `adb`.
+
+## Install
+
+```bash
+npm install -g adbex
+```
+
+Requires `adb` to be installed and on your PATH (part of [Android Platform Tools](https://developer.android.com/tools/releases/platform-tools)).
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `adbex pull <source...> [dest]` | Pull files; globs like `*.png` are expanded on the device |
+| `adbex push <source...> <dest>` | Push files; globs like `*.mp4` are expanded locally |
+| `adbex apk-pull <package>` | Pull all APKs for an installed package |
+| `adbex screenshot [dest]` | Capture the screen and save it locally |
+| `adbex backup <package> [--data]` | Back up an APK and optionally its sdcard data |
+| `adbex restore <dir> [--data]` | Reinstall APKs and optionally push data back |
+| `adbex install <file\|glob...>` | Install one or more APKs; supports wildcards like `*.apk` |
+| `adbex devices` | List connected devices with friendly info |
+| `adbex select` | Pick a default device (saved to `~/.adbex.json`) |
+| `adbex packages [filter]` | List packages; filter by name, `-3` for third-party, `-s` for system |
+| `adbex logcat [package]` | Stream logcat for a package; auto-resolves its PID |
+
+Any command adbex doesn't recognize is passed directly to `adb`:
+
+```bash
+adbex shell                  # same as: adb shell
+adbex reboot bootloader      # same as: adb reboot bootloader
+adbex forward tcp:8080 ...   # and so on
+```
+
+## Flags
+
+| Flag | Description |
+|---|---|
+| `-d <serial>` | Target a specific device, overrides the saved default |
+| `-v, --verbose` | Show what adbex is doing under the hood |
+| `-h, --help` | Print help |
+
+## Device selection
+
+If you work with multiple devices, pick one as the default so you don't have to type `-d` every time:
+
+```bash
+adbex select
+```
+
+Your choice is saved to `~/.adbex.json`. Override it at any time with `-d <serial>`.
+
+## Examples
+
+```bash
+# Pull all screenshots from the device
+adbex pull /sdcard/DCIM/Screenshots/*.png ./screenshots
+
+# Install every APK in the current directory
+adbex install *.apk
+
+# Back up an app and its data, then restore it to a new device
+adbex backup com.example.app --data
+adbex restore ./backup-com.example.app --data
+
+# Pull the APK for an installed app
+adbex apk-pull com.example.app
+
+# Watch logs for a specific app
+adbex logcat com.example.app
+
+# Use a specific device for one command
+adbex -d emulator-5554 screenshot
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "adbex",
+  "version": "1.0.0",
+  "author": "JSleim",
+  "description": "A friendlier ADB wrapper - glob pulls, APK extraction, screenshots, backups and more",
+  "main": "src/index.js",
+  "bin": {
+    "adbex": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "keywords": ["adb", "android", "cli", "file-transfer", "apk"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  }
+}

package/src/commands/apk-pull.js

@@ -0,0 +1,63 @@
+const { execFileSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = function apkPull(args, { verbose } = {}) {
+  const pkg = args[0];
+  const dest = args[1] || '.';
+
+  if (!pkg) {
+    console.error('Usage: adbex apk-pull <package> [dest]');
+    console.error('Example: adbex apk-pull com.example.app ./apks');
+    process.exit(1);
+  }
+
+  if (verbose) console.error(`[adbex] adb shell pm path ${pkg}`);
+
+  let pmOutput;
+  try {
+    pmOutput = execFileSync('adb', ['shell', 'pm', 'path', pkg], {
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    console.error(`Failed to find package "${pkg}". Is it installed?`);
+    process.exit(1);
+  }
+
+  const paths = pmOutput
+    .trim()
+    .split(/\r?\n/)
+    .map(line => line.replace(/^package:/, '').trim())
+    .filter(Boolean);
+
+  if (!paths.length) {
+    console.error(`No APKs found for "${pkg}".`);
+    process.exit(1);
+  }
+
+  if (dest !== '.') {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  console.log(`Found ${paths.length} APK(s) for ${pkg}`);
+
+  let failed = 0;
+  for (const apkPath of paths) {
+    const fileName = path.basename(apkPath);
+    console.log(`Pulling ${fileName}...`);
+    if (verbose) console.error(`[adbex] adb pull "${apkPath}" "${dest}"`);
+
+    const result = spawnSync('adb', ['pull', apkPath, dest], { stdio: 'inherit' });
+    if (result.status !== 0) {
+      console.error(`Failed: ${apkPath}`);
+      failed++;
+    }
+  }
+
+  if (failed > 0) {
+    console.error(`\n${failed} APK(s) failed.`);
+    process.exit(1);
+  } else {
+    console.log(`\nDone. ${paths.length} APK(s) saved to ${dest}`);
+  }
+};

package/src/commands/backup.js

@@ -0,0 +1,90 @@
+const { execFileSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = function backup(args, { verbose } = {}) {
+  const flags = args.filter(a => a.startsWith('-'));
+  const positional = args.filter(a => !a.startsWith('-'));
+
+  const pkg = positional[0];
+  const dest = positional[1] || '.';
+  const includeData = flags.includes('--data') || flags.includes('--full');
+
+  if (!pkg) {
+    console.error('Usage: adbex backup <package> [dest] [--data]');
+    console.error('Example: adbex backup com.example.app ./backups --data');
+    process.exit(1);
+  }
+
+  const resolvedDest = require('path').resolve(dest);
+  const backupDir = path.join(resolvedDest, pkg);
+  fs.mkdirSync(backupDir, { recursive: true });
+
+  const steps = includeData ? 2 : 1;
+  let step = 0;
+  console.log(`Backing up ${pkg} → ${backupDir}`);
+
+  console.log(`\n[${++step}/${steps}] Pulling APK(s)...`);
+  let pmOutput;
+  try {
+    if (verbose) console.error(`[adbex] adb shell pm path ${pkg}`);
+    pmOutput = execFileSync('adb', ['shell', 'pm', 'path', pkg], { encoding: 'utf8' });
+  } catch {
+    console.error(`Package "${pkg}" not found on device.`);
+    process.exit(1);
+  }
+
+  const apkPaths = pmOutput
+    .trim()
+    .split(/\r?\n/)
+    .map(l => l.replace(/^package:/, '').trim())
+    .filter(Boolean);
+
+  let apkFailed = 0;
+  for (const apkPath of apkPaths) {
+    if (verbose) console.error(`[adbex] adb pull "${apkPath}" "${backupDir}"`);
+    const result = spawnSync('adb', ['pull', apkPath, backupDir], { stdio: 'inherit' });
+    if (result.status !== 0) apkFailed++;
+  }
+
+  if (apkFailed) {
+    console.error(`Warning: ${apkFailed} APK(s) failed to pull.`);
+  } else {
+    console.log(`APK(s) saved (${apkPaths.length} file(s))`);
+  }
+
+  if (includeData) {
+    console.log(`\n[${++step}/${steps}] Pulling sdcard data...`);
+    const remoteDat = `/sdcard/Android/data/${pkg}`;
+    const dataDir = path.join(backupDir, 'data');
+    fs.mkdirSync(dataDir, { recursive: true });
+
+    try {
+      if (verbose) console.error(`[adbex] adb shell ls ${remoteDat}`);
+      execFileSync('adb', ['shell', 'ls', remoteDat], { encoding: 'utf8' });
+    } catch {
+      console.warn(`No sdcard data found at ${remoteDat} — app may store data internally only.`);
+      summarize(backupDir, pkg);
+      return;
+    }
+
+    if (verbose) console.error(`[adbex] adb pull "${remoteDat}" "${dataDir}"`);
+    const result = spawnSync('adb', ['pull', remoteDat, dataDir], { stdio: 'inherit' });
+
+    if (result.status !== 0) {
+      console.error('Warning: data pull completed with errors.');
+    } else {
+      console.log('Data saved.');
+    }
+  } else {
+    console.log('\nTip: use --data to also backup /sdcard/Android/data');
+  }
+
+  summarize(backupDir, pkg);
+};
+
+function summarize(backupDir, pkg) {
+  console.log(`\nBackup complete → ${backupDir}`);
+  console.log(`Restore with:  adbex restore "${backupDir}"`);
+  console.log(`With data:     adbex restore "${backupDir}" --data`);
+}

package/src/commands/devices.js

@@ -0,0 +1,67 @@
+const { execFileSync } = require('child_process');
+
+module.exports = function devices(args, { verbose } = {}) {
+  let devicesOutput;
+  try {
+    devicesOutput = execFileSync('adb', ['devices'], { encoding: 'utf8' });
+  } catch {
+    console.error('Failed to run adb devices. Is adb in your PATH?');
+    process.exit(1);
+  }
+
+  const lines = devicesOutput.trim().split(/\r?\n/).slice(1);
+  const serials = lines
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('*'))
+    .map(l => {
+      const [serial, state] = l.split(/\s+/);
+      return { serial, state };
+    });
+
+  if (!serials.length) {
+    console.log('No devices connected.');
+    return;
+  }
+
+  console.log(`${serials.length} device(s) connected:\n`);
+
+  for (const { serial, state } of serials) {
+    if (state !== 'device') {
+      console.log(`  ${serial}  [${state}]`);
+      continue;
+    }
+
+    try {
+      const prop = (prop) => {
+        if (verbose) console.error(`[adbex] adb -s ${serial} shell getprop ${prop}`);
+        return execFileSync('adb', ['-s', serial, 'shell', 'getprop', prop], {
+          encoding: 'utf8',
+        }).trim();
+      };
+
+      const model = prop('ro.product.model');
+      const brand = prop('ro.product.brand');
+      const androidVer = prop('ro.build.version.release');
+      const sdkVer = prop('ro.build.version.sdk');
+
+      let battery = '?';
+      try {
+        const battOut = execFileSync(
+          'adb', ['-s', serial, 'shell', 'dumpsys', 'battery'],
+          { encoding: 'utf8' }
+        );
+        const match = battOut.match(/level:\s*(\d+)/);
+        if (match) battery = `${match[1]}%`;
+      } catch (_) {}
+
+      console.log(`  ${serial}`);
+      console.log(`    Device:  ${brand} ${model}`);
+      console.log(`    Android: ${androidVer} (SDK ${sdkVer})`);
+      console.log(`    Battery: ${battery}`);
+      console.log();
+    } catch (err) {
+      console.log(`  ${serial}  (could not read device info)`);
+      if (verbose) console.error(err.message);
+    }
+  }
+};

package/src/commands/install.js

@@ -0,0 +1,69 @@
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = function install(args, { verbose } = {}) {
+  if (!args.length) {
+    console.error('Usage: adbex install <file|glob> [file|glob...]');
+    console.error('Example: adbex install app.apk');
+    console.error('Example: adbex install .\\backup\\*.apk');
+    process.exit(1);
+  }
+
+  const apks = [];
+
+  for (const arg of args) {
+    if (hasGlob(arg)) {
+      const dir = path.dirname(arg);
+      const pattern = path.basename(arg);
+      const regex = globToRegex(pattern);
+
+      if (!fs.existsSync(dir)) {
+        console.error(`Directory not found: ${dir}`);
+        process.exit(1);
+      }
+
+      const matches = fs.readdirSync(dir)
+        .filter(f => regex.test(f) && f.endsWith('.apk'))
+        .map(f => path.join(dir, f));
+
+      if (!matches.length) {
+        console.error(`No APKs matched: ${arg}`);
+        process.exit(1);
+      }
+
+      if (verbose) console.error(`[adbex] expanded "${arg}" → ${matches.join(', ')}`);
+      apks.push(...matches);
+    } else {
+      if (!fs.existsSync(arg)) {
+        console.error(`File not found: ${arg}`);
+        process.exit(1);
+      }
+      apks.push(arg);
+    }
+  }
+
+  if (!apks.length) {
+    console.error('No APKs to install.');
+    process.exit(1);
+  }
+
+  const cmd = apks.length === 1 ? 'install' : 'install-multiple';
+  console.log(`Installing ${apks.length} APK(s) via ${cmd}...`);
+  if (verbose) console.error(`[adbex] adb ${cmd} ${apks.join(' ')}`);
+
+  const result = spawnSync('adb', [cmd, ...apks], { stdio: 'inherit' });
+  process.exit(result.status ?? 1);
+};
+
+function hasGlob(s) {
+  return /[*?[]/.test(s);
+}
+
+function globToRegex(pattern) {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.');
+  return new RegExp(`^${escaped}$`, 'i');
+}

package/src/commands/logcat.js

@@ -0,0 +1,29 @@
+const { execFileSync, spawnSync } = require('child_process');
+
+module.exports = function logcat(args, { verbose } = {}) {
+  const pkg = args[0];
+
+  if (!pkg || pkg.startsWith('-')) {
+    const result = spawnSync('adb', ['logcat', ...args], { stdio: 'inherit' });
+    process.exit(result.status ?? 1);
+  }
+
+  const rest = args.slice(1);
+
+  let pid;
+  try {
+    pid = execFileSync('adb', ['shell', 'pidof', pkg], { encoding: 'utf8' }).trim();
+  } catch {
+    console.error(`Could not get PID for package "${pkg}"`);
+    process.exit(1);
+  }
+
+  if (!pid) {
+    console.error(`Package "${pkg}" is not running.`);
+    process.exit(1);
+  }
+
+  if (verbose) console.error(`[adbex] adb logcat --pid=${pid} ${rest.join(' ')}`);
+  const result = spawnSync('adb', ['logcat', '--pid=' + pid, ...rest], { stdio: 'inherit' });
+  process.exit(result.status ?? 1);
+};

package/src/commands/packages.js

@@ -0,0 +1,39 @@
+const { execFileSync } = require('child_process');
+
+module.exports = function packages(args, { verbose } = {}) {
+  const flags = args.filter(a => a.startsWith('-'));
+  const filter = args.filter(a => !a.startsWith('-'))[0];
+
+  const pmArgs = ['shell', 'pm', 'list', 'packages'];
+  if (flags.includes('-3')) pmArgs.push('-3');
+  if (flags.includes('-s')) pmArgs.push('-s');
+  if (flags.includes('-e')) pmArgs.push('-e');
+
+  if (verbose) console.error(`[adbex] adb ${pmArgs.join(' ')}`);
+
+  let output;
+  try {
+    output = execFileSync('adb', pmArgs, { encoding: 'utf8' });
+  } catch {
+    console.error('Failed to list packages. Is a device connected?');
+    process.exit(1);
+  }
+
+  let packages = output
+    .trim()
+    .split(/\r?\n/)
+    .map(l => l.replace(/^package:/, '').trim())
+    .filter(Boolean);
+
+  if (filter) {
+    packages = packages.filter(p => p.toLowerCase().includes(filter.toLowerCase()));
+  }
+
+  if (!packages.length) {
+    console.log(filter ? `No packages matching "${filter}".` : 'No packages found.');
+    return;
+  }
+
+  packages.sort().forEach(p => console.log(p));
+  console.log(`\n${packages.length} package(s)${filter ? ` matching "${filter}"` : ''}`);
+};

package/src/commands/pull.js

@@ -0,0 +1,98 @@
+const { execFileSync, spawnSync } = require('child_process');
+const { mkdirSync } = require('fs');
+
+function ensureDestDir(dest) {
+  try {
+    mkdirSync(dest, { recursive: true });
+  } catch {}
+}
+
+module.exports = function pull(args, { verbose } = {}) {
+  if (args.length === 0) {
+    console.error('Usage: adbex pull <source...> [dest]');
+    process.exit(1);
+  }
+
+  const hasAnyGlob = args.some(hasGlob);
+
+  if (!hasAnyGlob) {
+    if (args.length <= 2) {
+      if (args.length === 2) ensureDestDir(args[1]);
+      if (verbose) console.error(`[adbex] adb pull ${args.join(' ')}`);
+      const result = spawnSync('adb', ['pull', ...args], { stdio: 'inherit' });
+      process.exit(result.status ?? 1);
+    } else {
+      const dest = args[args.length - 1];
+      const sources = args.slice(0, -1);
+      ensureDestDir(dest);
+      for (const source of sources) {
+        if (verbose) console.error(`[adbex] adb pull "${source}" "${dest}"`);
+        const result = spawnSync('adb', ['pull', source, dest], { stdio: 'inherit' });
+        if (result.status !== 0) process.exit(result.status);
+      }
+      return;
+    }
+  }
+
+  const dest = args.length >= 2 ? args[args.length - 1] : '.';
+  const sources = args.length >= 2 ? args.slice(0, -1) : args;
+
+  ensureDestDir(dest);
+
+  const expanded = [];
+
+  for (const source of sources) {
+    if (hasGlob(source)) {
+      if (verbose) console.error(`[adbex] expanding: adb shell ls ${source}`);
+      try {
+        const out = execFileSync('adb', ['shell', 'ls', source], {
+          encoding: 'utf8',
+          maxBuffer: 10 * 1024 * 1024,
+        });
+        const matches = out
+          .trim()
+          .split(/\r?\n/)
+          .map(s => s.trim())
+          .filter(s => s && !s.startsWith('ls:'));
+
+        if (!matches.length) {
+          console.warn(`Warning: no matches for "${source}"`);
+        } else {
+          if (verbose) console.error(`[adbex] matched: ${matches.join(', ')}`);
+          expanded.push(...matches);
+        }
+      } catch (err) {
+        console.error(`Error expanding "${source}": ${err.message}`);
+        process.exit(1);
+      }
+    } else {
+      expanded.push(source);
+    }
+  }
+
+  if (!expanded.length) {
+    console.error('No files to pull.');
+    process.exit(1);
+  }
+
+  console.log(`Pulling ${expanded.length} file(s) → ${dest}`);
+
+  let failed = 0;
+  for (const file of expanded) {
+    if (verbose) console.error(`[adbex] adb pull "${file}" "${dest}"`);
+    const result = spawnSync('adb', ['pull', file, dest], { stdio: 'inherit' });
+    if (result.status !== 0) {
+      console.error(`Failed: ${file}`);
+      failed++;
+    }
+  }
+
+  if (failed > 0) {
+    console.error(`\n${failed} file(s) failed.`);
+    process.exit(1);
+  }
+};
+
+function hasGlob(s) {
+  return /[*?[]/.test(s);
+}

package/src/commands/push.js

@@ -0,0 +1,89 @@
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = function push(args, { verbose } = {}) {
+  if (args.length < 2) {
+    console.error('Usage: adbex push <source...> <dest>');
+    console.error('Example: adbex push *.mp4 /sdcard/Movies/');
+    console.error('Example: adbex push ./photos/*.jpg /sdcard/DCIM/');
+    process.exit(1);
+  }
+
+  const dest = args[args.length - 1];
+  const sources = args.slice(0, -1);
+  const hasAnyGlob = sources.some(hasGlob);
+
+  if (!hasAnyGlob) {
+    if (verbose) console.error(`[adbex] adb push ${args.join(' ')}`);
+    const result = spawnSync('adb', ['push', ...args], { stdio: 'inherit' });
+    process.exit(result.status ?? 1);
+  }
+
+  const expanded = [];
+
+  for (const source of sources) {
+    if (hasGlob(source)) {
+      const dir = path.dirname(source);
+      const pattern = path.basename(source);
+      const regex = globToRegex(pattern);
+      const resolvedDir = dir === '.' ? process.cwd() : path.resolve(dir);
+
+      if (!fs.existsSync(resolvedDir)) {
+        console.error(`Directory not found: ${resolvedDir}`);
+        process.exit(1);
+      }
+
+      const matches = fs.readdirSync(resolvedDir)
+        .filter(f => regex.test(f))
+        .map(f => path.join(resolvedDir, f));
+
+      if (!matches.length) {
+        console.warn(`Warning: no matches for "${source}"`);
+      } else {
+        if (verbose) console.error(`[adbex] expanded "${source}" → ${matches.join(', ')}`);
+        expanded.push(...matches);
+      }
+    } else {
+      if (!fs.existsSync(source)) {
+        console.error(`File not found: ${source}`);
+        process.exit(1);
+      }
+      expanded.push(source);
+    }
+  }
+
+  if (!expanded.length) {
+    console.error('No files to push.');
+    process.exit(1);
+  }
+
+  console.log(`Pushing ${expanded.length} file(s) → ${dest}`);
+
+  let failed = 0;
+  for (const file of expanded) {
+    if (verbose) console.error(`[adbex] adb push "${file}" "${dest}"`);
+    const result = spawnSync('adb', ['push', file, dest], { stdio: 'inherit' });
+    if (result.status !== 0) {
+      console.error(`Failed: ${file}`);
+      failed++;
+    }
+  }
+
+  if (failed > 0) {
+    console.error(`\n${failed} file(s) failed.`);
+    process.exit(1);
+  }
+};
+
+function hasGlob(s) {
+  return /[*?[]/.test(s);
+}
+
+function globToRegex(pattern) {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.');
+  return new RegExp(`^${escaped}$`, 'i');
+}

package/src/commands/restore.js

@@ -0,0 +1,103 @@
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = function restore(args, { verbose } = {}) {
+  const dataFlagIndex = args.indexOf('--data');
+  const hasData = dataFlagIndex !== -1;
+
+  let explicitDataDir = null;
+  const cleanArgs = [...args];
+  if (hasData) {
+    cleanArgs.splice(dataFlagIndex, 1);
+    const next = cleanArgs[dataFlagIndex];
+    if (next && !next.startsWith('-')) {
+      explicitDataDir = next;
+      cleanArgs.splice(dataFlagIndex, 1);
+    }
+  }
+
+  const dir = cleanArgs[0];
+
+  if (!dir) {
+    console.error('Usage: adbex restore <dir> [--data [data-dir]]');
+    console.error('Example: adbex restore .\\com.example.app --data');
+    console.error('Example: adbex restore .\\com.example.app --data .\\mydata\\');
+    process.exit(1);
+  }
+
+  const resolvedDir = path.resolve(dir);
+
+  if (!fs.existsSync(resolvedDir)) {
+    console.error(`Directory not found: ${resolvedDir}`);
+    process.exit(1);
+  }
+
+  const apks = fs.readdirSync(resolvedDir)
+    .filter(f => f.endsWith('.apk'))
+    .map(f => path.join(resolvedDir, f));
+
+  if (!apks.length) {
+    console.error(`No APKs found in ${resolvedDir}`);
+    process.exit(1);
+  }
+
+  const steps = hasData ? 2 : 1;
+  let step = 0;
+
+  console.log(`Restoring from ${resolvedDir}\n`);
+
+  console.log(`[${++step}/${steps}] Installing ${apks.length} APK(s)...`);
+
+  const installCmd = apks.length === 1 ? 'install' : 'install-multiple';
+  if (verbose) console.error(`[adbex] adb ${installCmd} ${apks.join(' ')}`);
+
+  const installResult = spawnSync('adb', [installCmd, ...apks], { stdio: 'inherit' });
+  if (installResult.status !== 0) {
+    console.error('Install failed.');
+    process.exit(1);
+  }
+
+  console.log('Installed.');
+
+  if (hasData) {
+    console.log(`\n[${++step}/${steps}] Pushing data...`);
+
+    const dataDir = explicitDataDir
+      ? path.resolve(explicitDataDir)
+      : path.join(resolvedDir, 'data');
+
+    if (!fs.existsSync(dataDir)) {
+      console.error(`Data folder not found: ${dataDir}`);
+      console.error('Tip: specify it explicitly with --data <path>');
+      process.exit(1);
+    }
+
+    const entries = fs.readdirSync(dataDir);
+    if (!entries.length) {
+      console.error(`Data folder is empty: ${dataDir}`);
+      process.exit(1);
+    }
+
+    const remoteDest = '/sdcard/Android/data/';
+    let pushFailed = false;
+    for (const entry of entries) {
+      const entryPath = path.join(dataDir, entry);
+      if (verbose) console.error(`[adbex] adb push "${entryPath}" "${remoteDest}"`);
+      const pushResult = spawnSync('adb', ['push', entryPath, remoteDest], { stdio: 'inherit' });
+      if (pushResult.status !== 0) pushFailed = true;
+    }
+
+    if (pushFailed) {
+      console.error(`
+Data push completed with errors. Possible reasons:
+  - App has restricted its data folder (common on Android 11+)
+  - Insufficient storage on device
+  - File path too long for the device filesystem`);
+    } else {
+      console.log('Data restored.');
+    }
+  }
+
+  console.log('\nRestore complete.');
+};

package/src/commands/screenshot.js

@@ -0,0 +1,37 @@
+const { execFileSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = function screenshot(args, { verbose } = {}) {
+  const dest = args[0] || '.';
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const fileName = `screenshot-${timestamp}.png`;
+  const remotePath = `/sdcard/${fileName}`;
+
+  let localPath;
+  if (dest === '.' || (fs.existsSync(dest) && fs.statSync(dest).isDirectory())) {
+    localPath = path.join(dest, fileName);
+  } else {
+    localPath = dest.endsWith('.png') ? dest : `${dest}.png`;
+  }
+
+  console.log('Capturing screenshot...');
+
+  try {
+    if (verbose) console.error(`[adbex] adb shell screencap -p ${remotePath}`);
+    execFileSync('adb', ['shell', 'screencap', '-p', remotePath]);
+
+    if (verbose) console.error(`[adbex] adb pull ${remotePath} ${localPath}`);
+    spawnSync('adb', ['pull', remotePath, localPath], { stdio: 'inherit' });
+
+    if (verbose) console.error(`[adbex] adb shell rm ${remotePath}`);
+    execFileSync('adb', ['shell', 'rm', remotePath]);
+
+    console.log(`Saved to ${localPath}`);
+  } catch (err) {
+    console.error(`Screenshot failed: ${err.message}`);
+    try { execFileSync('adb', ['shell', 'rm', remotePath]); } catch (_) {}
+    process.exit(1);
+  }
+};

package/src/commands/select.js

@@ -0,0 +1,76 @@
+const { execFileSync } = require('child_process');
+const readline = require('readline');
+
+module.exports = function select(args, { verbose } = {}) {
+  let devicesOutput;
+  try {
+    devicesOutput = execFileSync('adb', ['devices'], { encoding: 'utf8' });
+  } catch {
+    console.error('Failed to run adb devices. Is adb in your PATH?');
+    process.exit(1);
+  }
+
+  const lines = devicesOutput.trim().split(/\r?\n/).slice(1);
+  const serials = lines
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('*'))
+    .map(l => {
+      const [serial, state] = l.split(/\s+/);
+      return { serial, state };
+    })
+    .filter(d => d.state === 'device');
+
+  if (!serials.length) {
+    console.error('No devices connected.');
+    process.exit(1);
+  }
+
+  if (serials.length === 1) {
+    const { serial } = serials[0];
+    console.log(`Only one device: ${serial}`);
+    saveSelection(serial);
+    return;
+  }
+
+  console.log(`${serials.length} devices available. Choose one:\n`);
+
+  for (let i = 0; i < serials.length; i++) {
+    const { serial } = serials[i];
+    try {
+      const prop = (p) => {
+        if (verbose) console.error(`[adbex] adb -s ${serial} shell getprop ${p}`);
+        return execFileSync('adb', ['-s', serial, 'shell', 'getprop', p], { encoding: 'utf8' }).trim();
+      };
+      const model = prop('ro.product.model');
+      const brand = prop('ro.product.brand');
+      const ver = prop('ro.build.version.release');
+      console.log(`  ${i + 1}) ${serial}`);
+      console.log(`     ${brand} ${model} — Android ${ver}`);
+    } catch {
+      console.log(`  ${i + 1}) ${serial}`);
+      console.log(`     (could not read device info) `);
+    }
+    console.log();
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  rl.question('Enter number (1): ', (input) => {
+    rl.close();
+    const idx = parseInt(input, 10) - 1;
+
+    if (isNaN(idx) || idx < 0 || idx >= serials.length) {
+      console.error('Invalid selection.');
+      process.exit(1);
+    }
+
+    const { serial } = serials[idx];
+    saveSelection(serial);
+  });
+};
+
+function saveSelection(serial) {
+  const { load, save } = require('../config');
+  save({ ...load(), selectedDevice: serial });
+  console.log(`Default device set to: ${serial}`);
+}

package/src/config.js

@@ -0,0 +1,20 @@
+const { readFileSync, writeFileSync, existsSync } = require('fs');
+const { homedir } = require('os');
+const { join } = require('path');
+
+const CONFIG_PATH = join(homedir(), '.adbex.json');
+
+function load() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function save(data) {
+  writeFileSync(CONFIG_PATH, JSON.stringify(data, null, 2) + '\n');
+}
+
+module.exports = { load, save };

package/src/index.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('child_process');
+const pull = require('./commands/pull');
+const apkPull = require('./commands/apk-pull');
+const screenshot = require('./commands/screenshot');
+const backup = require('./commands/backup');
+const devices = require('./commands/devices');
+const packages = require('./commands/packages');
+const select = require('./commands/select');
+const logcat = require('./commands/logcat');
+const restore = require('./commands/restore');
+const install = require('./commands/install');
+const push = require('./commands/push');
+
+const COMMANDS = {
+  'pull': pull,
+  'push': push,
+  'apk-pull': apkPull,
+  'screenshot': screenshot,
+  'backup': backup,
+  'restore': restore,
+  'install': install,
+  'devices': devices,
+  'packages': packages,
+  'select': select,
+  'logcat': logcat,
+};
+
+const { load: loadConfig } = require('./config');
+const { selectedDevice } = loadConfig();
+if (selectedDevice) {
+  process.env.ANDROID_SERIAL = selectedDevice;
+}
+
+let args = process.argv.slice(2);
+
+const dIdx = args.indexOf('-d');
+if (dIdx !== -1 && dIdx + 1 < args.length) {
+  process.env.ANDROID_SERIAL = args[dIdx + 1];
+  args.splice(dIdx, 2);
+}
+
+const cmd = args[0];
+const verbose = args.includes('--verbose') || args.includes('-v');
+
+const cleanArgs = args.filter(a => a !== '--verbose' && a !== '-v');
+
+if (!cmd) {
+  printHelp();
+  process.exit(0);
+}
+
+if (cmd === '--help' || cmd === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (COMMANDS[cmd]) {
+  COMMANDS[cmd](cleanArgs.slice(1), { verbose });
+} else {
+  if (verbose) console.error(`[adbex] passing through to adb: adb ${args.join(' ')}`);
+  const result = spawnSync('adb', args, { stdio: 'inherit' });
+  process.exit(result.status ?? 1);
+}
+
+function printHelp() {
+  console.log(`
+adbex — a friendlier adb wrapper
+
+ADBEX COMMANDS:
+  pull <source...> [dest]       Pull files, globs like *.png are auto-expanded
+  push <source...> <dest>       Push files, globs like *.mp4 are auto-expanded
+  apk-pull <package>            Pull APK(s) for an installed package
+  screenshot [dest]             Capture screen and save locally
+  backup <package> [--data]     Backup APK and optionally sdcard data
+  restore <dir> [--data]        Reinstall APKs and optionally push data back
+  install <file|glob...>        Install APK(s), supports wildcards like *.apk
+  devices                       List devices with friendly info
+  select                        Select default device (saves to ~/.adbex.json)
+  packages [filter] [-3] [-s]   List installed packages, optionally filtered
+  logcat [package]               Logcat for package (auto-resolves PID)
+
+FLAGS:
+  -v, --verbose                 Show what adbex is doing under the hood
+  -d <serial>                   Target a specific device (overrides default)
+  -h, --help                    Show this help
+
+ANY OTHER COMMAND is passed straight through to adb:
+  adbex shell, adbex logcat, adbex reboot, etc.
+`);
+}