Hamibot CLI

远程 Android 自动化命令行工具。通过终端控制你的 Android 设备 —— 执行脚本、管理文件、模拟触摸输入，一切尽在命令行。

首次使用？前往 hamibot.cn 注册账号并连接你的设备。

安装

要求 Node.js >= 18

npm install -g hamibot

安装完成后，终端中即可使用 hamibot 命令：

hamibot --version

快速开始

# 1. 登录
hamibot login

# 2. 查看已连接的设备
hamibot devices

# 3. 在设备上执行代码
hamibot exec -c 'toast("Hello from CLI!")'

登录认证

Token 登录（推荐）

Personal Access Token 适合所有场景，尤其是 CI/CD 和脚本自动化。

1. 登录 hamibot.cn/account/tokens，创建一个 Token（格式为 hmp_...）
2. 使用 Token 登录：

hamibot login -t hmp_xxxxxxxxxxxx

账号密码登录

hamibot login

按提示选择登录方式，输入手机号/邮箱和密码即可。

环境变量免登录

在 CI/CD 或脚本中，可以通过环境变量跳过登录步骤：

export HAMIBOT_TOKEN=hmp_xxxxxxxxxxxx
hamibot exec -c 'toast("Hi")' -d my-device

全局选项

所有命令都支持以下全局选项：

选项	说明
-d, --device <id>	指定目标设备（可多次使用，多设备并行）
-j, --json	以 JSON 格式输出结果，方便管道和脚本处理
--debug [namespace]	启用调试日志

设备选择

未指定 -d 时，CLI 会自动选择设备：

1. 如果配置了默认设备（hamibot config defaultDevice <id>），直接使用
2. 如果只有一台设备，自动选中
3. 多台设备时，进入交互式选择（输入 0 选择全部）

多设备并行

# 在两台设备上同时点击
hamibot input tap 500 500 -d device-A -d device-B

命令一览

代码执行

在设备上执行 JavaScript 代码：

# 直接传入代码
hamibot exec -c 'toast("Hello!")'

# 从本地文件执行
hamibot exec -f ./script.js

# 通过管道传入
echo 'toast("Hello!")' | hamibot exec

文件管理

管理设备上的文件：

# 列出目录内容（默认 /sdcard）
hamibot file ls
hamibot file ls /sdcard/Download

# 下载文件到本地（默认保存到当前目录，使用远程文件名）
hamibot file download /sdcard/screenshot.png
hamibot file download /sdcard/screenshot.png ./my-screenshot.png

# 上传文件到设备
hamibot file upload ./local.txt /sdcard/

# 查看文件内容
hamibot file cat /sdcard/log.txt

输入控制

模拟触屏操作：

# 点击
hamibot input tap 500 500
hamibot input click 500 500          # click 是 tap 的别名

# 长按（可指定时长）
hamibot input longtap 500 500
hamibot input longtap 500 500 --duration 1000

# 滑动
hamibot input swipe 500 1500 500 500 --duration 300

# 自定义手势路径
hamibot input gesture 500 100 200 300 400 500 600 700

截图

hamibot screenshot
hamibot screenshot -o ./screen.png
hamibot screenshot --open

应用控制

# 启动应用
hamibot launch com.example.app
hamibot launch com.example.app --activity .MainActivity

设备管理

# 列出所有设备
hamibot devices

# 查看设备详情
hamibot devices info <deviceId>

# 检查在线状态
hamibot devices online

设备信息查询

# 屏幕尺寸与密度
hamibot info screen

# 电池状态
hamibot info battery

# 查看应用信息
hamibot info app com.example.app

# 列出已安装应用
hamibot info apps
hamibot info apps --system

配置

CLI 配置文件位于 ~/.hamibot/（遵循 XDG 规范，可被 $XDG_CONFIG_HOME 覆盖）。

常用配置项

# 设置默认设备
hamibot config defaultDevice <deviceId>

# 查看配置
hamibot config defaultDevice --get

# 清理所有配置
hamibot config --reset

环境变量

变量	说明
HAMIBOT_TOKEN	认证 Token，设置后跳过登录
HAMIBOT_API_URL	API 服务地址
HAMIBOT_TIMEOUT	请求超时时间（毫秒）
HAMIBOT_DEFAULT_DEVICE	默认设备 ID
HAMIBOT_DEBUG	调试日志命名空间

许可证

MIT