jackwener--opencli/docs/advanced/android-chrome.md

Using OpenCLI with Android Chrome

OpenCLI can control Chrome on a connected Android device via ADB port forwarding and CDPBridge — no extra tools or custom builds required. The same adapters that run on desktop Chrome work identically on Android, reusing whatever cookies are already in the mobile browser.

---

How It Works

Android Chrome supports remote debugging via CDP. The device exposes a local Unix socket that ADB can forward to a TCP port on your machine. OpenCLI's CDPBridge then connects to that port exactly as it would to any other CDP endpoint.

OpenCLI (CDPBridge)
    │  WebSocket (CDP)
    ▼
localhost:9222                ← ADB forward
    │  adb forward
    ▼
Android device
  chrome_devtools_remote      ← Chrome's Unix debug socket

No Chrome extension, no daemon process — just a direct CDP WebSocket connection.

---

Prerequisites

On the Android device:

1. Settings → About Phone → tap Build Number 7 times to enable Developer Options
2. Settings → Developer Options → enable USB Debugging
3. In Chrome for Android, open chrome://flags, search for DevTools remote debugging, and enable it (Chrome 119+). On older versions this is on by default when USB debugging is active.

On your machine:

• Android Debug Bridge (ADB) installed and on $PATH
• OpenCLI installed (npm install -g opencli)

---

Step-by-Step Setup

1. Connect the device

adb devices

Expected output:

List of devices attached
R5CT443TRDM    device

If the device shows as unauthorized, check for a "Allow USB Debugging?" prompt on the phone and tap Allow.

2. Forward the CDP port

adb forward tcp:9222 localabstract:chrome_devtools_remote

3. Verify the connection

curl http://localhost:9222/json

A successful response lists the open tabs:

[
  {
    "id": "3941",
    "title": "Hacker News",
    "type": "page",
    "url": "https://news.ycombinator.com",
    "webSocketDebuggerUrl": "ws://localhost:9222/devtools/page/3941"
  }
]

4. Run any OpenCLI command

export OPENCLI_CDP_ENDPOINT=http://localhost:9222
opencli hackernews top --limit 5

---

Targeting a Specific Tab

When multiple tabs are open, CDPBridge picks the best one automatically using a scoring algorithm (prefer type=page, real URLs over about:blank, etc.). To override this, set OPENCLI_CDP_TARGET to a substring of the tab's title or URL:

OPENCLI_CDP_TARGET="twitter" opencli twitter trending

You can also connect directly to a specific tab's WebSocket URL (from /json):

OPENCLI_CDP_ENDPOINT=ws://localhost:9222/devtools/page/3941 opencli ...

---

Using Login-Required Adapters

Adapters that use the cookie strategy (most social/content sites) need you to be logged in on the Android device. The cookies are already in Android Chrome — OpenCLI reads them automatically over CDP.

To check whether an adapter requires login:

opencli zhihu hot --help
# Strategy: cookie | Browser: yes | Domain: www.zhihu.com

If you see Strategy: cookie, log into the site on the phone first, then run the command.

---

Teardown

Remove the port forward when done:

adb forward --remove tcp:9222
# or remove all forwards:
adb forward --remove-all

---

Differences from Desktop Chrome

Feature	Desktop Chrome (BrowserBridge)	Android Chrome (CDPBridge)
Chrome extension required	Yes	No
Daemon process	Yes (auto-started)	No
Multi-tab management	Full (tabs, selectTab)	Not supported
Cookie session	Desktop browser's cookies	Android browser's cookies
Touch events	N/A	Not needed (CDP uses DOM events)
Concurrent devices	N/A	Use different local ports per device

---

Multiple Devices

To connect to more than one Android device simultaneously, assign each a different local port:

# Device 1
adb -s <device1-serial> forward tcp:9222 localabstract:chrome_devtools_remote

# Device 2
adb -s <device2-serial> forward tcp:9223 localabstract:chrome_devtools_remote

# Run commands targeting each device
OPENCLI_CDP_ENDPOINT=http://localhost:9222 opencli twitter trending
OPENCLI_CDP_ENDPOINT=http://localhost:9223 opencli twitter trending

---

Troubleshooting

adb devices shows nothing

• Check USB cable (data cable, not charge-only)
• Revoke USB debugging authorizations on the device and re-approve

curl http://localhost:9222/json returns empty array []

• Chrome for Android is not open, or has no visible tabs — open a tab and retry
• Remote debugging flag in chrome://flags may be disabled

curl http://localhost:9222/json returns connection refused

• Port forward may have dropped (happens after device screen lock on some ROMs) — re-run adb forward

Adapter returns (no data) despite a working connection

• The site's API requires authentication: log into the site in Android Chrome first
• Confirm with --verbose to see which pipeline step returns 0 items