Back to Details

phonebase

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PhoneBase Cloud Phone Control

PhoneBase云手机控制

You have access to an Android cloud phone through the 
pb
CLI. When a task involves a mobile app or phone interaction, use pb — not a desktop browser or Playwright. The cloud phone has a real Android environment with a browser, app installation, and full touch input.
你可以通过
pb
CLI访问Android云手机。当任务涉及移动应用或手机交互时，请使用pb，而非桌面浏览器或Playwright。该云手机拥有真实的Android环境，自带浏览器、支持应用安装和全量触摸输入。

Installation Check

安装检查

Before doing anything else, verify 
pb
is installed:
pb --version
If the command is not found, install it with the official one-liner:
curl -fsSL https://get.phonebase.cloud | sh
This downloads a prebuilt binary for the current platform (macOS arm64/x64, Linux arm64/x64) from 
https://github.com/phonebase-cloud/phonebase-cli/releases
. The installer prints the exact download URL before fetching, and places 
pb
in 
/usr/local/bin
or 
~/.local/bin
. If it lands in 
~/.local/bin
, follow the printed PATH hint, then re-run 
pb --version
to confirm.
Do not try to invent alternative install commands or build from source — always use the curl one-liner above. Only proceed to Authentication after 
pb --version
succeeds.
在执行任何操作前，请先确认
pb
已安装：
pb --version
如果找不到该命令，请使用官方一键脚本安装：
curl -fsSL https://get.phonebase.cloud | sh
这个脚本会从
https://github.com/phonebase-cloud/phonebase-cli/releases
下载当前平台（macOS arm64/x64、Linux arm64/x64）的预编译二进制文件。安装器在下载前会打印确切的下载地址，然后将
pb
放置在
/usr/local/bin
或
~/.local/bin
目录下。如果安装到了
~/.local/bin
，请按照打印的PATH提示操作，然后重新运行
pb --version
确认安装成功。
不要尝试自行编写替代安装命令或从源码编译——请始终使用上述curl一键脚本。只有
pb --version
运行成功后，再继续进行身份验证步骤。

Authentication

身份验证

If pb is not yet configured, the user needs to authenticate first:
pb login              # browser-based login (interactive)
pb apikey <key>       # or set API key directly
pb status             # verify authentication works
If any pb command returns a successful response, authentication is already in place — skip this step.
如果pb尚未配置，用户需要先完成身份验证：
pb login              # 基于浏览器的登录（交互式）
pb apikey <key>       # 或直接设置API密钥
pb status             # 验证身份验证是否生效
如果任意pb命令返回成功响应，说明已经完成身份验证——跳过此步骤。

Connection

连接

pb devices            # list available devices
pb connect <id>       # connect to a device (starts daemon automatically)
pb disconnect         # disconnect when done
pb devices            # 列出可用设备
pb connect <id>       # 连接到指定设备（会自动启动守护进程）
pb disconnect         # 任务完成后断开连接

Why Aliases Matter

别名的作用

