pmock-cli

pmock-cli

PMOCK 开放 API 的命令行客户端。用团队的 Access Key / Secret Key 直接管理云手机、 应用、文件、网络和 RPA 任务，不需要打开客户端，也不需要本机登录态。

适合：

• 在终端批量管理云手机
• 写自动化脚本 / CI 任务
• 给 AI Agent 提供可执行的 PMOCK 工具（MCP）

安装

npm（macOS / Linux）

npm install -g pmock-cli@latest

国内镜像如果还没同步，指定官方源：

npm install -g pmock-cli@latest --registry=https://registry.npmjs.org

验证：

pmock-cli version

一行安装（macOS / Linux，不需要 npm）

curl -fsSL https://raw.githubusercontent.com/haidaisiganbei/pmock-cli/main/scripts/install.sh | sh

安装到 ~/.local/bin/pmock-cli，并自动校验 checksums。

Windows

Windows 暂时使用 GitHub Release 中的 .zip：

https://github.com/haidaisiganbei/pmock-cli/releases

其他安装方式

go install github.com/haidaisiganbei/pmock-cli@latest

五分钟上手

# 1. 配置 AK/SK
pmock-cli config init

# 2. 检查配置和连通性
pmock-cli doctor

# 3. 查询设备
pmock-cli phone list --page-num 1 --page-size 100

# 4. 表格查看
pmock-cli phone list --format table

配置

交互式

pmock-cli config init

Secret 输入不会回显。配置保存在 ~/.pmock-cli/config.json，权限 0600。

非交互式

pmock-cli config init \
  --base-url "https://user.pmock.com/api" \
  --access-key "AK..." \
  --secret-key "SK..."

环境变量

CI 中推荐使用环境变量：

export PMOCK_ACCESS_KEY="AK..."
export PMOCK_SECRET_KEY="SK..."
export PMOCK_BASE_URL="https://user.pmock.com/api"
export PMOCK_TIMEOUT="30s"

优先级：

命令行参数 > 环境变量 > 配置文件 > 默认值

多套配置

为不同团队或账号保存独立配置：

export PMOCK_CLI_CONFIG="$HOME/.pmock-cli/team-b.json"
pmock-cli config init

之后固定使用：

export PMOCK_CLI_CONFIG="$HOME/.pmock-cli/team-b.json"

常用命令

云手机

# 列表
pmock-cli phone list --page-size 100
pmock-cli phone list --name-or-code demo
pmock-cli phone list --status 1
pmock-cli phone list --group-id 123

# 开关机 / 重启
pmock-cli phone start --id 123 --wait
pmock-cli phone stop --id 123 --wait
pmock-cli phone restart --id 123 --wait

# 截图（默认删除手机中的截图文件）
pmock-cli phone screen --id 123
pmock-cli phone screen --id 123 --is-remove=false

# 需要花钱或不可逆的操作
pmock-cli phone create --spu-id 1 --sku-id 2 --num 1
pmock-cli phone remove --id 123 --yes

UI 自动化

动作类命令使用 code，不是 id：

pmock-cli phone action click --code A1 --pos-type 2 --pos 100,200 --wait
pmock-cli phone action input --code A1 --text "hello" --wait
pmock-cli phone action swipe --code A1 --pos1 100,200 --pos2 100,600

文件上传

pmock-cli phone file upload --id 123 --file ./video.mp4
pmock-cli phone file upload --id 123 --file ./app.apk --type app

• 自动计算 MD5
• 自动分片上传
• 默认推送到 /sdcard/Download
• --dest 可指定手机目录
• --type app 返回的 envFileId 可传给 app install --file-id

应用

pmock-cli app list --page-size 10 --apk-name tiktok
pmock-cli app install --id 123 --file-id 456 --apk-pkg com.example.app \
  --apk-name Example --apk-version-name 1.0 --apk-version-code 1

RPA

pmock-cli rpa template list
pmock-cli rpa task list
pmock-cli rpa task add --template-id 9 --name daily --json @task.json --wait

更多命令：

pmock-cli --help
pmock-cli phone --help
pmock-cli docs phone start
pmock-cli commands

输出

默认输出 JSON：

{
  "traceId": "...",
  "code": 200,
  "msg": "查询成功",
  "data": {}
}

• code 为 0 或 200 表示成功
• 其他 code 表示失败，msg 是原因
• 分页接口统一输出为 data.total + data.rows

