multi-adb 0.1.0

Android Debug Bridge Selector - A tool for managing multiple ADB devices

adbs - Android Debug Bridge Selector

A smart command-line wrapper for Android Debug Bridge (ADB) that makes managing multiple connected devices effortless on Windows and Linux.

支持中文 | English support available

问题解决方案 / Problem Solved

当您连接了多个ADB设备（包括物理设备和模拟器）时，运行ADB命令变得繁琐，因为每次都需要使用 -s 标志指定设备序列号：

When multiple ADB devices are connected to your computer (both physical devices and emulators), running ADB commands becomes tedious as you need to specify the device serial number every time using the -s flag:

adb -s 0123456789ABCDEF shell
adb -s 0123456789ABCDEF install app.apk
adb -s 127.0.0.1:7665 logcat

adbs 通过让您选择一次设备，然后所有后续命令自动使用该设备来解决这个问题。

adbs solves this by letting you select a device once, then automatically using that device for all subsequent commands.

功能特性 / Features

• ✨ 交互式设备选择 - 从可用设备中简单选择

• 🌐 多语言支持 - 自动检测系统语言（中文/英文）

• 💾 持久化设备选择 - 选择跨终端会话记住

• 🔧 自定义命令 - 快速执行常用命令序列

• 📋 详细输出模式 - 显示执行的命令（-v 选项）

• 🔄 轻松切换设备 - 单个命令切换设备

• 🎯 透明ADB包装 - 所有ADB命令按预期工作

• 🚀 零配置 - 开箱即用，只需安装使用

• ✨ Interactive Device Selection - Choose from connected devices with a simple menu

• 🌐 Multi-language Support - Automatic detection of system language (Chinese/English)

• 💾 Persistent Device Selection - Your choice is remembered across terminal sessions

• 🔧 Custom Commands - Quickly execute common command sequences

• 📋 Verbose Output - Show executed commands with -v option

• 🔄 Easy Device Switching - Switch to another device anytime with a single command

• 🎯 Transparent ADB Wrapping - All ADB commands work exactly as expected

• 🚀 Zero Configuration - Works out of the box, just install and use

安装 / Installation

通过 pip 安装 / via pip (推荐 Recommended)

pip install adbs

从源代码安装 / From Source

git clone https://github.com/toder/adbs.git
cd adbs
pip install .

系统要求 / Requirements

• Python 3.7 或更高 / Python 3.7 or higher
• ADB (Android Debug Bridge) 已安装并在 PATH 中 / ADB (Android Debug Bridge) installed and in your PATH
  • Android SDK Platform Tools 的一部分 / Part of Android SDK Platform Tools
  • 可从以下地址下载 / Can be downloaded from: https://developer.android.com/studio/releases/platform-tools

使用方法 / Usage

初始设备选择 / Initial Device Selection

首次运行不带参数的 adbs 时，它会列出所有连接的设备并让您选择：

When you first run adbs without arguments, it will list all connected devices and let you choose one:

$ adbs

可用设备：
  [1] 0123456789ABCDEF (在线)
  [2] 127.0.0.1:7665 (在线)

选择设备 (1-2): 1
✓ 设备 '0123456789ABCDEF' 已选择并保存。

or in English:

$ adbs

Available devices:
  [1] 0123456789ABCDEF (device)
  [2] 127.0.0.1:7665 (device)

Select device (1-2): 1
✓ Device '0123456789ABCDEF' selected and saved.

使用 adbs 命令 / Using adbs Commands

一旦选择了设备，所有后续 adbs 命令自动使用该设备：

Once a device is selected, all subsequent adbs commands automatically use that device:

# 在选定设备上进入 shell / Enter shell on selected device
adbs shell

# 安装 APK / Install an APK
adbs install app.apk

# 查看日志 / View logs
adbs logcat

# 推送文件 / Push files
adbs push local_file.txt /sdcard/

# 拉取文件 / Pull files
adbs pull /sdcard/remote_file.txt .

详细输出模式 / Verbose Mode

使用 -v 或 --verbose 选项查看执行的命令：

Use the -v or --verbose option to see the commands being executed:

$ adbs -v shell
执行命令：adb -s 0123456789ABCDEF shell

自定义命令 / Custom Commands

您可以创建自定义命令快捷方式。在主目录创建 ~/.adbs_custom.json 文件：

You can create custom command shortcuts. Create a ~/.adbs_custom.json file in your home directory:

{
  "connect_yocoto": [
    "adb -d forward tcp:7665 tcp:6665",
    "adb connect 127.0.0.1:7665"
  ],
  "disconnect_yocoto": "adb disconnect 127.0.0.1:7665",
  "start_logcat": [
    "adb logcat -c",
    "adb logcat *:V"
  ]
}

然后使用简洁的命令名：

Then use the simple command name:

$ adbs connect_yocoto
执行自定义命令序列：adb -d forward tcp:7665 tcp:6665 → adb connect 127.0.0.1:7665
执行命令：adb -d forward tcp:7665 tcp:6665
执行命令：adb connect 127.0.0.1:7665
connected to 127.0.0.1:7665

查看所有自定义命令：

View all custom commands:

$ adbs --help
...
可用自定义命令：
  connect_yocoto    adb -d forward tcp:7665 tcp:6665 → adb connect 127.0.0.1:7665
  disconnect_yocoto adb disconnect 127.0.0.1:7665
  start_logcat      adb logcat -c → adb logcat *:V

临时覆盖设备 / Temporarily Override Device

如果需要在单个命令中临时使用其他设备，使用 -s 标志：

If you need to use a different device for a single command, use the -s flag:

adbs -s 127.0.0.1:7665 shell

切换设备 / Switch Device

要切换到不同的设备，只需再次运行 adbs：

To switch to a different device, simply run adbs again:

$ adbs

可用设备：
  [1] 0123456789ABCDEF (在线)
  [2] 127.0.0.1:7665 (在线)

选择设备 (1-2): 2
✓ 设备 '127.0.0.1:7665' 已选择并保存。

列出所有设备 / List All Devices

要查看所有连接的设备而不更改选择：

To see all connected devices without changing your selection:

adbs devices

单个设备自动选择 / Single Device Auto-Selection

如果只连接了一个设备，adbs 会自动选择它而不提示。

If only one device is connected, adbs will automatically select it without prompting.

支持的命令 / Supported Commands

adbs 支持所有 ADB 子命令：

adbs supports all ADB subcommands:

• shell - 交互式 shell / Interactive shell
• install - 安装 APK 文件 / Install APK files
• uninstall - 卸载应用 / Uninstall applications
• push - 推送文件到设备 / Push files to device
• pull - 从设备拉取文件 / Pull files from device
• logcat - 查看设备日志 / View device logs
• forward - 端口转发 / Port forwarding
• reverse - 反向端口转发 / Reverse port forwarding
• screencap - 屏幕截图 / Screen capture
• screenrecord - 屏幕录制 / Screen recording
• 以及所有其他 ADB 命令！/ And all other ADB commands!

不需要设备选择的全局命令（如 devices、version、help、kill-server、start-server）会自动处理，无需提示。

Global commands that don't require device selection (like devices, version, help, kill-server, start-server) are handled automatically without prompting.

工作原理 / How It Works

1. 配置存储：您选择的设备序列号存储在 ~/.adbs_config

2. 智能命令检测：adbs 自动检测哪些命令需要设备选择

3. 透明转发：命令通过传递给 ADB 并添加适当的 -s 标志

4. 验证：工具在执行命令前验证所选设备仍然可用

5. 自定义命令：从 ~/.adbs_custom.json 加载自定义命令序列

6. Configuration Storage: Your selected device serial is stored in ~/.adbs_config

7. Smart Command Detection: adbs automatically detects which commands need device selection

8. Transparent Forwarding: Commands are passed through to ADB with appropriate -s flags

9. Validation: The tool verifies your selected device is still available before executing commands

10. Custom Commands: Custom command sequences are loaded from ~/.adbs_custom.json

项目结构 / Project Structure

