Devicebase CLI

A cross-platform Go CLI tool for remote device control. Supports Android, HarmonyOS, and iOS devices. Capabilities include tap, swipe, text input, app launching, screenshots, UI hierarchy inspection, and device information retrieval.

When to Activate

• Building AI agents or automation scripts that interact with mobile devices
• Developing mobile app testing pipelines
• Creating remote device control workflows
• Implementing deviceFarm or mobile CI/CD integrations
• Any task requiring programmatic mobile device interaction

Quick Reference

Command Pattern

# Commands requiring device serial
devicebase -s <serial> <subcommand> [args]

# Global commands (no serial required)
devicebase list-devices [flags]

All Commands

Environment Setup

Both environment variables are required. The CLI exits with code 1 if either is missing.

# Install Devicebase CLI on Linux/MacOS (if not already installed)
which devicebase || curl -fsSL https://downloads.devicebase.cn/cli/install.sh | bash
# Install Devicebase CLI on Windows (if not already installed)
powershell -c "irm https://downloads.devicebase.cn/cli/install.ps1 | iex"

# Export API key to environment variable on Linux/MacOS (recommended for repeated use)
export DEVICEBASE_API_KEY="your_api_key"
# Export API key to environment variable on Windows (recommended for repeated use)
$env:DEVICEBASE_API_KEY = "your_api_key"

# Or inline (for one-off commands)
DEVICEBASE_API_KEY=your_api_key \
  devicebase -s <serial> <command>

Global Flags

Missing serial produces:

Error: required flag(s) "--serial" not set

Device Listing

list-devices

List all available devices with their serial numbers, states, and basic info.

devicebase list-devices

# Filter by keyword (brand/model/serial/name)
devicebase list-devices --keyword "iPhone"

# Filter by state (busy/free/offline)
devicebase list-devices --state free

# Combine filters
devicebase list-devices --keyword "Samsung" --state busy

Common workflows:

# Find an available device for testing
devicebase list-devices --state free

# Find a specific device by model
devicebase list-devices --keyword "Pixel"

# Check all iOS devices
devicebase list-devices --keyword "iPhone"

Touch Interactions

All touch commands use pixel coordinates. Format: x,y (horizontal,vertical).

tap

Single tap at coordinates.

devicebase -s <serial> tap 100,200

double-tap

Double tap at coordinates.

devicebase -s <serial> double-tap 540,960

long-press

Long press (touch and hold) at coordinates.

devicebase -s <serial> long-press 200,400

swipe

Swipe from one point to another.

devicebase -s <serial> swipe 100,200,300,400
# Format: x1,y1,x2,y2 (start point to end point)

Common workflows:

# Tap center-bottom of a 1080x1920 screen
devicebase -s <serial> tap 540,1800

# Pull to refresh (swipe up)
devicebase -s <serial> swipe 540,1600,540,200

# Long press to trigger context menu
devicebase -s <serial> long-press 540,960

Navigation

back

Press the back button. Use to navigate back, dismiss dialogs, or close keyboards.

devicebase -s <serial> back

home

Press the home button to return to the home screen.

devicebase -s <serial> home

Workflow:

# Navigate back twice
devicebase -s <serial> back
devicebase -s <serial> back

# Go home then launch an app
devicebase -s <serial> home
devicebase -s <serial> launch-app com.android.settings

App Management

launch-app

Launch an application by its package name (Android/HarmonyOS) or bundle ID (iOS).

# Android
devicebase -s <serial> launch-app com.android.settings

# iOS
devicebase -s <serial> launch-app com.apple.Maps

# HarmonyOS
devicebase -s <serial> launch-app com.huawei.systemmanager

Empty app name is rejected with exit code 1:

Error: app_name cannot be empty

current-app

Get the identifier of the currently foreground app.

devicebase -s <serial> current-app

Workflow:

# Launch and verify
devicebase -s <serial> launch-app com.android.settings
sleep 1
devicebase -s <serial> current-app
# Output: com.android.settings