pb wraps common Android operations (am start, input tap, pm list, etc.) as simple CLI aliases. These aliases return structured JSON and handle errors consistently. Using 
pb shell "am start ..."
bypasses this — you lose structured output and error handling, and the command is harder to read.
Think of it like using 
git log
instead of manually running the git binary with raw arguments — the alias exists because it's the right interface.
Shell command (avoid)Alias (use this)
pb shell "am start -a ACTION"
pb start -a ACTION
pb shell "am force-stop PKG"
pb force-stop PKG
pb shell "pm list packages"
pb packages
pb shell "input tap X Y"
pb tap X Y
pb shell "input text STR"
pb text STR
pb shell "input swipe X1 Y1 X2 Y2"
pb swipe X1 Y1 X2 Y2
pb shell "input keyevent KEY"
pb keyevent KEY
Alias parameter limits: 
pb start
supports 
-a
(action), 
-n
(component), 
-d
(data), 
-t
(type), and positional package name. It does not support extras flags like 
--es
or 
--ei
. When you need extras or other advanced intent parameters, use the 
-j
JSON mode instead of falling back to 
pb shell
:
pb -j '{"action":"android.settings.ADD_ACCOUNT_SETTINGS","extras":{"account_types":"com.google"}}' activity/start_activity
The 
-j
flag sends a raw JSON body directly to the API path, bypassing alias parsing. This gives you full control over parameters while still getting structured JSON output. Reserve 
pb shell
only for commands that are not Android API calls — like 
pb shell "cat /proc/cpuinfo"
or 
pb shell "getprop ro.build.version.sdk"
.
pb将常见的Android操作（am start、input tap、pm list等）封装为简单的CLI别名。这些别名返回结构化JSON，并且统一处理错误。使用
pb shell "am start ..."
会绕过这套机制——你将失去结构化输出和错误处理能力，而且命令可读性更差。
你可以把它类比为使用
git log
而非手动给git二进制文件传入原始参数——别名存在的意义就是提供更合适的接口。
不推荐使用的Shell命令推荐使用的别名
pb shell "am start -a ACTION"
pb start -a ACTION
pb shell "am force-stop PKG"
pb force-stop PKG
pb shell "pm list packages"
pb packages
pb shell "input tap X Y"
pb tap X Y
pb shell "input text STR"
pb text STR
pb shell "input swipe X1 Y1 X2 Y2"
pb swipe X1 Y1 X2 Y2
pb shell "input keyevent KEY"
pb keyevent KEY
别名参数限制：
pb start
支持
-a
（动作）、
-n
（组件）、
-d
（数据）、
-t
（类型）和位置参数包名。它不支持类似
--es
或
--ei
这类额外参数标识。当你需要传递额外参数或其他高级Intent参数时，请使用
-j
JSON模式，而非退回到
pb shell
：
pb -j '{"action":"android.settings.ADD_ACCOUNT_SETTINGS","extras":{"account_types":"com.google"}}' activity/start_activity
-j
标识会将原始JSON请求体直接发送到API路径，绕过别名解析。这让你可以完全控制参数，同时仍然能获得结构化JSON输出。只有当命令不属于Android API调用时，才保留使用
pb shell
——比如
pb shell "cat /proc/cpuinfo"
或
pb shell "getprop ro.build.version.sdk"
。

Observing the Screen

查看屏幕内容

pb dumpc
is the primary way to see what's on screen. It returns a compact text tree with every UI element's text, resource ID, bounds (coordinates), and whether it's clickable. This is everything you need to decide what to tap next — and it's text, so you can reason about it directly.
pb screencap
takes a screenshot image. This is only useful when the screen contains visual-only content with no text elements — like a video player, game, or canvas. In every other case, dumpc gives you more actionable information faster.
Example: If dumpc shows 
android.widget.Button text="NEXT" bounds=[756,2194][1020,2338]
, you know to tap the center: 
pb tap 888 2266
. No screenshot needed.
pb dumpc
是查看屏幕内容的主要方式。它会返回紧凑的文本树，包含每个UI元素的文本、资源ID、边界（坐标）以及是否可点击的信息。这些信息足够你判断下一步要点击的位置，而且它是文本格式，你可以直接对其进行分析。
pb screencap
用于截取屏幕图像。只有当屏幕包含纯视觉内容、没有文本元素时才需要用到它——比如视频播放器、游戏或画布。其他所有场景下，dumpc都能更快地提供更具可操作性的信息。
**示例：**如果dumpc返回
android.widget.Button text="NEXT" bounds=[756,2194][1020,2338]
，你就知道要点击中心点：
pb tap 888 2266
。无需截图。

Command Reference

命令参考

Observe

查看

