PhoneBase Docs

English

简体中文

English

简体中文

Appearance

Quick Start ​

Welcome to PhoneBase! This guide takes you from zero to controlling a real Android cloud phone in about 5 minutes. You'll install the CLI, create a device, interact with it, and run your first Skill.

Prerequisites ​

Before you start, make sure you have:

  • A PhoneBase account — Sign up at phonebase.cloud to get your API key (first $5 of usage is free, no credit card required)
  • The pb CLI installed — See the Installation guide if you haven't installed it yet

Step 1: Login ​

Authenticate with your PhoneBase account. The CLI opens your default browser for a secure OAuth login:

bash
pb login

Expected output:

Opening browser for login...
Your one-time code: ABCD-1234
Waiting for authentication... (298s)
✓  Login successful

Alternative: API Key Authentication

If you prefer to skip the browser flow (useful for servers and CI/CD), set your API key directly:

bash
pb apikey <your-api-key>

Verify your login status and account balance:

bash
pb status
json
{
  "code": 0,
  "data": {
    "authenticated": true,
    "auth_type": "token",
    "balance_cents": 500
  }
}

Step 2: Create a Cloud Phone ​

Allocate a new Android cloud phone:

bash
pb devices create
✓ Device created
  device_code  IDY291LX6WW6RCW
  status       starting

INFO

The device_code (e.g., IDY291LX6WW6RCW) is the identifier you'll use in all subsequent commands. Save it -- you'll need it in the next steps.

Confirm the device appears in your device list:

bash
pb devices list
CODE               STATUS         ONLINE   CONNECTED  STARTED_AT
IDY291LX6WW6RCW   running        yes      -          2026-04-09T10:30:00Z

Step 3: Connect to the Device ​

Connect to your cloud phone:

bash
pb connect IDY291LX6WW6RCW
✓ Connected to device IDY291LX6WW6RCW

TIP

A background process is automatically started to manage the connection. You don't need to keep the terminal open -- the connection persists until you explicitly disconnect.

Step 4: First Device Interactions ​

Now that you're connected, try some basic commands:

Take a Screenshot ​

Capture the current screen and save it as a JPG image:

bash
pb screencap
✓ Screenshot saved: ~/.phonebase/data/screencap/20260409/IDY291LX6WW6RCW-20260409103500.jpg (45.2 KB)

Tap the Screen ​

Tap at the center of a typical phone screen (1080x1920):

bash
pb tap 540 960
json
{
  "code": 0,
  "msg": "ok"
}

Type Text ​

Input text into the currently focused field:

bash
pb text "Hello PhoneBase"
json
{
  "code": 0,
  "msg": "ok"
}

Press a Key ​

Send an Android key event (e.g., go back to the home screen):

bash
pb keyevent HOME
json
{
  "code": 0,
  "msg": "ok"
}

Supported Key Names

Common key names: HOME, BACK, ENTER, DELETE, POWER, VOLUME_UP, VOLUME_DOWN, TAB, SPACE, MENU, SEARCH, ESCAPE. You can also use numeric key codes (e.g., pb keyevent 3 for HOME).

Inspect the Screen (Screenshot + UI Layout) ​

For a deeper look at the device state, use inspect to get both a screenshot and the UI layout tree:

bash
pb inspect
✓ Inspect complete: IDY291LX6WW6RCW

  inspect:    ~/.phonebase/data/inspect/20260409/IDY291LX6WW6RCW-20260409103600-inspect.html
  screenshot: ~/.phonebase/data/inspect/20260409/IDY291LX6WW6RCW-20260409103600-screenshot.jpg
  layout:     ~/.phonebase/data/inspect/20260409/IDY291LX6WW6RCW-20260409103600-layout.xml

  Cmd+Click inspect.html to open in browser

TIP

The inspect.html file provides an interactive visual inspector with the UI layout overlaid on the screenshot. This is especially useful for AI agents that need to understand the screen context.

Step 5: Run Your First Skill ​

Skills are reusable automation scripts for common app operations. Install the built-in skills:

bash
pb skills install
✓ 8 built-in skills installed

  Installing global skills (phonebase-skills)...
✓ Global skills installed

List available skills:

bash
pb skills list
NAME          KIND      ENABLED  VERSION  DESCRIPTION
googleplay    builtin   yes      1.0.0    Google Play Store automation
settings      builtin   yes      1.0.0    Android Settings automation
...

Now run a skill -- for example, open Google Play:

bash
pb googleplay open

Search for an app:

bash
pb googleplay search --keyword "twitter"

TIP

Each skill exposes multiple subcommands. Use pb <skill-name> --help to see all available operations for a skill.

Step 6: AI Agent Integration ​

Every pb command outputs structured JSON when running in a non-TTY context (e.g., when called by Claude Code or other AI agents). This means AI agents can directly parse the output without any additional processing.

For example, when Claude Code runs:

bash
pb inspect

It receives:

json
{
  "code": 0,
  "msg": "Inspect complete: IDY291LX6WW6RCW",
  "data": {
    "inspect": "/Users/you/.phonebase/data/inspect/20260409/...-inspect.html",
    "screenshot": "/Users/you/.phonebase/data/inspect/20260409/...-screenshot.jpg",
    "layout": "/Users/you/.phonebase/data/inspect/20260409/...-layout.xml"
  }
}

The agent reads the screenshot to "see" the phone, analyzes the layout tree to understand the UI structure, and issues the next pb command -- all without any custom API integration.

INFO

You can also force JSON output in an interactive terminal by setting PHONEBASE_OUTPUT=json. See Environment Variables for details.

Step 7: Disconnect ​

When you're done, disconnect from the device:

bash
pb disconnect
✓ Disconnected

WARNING

Disconnecting does not stop or delete the device. The device continues running and billing continues. To stop billing, explicitly stop or delete the device:

bash
# Stop the device (can be started again later)
pb devices stop IDY291LX6WW6RCW

# Or delete the device permanently
pb devices delete IDY291LX6WW6RCW

Next Steps ​

You now have a working PhoneBase setup. Here's where to go next:

  • Connect Device — Learn about device lifecycle, modes, and multi-device management
  • CLI Reference — Complete reference for all pb commands
  • Skill Hub — Browse all available automation skills

Copyright © 2026 PhoneBase