PhoneBase Docs

English

简体中文

English

简体中文

Appearance

CLI Overview ​

pb is the command-line interface for PhoneBase — a cloud phone automation platform. It gives you full control over Android cloud devices from your terminal: manage device lifecycle, interact with screens, install apps, transfer files, and run automation skills.

GitHub: https://github.com/phonebase-cloud/phonebase-cli

All output is structured JSON by default when called by AI agents or scripts. In interactive terminals, output is displayed as human-friendly tables and messages.

Global Flags ​

FlagDescription
-s, --device <id>Target device ID (applies to all commands)
-j, --json <body>Pass a JSON body directly to the API
-f, --file <path>Read JSON body from a file (- for stdin)
-V, --versionPrint CLI version
-h, --helpPrint help information

TIP

The -s flag is global -- it works with any command to specify which device to operate on. If omitted, the currently connected device is used.

Environment Variables ​

VariableDescriptionExample
PHONEBASE_API_KEYAPI key for authenticationpb_sk_xxxxxxxxxxxx
PHONEBASE_API_URLAPI gateway URLhttps://api.phonebase.cloud
PHONEBASE_LANGCLI language (en / zh)en
PHONEBASE_OUTPUTOutput format (json / text)json

INFO

Environment variables take precedence over config file values.

Temporary (current session only):

bash
# Prepend to a single command
PHONEBASE_OUTPUT=json pb devices

# Or export for the entire session
export PHONEBASE_API_KEY=pb_sk_xxxxxxxxxxxx

Permanent (persist across sessions):

bash
echo 'export PHONEBASE_API_KEY=pb_sk_xxxxxxxxxxxx' >> ~/.zshrc
source ~/.zshrc
bash
echo 'export PHONEBASE_API_KEY=pb_sk_xxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc

Output Format ​

pb automatically detects who is calling — human or AI — and adjusts the output format accordingly.

WhoFormatForce
HumanFriendly tables and colored messagesPHONEBASE_OUTPUT=text
AIStructured JSONPHONEBASE_OUTPUT=json

For example, pb devices outputs differently depending on the caller:

Human sees:

CODE               STATUS    ONLINE   CONNECTED  STARTED_AT
IDY291LX6WW6RCW   running   yes      yes        2025-01-15T08:30:00Z
IDY2A0ZNVOR00ZK   stopped   no       -          -

AI sees:

json
{
  "code": 200,
  "data": {
    "devices": [
      {
        "device_code": "IDY291LX6WW6RCW",
        "plex_status": "running",
        "is_online": true,
        "connected": true,
        "started_at": "2025-01-15T08:30:00Z"
      }
    ]
  },
  "msg": "OK"
}

Copyright © 2026 PhoneBase