adbs/
├── adbs/
│   ├── __init__.py      # 包元数据 / Package metadata
│   ├── __main__.py      # 入口点 / Entry point
│   └── core.py          # 核心功能 / Core functionality
├── pyproject.toml       # 构建配置 / Build configuration
├── LICENSE              # MIT 许可证 / MIT License
├── README.md            # 本文件 / This file
└── adbs_custom.example.json  # 自定义命令示例 / Custom commands example

开发 / Development

构建包 / Building the Package

pip install build
python -m build

本地测试 / Local Testing

以开发模式安装：

Install in development mode:

pip install -e .

自定义命令示例 / Custom Commands Example

创建 ~/.adbs_custom.json：

Create ~/.adbs_custom.json:

{
  "connect_yocoto": [
    "adb -d forward tcp:7665 tcp:6665",
    "adb connect 127.0.0.1:7665"
  ],
  "logcat_clear": [
    "adb logcat -c",
    "adb logcat -v time"
  ],
  "install_release": "adb -s <your_device> install app-release.apk",
  "reboot_bootloader": "adb reboot bootloader"
}

然后可以直接使用：

Then use directly:

adbs connect_yocoto
adbs logcat_clear

多语言支持 / Multi-language Support

adbs 根据系统语言自动检测语言环境：

adbs automatically detects the locale based on system language:

• 中文 (zh_CN): 简体中文支持 / Simplified Chinese support
• English: 默认回退 / Default fallback

您可以通过更改系统的语言环境来切换语言。

You can switch the language by changing your system's locale.

许可证 / License

MIT License - see LICENSE file for details.

贡献 / Contributing

欢迎贡献！请随时提交问题或拉取请求。

Contributions are welcome! Please feel free to submit issues or pull requests.

作者 / Author

创建和维护 / Created and maintained by Toder

路线图 / Roadmap

• 设备别名/昵称 / Device aliases/nicknames
• 每项目设备配置文件 / Per-project device profiles
• 设备分组 / Device grouping
• GUI 设备选择器 / GUI device selector
• 与其他 Android 开发工具集成 / Integration with other Android development tools
• ✅ 自定义命令支持 / Custom commands support
• ✅ 详细输出模式 / Verbose output mode
• ✅ 多语言支持 / Multi-language support

故障排除 / Troubleshooting

"adb command not found"

确保 ADB 已安装并添加到系统 PATH 中。在 Windows 上，安装 Android SDK Platform Tools 后可能需要重启终端。

Ensure ADB is installed and added to your system PATH. On Windows, you may need to restart your terminal after installing Android SDK Platform Tools.

"No online devices found"

确保您的设备已连接并获得授权。检查设备上是否启用了 USB 调试，并且您已接受了 RSA 密钥提示。

Make sure your devices are connected and authorized. Check that USB debugging is enabled on your device and you've accepted the RSA key prompt.

配置问题 / Configuration Issues

设备选择存储在 ~/.adbs_config 中。您可以安全地删除此文件以重置配置。

The device selection is stored in ~/.adbs_config. You can safely delete this file to reset the configuration.

自定义命令不工作 / Custom Commands Not Working

确保 ~/.adbs_custom.json 文件是有效的 JSON 格式。可以使用 JSON 验证工具验证语法。

Make sure the ~/.adbs_custom.json file is in valid JSON format. You can validate the syntax using a JSON validator tool.

参见 / See Also

• 官方 ADB 文档 / Official ADB Documentation
• Android Platform Tools

常见问题 / FAQ

Q: 如何查看所有可用选项？/ How do I see all available options?

A: 运行 adbs --help / Run adbs --help

Q: 可以在 Windows 上使用吗？/ Can I use it on Windows?

A: 是的，完全支持 Windows / Yes, fully supported on Windows

Q: 如何删除缓存的设备选择？/ How do I delete the cached device selection?

A: 删除文件 ~/.adbs_config 或运行 adbs 选择新设备 / Delete the file ~/.adbs_config or run adbs to select a new device

Q: 自定义命令支持变量替换吗？/ Do custom commands support variable substitution?

A: 目前不支持，但计划在未来版本中添加 / Not currently supported, but planned for future versions