1  # Using OpenCLI with Android Chrome
  2  
  3  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.
  4  
  5  ---
  6  
  7  ## How It Works
  8  
  9  Android Chrome supports [remote debugging via CDP](https://developer.chrome.com/docs/devtools/remote-debugging/). 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.
 10  
 11  ```
 12  OpenCLI (CDPBridge)
 13      │  WebSocket (CDP)
 14      ▼
 15  localhost:9222                ← ADB forward
 16      │  adb forward
 17      ▼
 18  Android device
 19    chrome_devtools_remote      ← Chrome's Unix debug socket
 20  ```
 21  
 22  No Chrome extension, no daemon process — just a direct CDP WebSocket connection.
 23  
 24  ---
 25  
 26  ## Prerequisites
 27  
 28  **On the Android device:**
 29  1. Settings → About Phone → tap **Build Number** 7 times to enable Developer Options
 30  2. Settings → Developer Options → enable **USB Debugging**
 31  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.
 32  
 33  **On your machine:**
 34  - [Android Debug Bridge (ADB)](https://developer.android.com/tools/adb) installed and on `$PATH`
 35  - OpenCLI installed (`npm install -g opencli`)
 36  
 37  ---
 38  
 39  ## Step-by-Step Setup
 40  
 41  ### 1. Connect the device
 42  
 43  ```bash
 44  adb devices
 45  ```
 46  
 47  Expected output:
 48  ```
 49  List of devices attached
 50  R5CT443TRDM    device
 51  ```
 52  
 53  If the device shows as `unauthorized`, check for a "Allow USB Debugging?" prompt on the phone and tap **Allow**.
 54  
 55  ### 2. Forward the CDP port
 56  
 57  ```bash
 58  adb forward tcp:9222 localabstract:chrome_devtools_remote
 59  ```
 60  
 61  ### 3. Verify the connection
 62  
 63  ```bash
 64  curl http://localhost:9222/json
 65  ```
 66  
 67  A successful response lists the open tabs:
 68  ```json
 69  [
 70    {
 71      "id": "3941",
 72      "title": "Hacker News",
 73      "type": "page",
 74      "url": "https://news.ycombinator.com",
 75      "webSocketDebuggerUrl": "ws://localhost:9222/devtools/page/3941"
 76    }
 77  ]
 78  ```
 79  
 80  ### 4. Run any OpenCLI command
 81  
 82  ```bash
 83  export OPENCLI_CDP_ENDPOINT=http://localhost:9222
 84  opencli hackernews top --limit 5
 85  ```
 86  
 87  ---
 88  
 89  ## Targeting a Specific Tab
 90  
 91  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:
 92  
 93  ```bash
 94  OPENCLI_CDP_TARGET="twitter" opencli twitter trending
 95  ```
 96  
 97  You can also connect directly to a specific tab's WebSocket URL (from `/json`):
 98  
 99  ```bash
100  OPENCLI_CDP_ENDPOINT=ws://localhost:9222/devtools/page/3941 opencli ...
101  ```
102  
103  ---
104  
105  ## Using Login-Required Adapters
106  
107  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.
108  
109  To check whether an adapter requires login:
110  
111  ```bash
112  opencli zhihu hot --help
113  # Strategy: cookie | Browser: yes | Domain: www.zhihu.com
114  ```
115  
116  If you see `Strategy: cookie`, log into the site on the phone first, then run the command.
117  
118  ---
119  
120  ## Teardown
121  
122  Remove the port forward when done:
123  
124  ```bash
125  adb forward --remove tcp:9222
126  # or remove all forwards:
127  adb forward --remove-all
128  ```
129  
130  ---
131  
132  ## Differences from Desktop Chrome
133  
134  | Feature | Desktop Chrome (BrowserBridge) | Android Chrome (CDPBridge) |
135  |---------|-------------------------------|---------------------------|
136  | Chrome extension required | Yes | No |
137  | Daemon process | Yes (auto-started) | No |
138  | Multi-tab management | Full (`tabs`, `selectTab`) | Not supported |
139  | Cookie session | Desktop browser's cookies | Android browser's cookies |
140  | Touch events | N/A | Not needed (CDP uses DOM events) |
141  | Concurrent devices | N/A | Use different local ports per device |
142  
143  ---
144  
145  ## Multiple Devices
146  
147  To connect to more than one Android device simultaneously, assign each a different local port:
148  
149  ```bash
150  # Device 1
151  adb -s <device1-serial> forward tcp:9222 localabstract:chrome_devtools_remote
152  
153  # Device 2
154  adb -s <device2-serial> forward tcp:9223 localabstract:chrome_devtools_remote
155  
156  # Run commands targeting each device
157  OPENCLI_CDP_ENDPOINT=http://localhost:9222 opencli twitter trending
158  OPENCLI_CDP_ENDPOINT=http://localhost:9223 opencli twitter trending
159  ```
160  
161  ---
162  
163  ## Troubleshooting
164  
165  **`adb devices` shows nothing**
166  - Check USB cable (data cable, not charge-only)
167  - Revoke USB debugging authorizations on the device and re-approve
168  
169  **`curl http://localhost:9222/json` returns empty array `[]`**
170  - Chrome for Android is not open, or has no visible tabs — open a tab and retry
171  - Remote debugging flag in `chrome://flags` may be disabled
172  
173  **`curl http://localhost:9222/json` returns connection refused**
174  - Port forward may have dropped (happens after device screen lock on some ROMs) — re-run `adb forward`
175  
176  **Adapter returns `(no data)` despite a working connection**
177  - The site's API requires authentication: log into the site in Android Chrome first
178  - Confirm with `--verbose` to see which pipeline step returns 0 items