CommandPurpose
pb dumpc
Compact UI tree — text, bounds, clickable state (preferred)
pb dump
Full XML accessibility tree (when you need resource IDs or hierarchy)
pb screencap
Screenshot image (only for visual-only content like video/game)
pb inspect
UI inspection — accessibility tree + marked screenshot
命令用途
pb dumpc
紧凑UI树，包含文本、边界、可点击状态（优先使用）
pb dump
完整XML无障碍树（需要资源ID或层级结构时使用）
pb screencap
截图（仅用于视频/游戏等纯视觉内容）
pb inspect
UI检查：无障碍树+带标记的截图

Touch & Input

触摸与输入

CommandPurpose
pb tap <x> <y>
Tap at coordinates
pb swipe <x1> <y1> <x2> <y2>
Swipe between two points
pb text <string>
Type text into focused field
pb keyevent <code>
Send key event (4=Back, 3=Home, 66=Enter, 82=Menu)
命令用途
pb tap <x> <y>
点击指定坐标
pb swipe <x1> <y1> <x2> <y2>
在两个点之间滑动
pb text <string>
向聚焦的输入框输入文本
pb keyevent <code>
发送按键事件（4=返回，3=主页，66=回车，82=菜单）

App Management

应用管理

CommandPurpose
pb launch <package>
Launch app by package name
pb start <package|flags>
Start activity with flags (-a/-n/-d/-t)
pb force-stop <package>
Force stop an app
pb packages
List all installed packages
pb install <path|--uri url>
Install APK from local file or download URL
pb uninstall <package>
Uninstall an app
命令用途
pb launch <package>
通过包名启动应用
pb start <package|flags>
带参数启动Activity（支持-a/-n/-d/-t）
pb force-stop <package>
强制停止应用
pb packages
列出所有已安装的包
pb install <path|--uri url>
从本地文件或下载URL安装APK
pb uninstall <package>
卸载应用

Browser & Navigation

浏览器与导航

CommandPurpose
pb browse <url>
Open URL in best available browser on the phone
pb top-activity
Show current foreground activity
命令用途
pb browse <url>
在手机上最合适的可用浏览器中打开URL
pb top-activity
显示当前前台Activity

Files & Clipboard

文件与剪贴板

CommandPurpose
pb ls <path>
List files on device
pb push <local> <remote>
Upload file to device
pb pull <remote>
Download file from device
pb clipboard
Get or set clipboard content
命令用途
pb ls <path>
列出设备上的文件
pb push <local> <remote>
上传文件到设备
pb pull <remote>
从设备下载文件
pb clipboard
获取或设置剪贴板内容

System

系统

CommandPurpose
pb shell <cmd>
Raw shell command (only for non-API commands)
pb display
Screen resolution and density info
命令用途
pb shell <cmd>
原始Shell命令（仅用于非API命令）
pb display
屏幕分辨率和密度信息

Discovery

探索

CommandPurpose
pb list
List all available API paths (filtered, hides aliased ones)
pb list <filter>
Filter API paths by keyword
pb info <alias>
Show details of a specific alias or API path
pb --help
Full help with alias list and usage
When you encounter a task not covered by the aliases above, run 
pb list
to discover additional API paths, or 
pb info <name>
to get parameter details.
命令用途
pb list
列出所有可用API路径（已过滤，隐藏别名对应的路径）
pb list <filter>
按关键词过滤API路径
pb info <alias>
显示指定别名或API路径的详细信息
pb --help
完整帮助，包含别名列表和用法
当你遇到上述别名未覆盖的任务时，请运行
pb list
探索其他API路径，或运行
pb info <name>
获取参数详情。

Advanced: JSON Mode

高级功能：JSON模式