{
  "data": {
    "total": 6,
    "rows": [ ... ]
  }
}

• password、adbPassword、accessKey、token 等字段会自动替换为 ****

格式：

pmock-cli phone list --format json
pmock-cli phone list --format pretty
pmock-cli phone list --format table

退出码：

--allow-business-error 可以让业务失败也返回 0，适合只判断接口可达性的脚本。

更多用法

嵌套参数

标量参数用 flag，嵌套对象或数组用 --json：

pmock-cli phone create --spu-id 1 --sku-id 2 --num 1 \
  --json '{"tagIds":[1,2],"realResolution":true}'

pmock-cli rpa task add --template-id 9 --name daily --json @task.json

先看请求再执行

pmock-cli phone start --id 123 --dry-run

只输出 method、URL 和 body，不发送请求。

异步等待

pmock-cli phone start --id 123 --wait
pmock-cli phone action click --code A1 --pos-type 2 --pos 100,200 --wait
pmock-cli rpa task add --template-id 9 --name daily --json @task.json --wait

结果会写进 data.wait：

{
  "taskId": 1,
  "wait": {
    "ok": true,
    "taskStatus": 2,
    "phoneStatus": 1,
    "attempts": 2,
    "waitedMs": 1200
  }
}

MCP（AI Agent 接入）

{
  "mcpServers": {
    "pmock": {
      "command": "pmock-cli",
      "args": ["mcp"],
      "env": {
        "PMOCK_BASE_URL": "https://user.pmock.com/api",
        "PMOCK_ACCESS_KEY": "AK...",
        "PMOCK_SECRET_KEY": "SK..."
      }
    }
  }
}

工具按模块分组，调用时用 action 选择动作，params 传参数：

{
  "action": "start",
  "params": { "id": "1900000000000000123", "wait": true }
}

• 支持 pmock_phone、pmock_phone_action、pmock_phone_file、pmock_app、pmock_network、pmock_rpa_template、pmock_rpa_task、pmock_product、pmock_brand、pmock_team、pmock_task、pmock_account
• pmock_help 可以查询任意命令的完整参数
• 删除、重置等破坏性动作需要 params.yes = true
• 64 位 ID 必须用字符串传（"id": "1900000000000000123"），不要写成 JSON 数字。MCP SDK 按 float64 解析数字，超过 2^53 会丢精度，服务端只会看到四舍五入后的 ID，最终报「手机不存在」。直接调用 CLI 时 --id 是字符串参数，不受影响

故障排查

MCP 报「手机不存在」，但 CLI 直接调用正常

大整数 ID 被 JSON 数字精度截断了。MCP 工具参数里的 ID 要加引号：

{ "action": "start", "params": { "id": "1900000000000000123" } }

数字形式在 2^53 以上会丢失末尾几位（例如 1900000000000000123 变成 1900000000000000000），API 自然查不到这台手机。新版 CLI 遇到这种数字会直接报错并提示改用字符串，而不是把错误 ID 发出去。--json 里嵌套的 ID 同理。

10123 无效的开发者编号

通常是环境或团队不匹配：

pmock-cli config show

确认：

• base URL 是否正确
• AK/SK 是否属于同一环境的同一团队
• 客户端当前选中的团队是否一致

有设备但列表为空

先确认版本：

pmock-cli version

0.1.4 起已支持 rows 分页响应；旧版本可能显示 data: null。

npm 安装后还是旧版本

npm install -g pmock-cli@latest --registry=https://registry.npmjs.org --prefer-online
pmock-cli version

配置文件权限

chmod 600 ~/.pmock-cli/config.json

诊断

pmock-cli doctor

安全

• AK/SK 是团队维度凭证，不要提交到仓库或发到公开渠道
• 配置文件默认 0600
• CI 使用 PMOCK_ACCESS_KEY / PMOCK_SECRET_KEY
• remove、reset、new 等不可逆操作需要 --yes
• 输出会隐藏密码、ADB 密码、token 等敏感字段
• 如果凭证泄露，请在 PMOCK 客户端中重置

链接

• 开放 API 文档：https://help.pmock.com/zh/api-docs/api-docs.html
• Releases：https://github.com/haidaisiganbei/pmock-cli/releases
• 问题反馈：https://github.com/haidaisiganbei/pmock-cli/issues

参与开发请见 CONTRIBUTING.md。

Apache-2.0，见 LICENSE。