# Conditional action
CURRENT=$(devicebase -s <serial> current-app)
echo "Current app: $CURRENT"

Text Input

input

Type text into the currently focused text field. The device must have a text field focused (tap it first).

devicebase -s <serial> input "Hello World"

Quote text containing spaces or special characters:

devicebase -s <serial> input "user@example.com"
devicebase -s <serial> input "Password123!"

clear-text

Clear all text in the focused text field.

devicebase -s <serial> clear-text

Workflow:

# Fill a search field
devicebase -s <serial> tap 540,100      # tap search box
devicebase -s <serial> input "android"  # type query
devicebase -s <serial> tap 540,200      # tap search button

# Correct a typo
devicebase -s <serial> input "hello"
devicebase -s <serial> clear-text
devicebase -s <serial> input "world"

# Login form
devicebase -s <serial> tap 540,400
devicebase -s <serial> input "myuser"
devicebase -s <serial> tap 540,600
devicebase -s <serial> input "mypassword"
devicebase -s <serial> tap 900,750

Device Information

device-info

Retrieve device information: status, hardware, connection state, OS version, screen resolution, battery, etc.

devicebase -s <serial> device-info

dump-hierarchy

Dump the current UI accessibility tree as JSON. Returns nodes with attributes like resource-id, text, class, bounds, clickable, enabled.

devicebase -s <serial> dump-hierarchy

Use cases:

• Inspect UI layout to find element coordinates
• Verify UI state after interactions
• Build selectors for automation

screenshot

Capture the device screen as an image.

# Save to file
devicebase -s <serial> screenshot -o screen.png

# Output to stdout (for piping)
devicebase -s <serial> screenshot > screen.png

# Output to stdout (for base64)
devicebase -s <serial> screenshot | base64

Workflow:

# Capture state for analysis
devicebase -s <serial> screenshot -o /tmp/state.png

# Find a button's coordinates from hierarchy
devicebase -s <serial> dump-hierarchy | jq '.nodes[] | select(.text == "Submit") | .bounds'

# Full inspection pipeline
devicebase -s <serial> screenshot -o /tmp/screen.png
devicebase -s <serial> dump-hierarchy > /tmp/hierarchy.json
devicebase -s <serial> device-info > /tmp/device.json

AI Agent Integration

Sequential Actions

devicebase -s <serial> launch-app com.android.settings
sleep 2
devicebase -s <serial> tap 540,500
sleep 1
devicebase -s <serial> input "Wi-Fi"

Conditional Execution

CURRENT=$(devicebase -s <serial> current-app)
if [ "$CURRENT" = "com.android.settings" ]; then
    devicebase -s <serial> back
else
    devicebase -s <serial> launch-app com.android.settings
fi

Hierarchy-Driven Navigation

# Find and tap a button from the hierarchy
devicebase -s <serial> dump-hierarchy | jq -r '
  .nodes[]
  | select(.text == "Continue" and .enabled == true)
  | .bounds
' | while read -r bounds; do
  # Parse bounds [x,y][x,y] and tap center
  devicebase -s <serial> tap 540,960
done

Multi-Device Orchestration

# Control multiple devices in parallel
devicebase -s device1_serial tap 100,200 &
devicebase -s device2_serial tap 300,400 &
devicebase -s device3_serial tap 500,600 &
wait

Error-Aware Execution

if devicebase -s <serial> launch-app com.example.app; then
    echo "App launched successfully"
else
    echo "Failed to launch app"
    devicebase -s <serial> screenshot -o /tmp/error.png
    exit 1
fi

Error Reference

CLI Errors

Environment Errors

Critical Rules

1. Always use -s <serial> — every command requires the device serial.
2. Set both environment variables — DEVICEBASE_BASE_URL and DEVICEBASE_API_KEY before running.
3. Use comma-separated coordinates — 100,200, NOT 100 200.
4. Quote text with spaces — input "Hello World".
5. Screenshot defaults to stdout — use -o file to save to a file.
6. Exit code 1 on any error — both bad input and API failures cause non-zero exit.