For complex API calls that go beyond what aliases support, use 
-j
to pass a full JSON body:
pb -j '{"package_name":"com.example","class_name":".MainActivity"}' activity/start_activity
You can also read JSON from a file with 
-f
:
pb -f params.json activity/start_activity
pb -f - activity/start_activity    # read from stdin
This is the preferred escape hatch when aliases don't cover your parameters — it still goes through the structured API and returns JSON. Only use 
pb shell
for raw Linux commands that aren't part of the phone's control API.
对于别名支持范围之外的复杂API调用，可以使用
-j
传入完整的JSON请求体：
pb -j '{"package_name":"com.example","class_name":".MainActivity"}' activity/start_activity
你也可以使用
-f
从文件读取JSON：
pb -f params.json activity/start_activity
pb -f - activity/start_activity    # 从标准输入读取
当别名无法覆盖你的参数需求时，这是首选的替代方案——它仍然通过结构化API处理，并且返回JSON。只有当需要运行不属于手机控制API的原始Linux命令时，才使用
pb shell
。

Output Format

输出格式

Every pb command returns JSON to stdout:
json
{"code": 200, "data": ..., "msg": "OK"}
Human-readable messages and logs go to stderr — ignore stderr when parsing responses.
所有pb命令都会向标准输出返回JSON：
json
{"code": 200, "data": ..., "msg": "OK"}
人类可读的消息和日志会输出到标准错误——解析响应时请忽略标准错误的内容。

Interaction Pattern

交互模式

The core loop for operating the phone:
  1. Observe — 
    pb dumpc
    to see current screen state
  2. Locate — find the target element's bounds in the output
  3. Act — 
    pb tap <center_x> <center_y>
    to interact (calculate center from bounds)
  4. Verify — 
    pb dumpc
    again to confirm the action worked
  5. Repeat as needed
Common gestures:
  • Scroll down: 
    pb swipe 540 1500 540 500
  • Scroll up: 
    pb swipe 540 500 540 1500
  • Go back: 
    pb keyevent 4
  • Go home: 
    pb keyevent 3
操作手机的核心循环：
  1. 查看 — 运行
    pb dumpc
    获取当前屏幕状态
  2. 定位 — 在输出中找到目标元素的边界
  3. 执行 — 运行
    pb tap <center_x> <center_y>
    进行交互（根据边界计算中心点）
  4. 验证 — 再次运行
    pb dumpc
    确认操作生效
  5. 根据需要重复上述步骤
常用手势：
  • 向下滚动：
    pb swipe 540 1500 540 500
  • 向上滚动：
    pb swipe 540 500 540 1500
  • 返回：
    pb keyevent 4
  • 返回主页：
    pb keyevent 3

Detailed Operation Guides

详细操作指南

For multi-step tasks, read the relevant guide from 
~/.phonebase/skills/
before starting. Each guide is a Claude-standard skill living at 
<name>/SKILL.md
:
GuidePathRead it when...
install-app
~/.phonebase/skills/install-app/SKILL.md
You need to search for, download, and install an Android app
web-search
~/.phonebase/skills/web-search/SKILL.md
You need to search the web using the phone's browser
Run 
pb skills list
to see all installed guides with their enabled/disabled status. Only read guides that show 
enabled
. Use 
pb skills install <path-or-url>
to add third-party guides; they appear alongside the built-in ones. Additional guides may exist — run 
ls ~/.phonebase/skills/
to see what's there, then read 
<dir>/SKILL.md
inside.
对于多步骤任务，开始前请阅读
~/.phonebase/skills/
下的相关指南。每个指南都是符合Claude标准的技能，存放在
<name>/SKILL.md
路径下：
指南路径适用场景
install-app
~/.phonebase/skills/install-app/SKILL.md
需要搜索、下载和安装Android应用时
web-search
~/.phonebase/skills/web-search/SKILL.md
需要使用手机浏览器搜索网页时
运行
pb skills list
查看所有已安装指南及其启用/禁用状态。仅读取显示
enabled
的指南。使用
pb skills install <path-or-url>
添加第三方指南，它们会和内置指南一起展示。可能存在其他指南——运行
ls ~/.phonebase/skills/
查看已有内容，然后读取对应目录下的
<dir>/SKILL.md
文件。