Overview

1
---
2
name: ec-android-cli
3
description: >-
4
 EasyClick ec-android-cli install prerequisites, subcommands, flags, and examples.
5
 Use when a user or Agent needs to run, script, or troubleshoot this CLI; no implementation internals.
6
---
7

8
# ec-android-cli reference
9

10
## Prerequisites
11

12
- **IntelliJ IDEA** running with **EasyClick dev tools** plugin responsive.
13
- **Module name** in CLI matches the IDEA script module name.
14
- Multiple windows/projects: use **`-p`** with the **project root** path as opened in IDEA.
15

16
## Binary and help
17

18
- **Bundled binary** (repo root): **`ec_work_config/android/bin/ec-android-cli`**
19
 - From repo root: `./ec_work_config/android/bin/ec-android-cli -h`
20
 - Agents/scripts should prefer this path over global PATH.
21
 - Set log output format to JSON.
22
- If installed globally: **`ec-android-cli`** (same program; rename locally if needed).
23
- Help: `./ec_work_config/android/bin/ec-android-cli -h` (or `ec-android-cli -h` if on PATH)
24
- Subcommand help: `./ec_work_config/android/bin/ec-android-cli <subcommand> -h`
25

26
## Subcommands
27

28
| Subcommand | Purpose |
29
|-------------------|----------------------------|
30
| `preview` | Preview project |
31
| `run` | Run project |
32
| `stop` | Stop current run |
33
| `build` | Build IEC |
34
| `capture-screen` | Screenshot (from IDEA-connected device; returns path) |
35
| `capture-node` | Capture UI nodes (UIX, XML) and return path |
36
| `ocr-local-image` | OCR local image and output result |
37
| `ocr-screen` | OCR current screen and output result |
38
| `test-image` | Template match test (local image or live screen) |
39
| `monitor` | Stream logs only (no `-m`) |
40

41
**Notes:** Except `monitor`, all subcommands require **`-m` (module name)**; `monitor` does not.
42

43
## Common flags (most subcommands except `monitor`)
44

45
| Flag | Meaning |
46
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
47
| **`-m` / `--module`** | **Required.** IDEA module name. |
48
| **`-p` / `--project`** | Optional. Project root (same path as opened in IDEA). |
49
| **`-f` / `--format`** | Optional. Log line format: `text` or `json`; **default `json`**. |
50
| **`-o` / `--log`** | Optional. **Append** logs to the given file path. |
51
| **`-k` / `--stop-on`** | Optional. When log **contains** this substring, print a hint and **exit** (end log monitoring). For multiple OR conditions, join with **`|||`** (exit if any matches). |
52
| **`-w` / `--monitor-logs`** | Optional. `true` / `false`. **`preview` / `run` / `stop`**: omitting `-w` means **`true`** (follow logs until **Ctrl+C** or `-k` match). **`build`**: omitting `-w` means **`false`** (stop after the operation). Override with `-w true` / `-w false`. |
53
| **`-r` / `--random-log`** | Optional. `true` / `false`. When `true`, auto-generate a log file under **`ai_logs/`**; **cannot be used with `-o`**. |
54

55
**Constraints:** Optional flags must have **valid values**; **`-r` and `-o` are mutually exclusive**.
56

57
**`-k` multi-keyword (general):** All subcommands that support **`-k`** — **`preview` / `run` / `stop` / `build` / `monitor`** — accept **`|||`** for OR: monitoring ends when **any** substring appears.
58

59
**`preview` only:** If **`-k` / `--stop-on`** is omitted, default stop keyword is **`执行UI结束`**; if **`-w`** is omitted, default is **keep monitoring logs** (same as `-w true`).
60

61
**`run` only:** If **`-k`** is omitted, default stop keyword is **`脚本已运行结束`**; if **`-w`** is omitted, default is **keep monitoring logs** (same as `-w true`).
62

63
**`stop` only:** If **`-k`** is omitted, monitoring ends when log contains **`停止失败`**, **`停止运行成功`**, or **`无设备连接`** (**any** match); if **`-w`** is omitted, default is **keep monitoring logs** (same as `-w true`). Explicit **`-k`** overrides (still supports **`|||`** for OR).
64

65
**`build` (compile IEC) only:** If **`-k`** is omitted, monitoring ends when log contains **`release.iec`**, **`编译IEC成功`**, or **`编译失败`** (**any** match).
66

67
## `monitor` only
68

69
Log stream only; no `-m`, `-p`, or `-w`.
70

71
| Flag | Meaning |
72
|---------------------------|--------------------------------|
73
| **`-f` / `--format`** | Same as above: `text` or `json`, default `json`. |
74
| **`-o` / `--log`** | Same as above. |
75
| **`-k` / `--stop-on`** | Same as above. |
76
| **`-r` / `--random-log`** | Same as above (not with `-o`). |
77

78
## Logging habits
79

80
- Routine logs go to **stderr**; with **`-o`** or **`-r`**, also written to file.
81
- Default log line format is **JSON** unless **`-f text`**.
82

83
## Examples
84

85
# Assume repo root; EC = ./ec_work_config/android/bin/ec-android-cli
86
EC=./ec_work_config/android/bin/ec-android-cli
87
$EC preview -m app
88
$EC preview -m app -f json
89
$EC run -m app -f json -o /tmp/easyclick.log
90
$EC run -m app -r true
91
$EC run -m app -w false
92
$EC stop -m app
93
$EC build -m app
94
$EC capture-screen -m app
95
$EC capture-node -m app -d /tmp/nodes
96
$EC ocr-local-image -m app -i /tmp/a.png
97
$EC ocr-screen -m app
98
$EC test-image -m app -s /tmp/s.png
99
$EC monitor
100
$EC monitor -f text -o /tmp/monitor.log -k "完成"
101

102
Multi-project example:
103

104
./ec_work_config/android/bin/ec-android-cli run -m app -p /path/to/project/root
105

106
## `capture-screen`
107

108
- **Purpose**: Take a screenshot; outputs path on success.
109
- **Common short flags**:
110
 - `-n`: `--only-network`
111
 - `-d`: `--dir`
112

113
EC=./ec_work_config/android/bin/ec-android-cli
114
$EC capture-screen -m app
115
$EC capture-screen -m app -n -d /tmp/shots
116

117
## `capture-node` (UIX nodes)
118

119
- **Purpose**: Capture UI nodes; outputs UIX file path on success.
120
- **Common short flags**:
121
 - `-d`: `--dir`
122

123
EC=./ec_work_config/android/bin/ec-android-cli
124
$EC capture-node -m app
125
$EC capture-node -m app -d /tmp/nodes
126

127
## `ocr-local-image`
128

129
- **Purpose**: OCR a local image; outputs result string on success.
130
- **Required**: `-i/--path` local image path
131
- **Optional**:
132
 - `-t/--ocr-type`: `paddleOcrNcnnV5|paddleOcrOnnxV4|paddleOcrOnnxV5|ocrLite` (default `paddleOcrNcnnV5`)
133
 - `-P/--padding`: default `32`
134
 - `-X/--max-side-len`: default `640`
135
 - `-R/--release`: default `false`
136

137
EC=./ec_work_config/android/bin/ec-android-cli
138
$EC ocr-local-image -m app -i /path/to/image.png
139
$EC ocr-local-image -m app -i a.jpg -t paddleOcrOnnxV5 -P 48 -X 960 -R
140

141
## `ocr-screen`
142

143
- **Purpose**: OCR current screen; outputs result string on success.
144
- **Optional** (same as `ocr-local-image`, no `--path`):
145
 - `-t/--ocr-type` (default `paddleOcrNcnnV5`)
146
 - `-P/--padding` (default `32`)
147
 - `-X/--max-side-len` (default `640`)
148
 - `-R/--release` (default `false`)
149

150
EC=./ec_work_config/android/bin/ec-android-cli
151
$EC ocr-screen -m app
152
$EC ocr-screen -m app -t paddleOcrOnnxV5 -P 48 -X 960 -R
153

154
## `test-image`
155

156
- **Purpose**: Template match test; outputs result string on success.
157
- **Required**: `-s/--small-image-path` template image path
158
- **Optional** (all string values):
159
 - `-T/--test-type`: `1` local image test; `2` live screen test (default `2`). No `--big-image-path` when `test-type=2`
160
 - `-B/--big-image-path`: large image path (only when `test-type=1`)
161
 - `-F/--func`: `findImageByColor|findImage|matchTemplate` (default `findImage`)
162
 - `-M/--method`: template match method (default `5`)
163
 - `-g/--range`: default `0,0,0,0`
164
 - `-l/--limit`: default `1`
165
 - `-L/--max-level`: default `-1`
166
 - `-E/--weak-threshold`: default `0.7`
167
 - `-H/--threshold`: default `0.8`
168
 - `-C/--opencv-mat`: `1` no; `2` yes (default `1`)
169

170
EC=./ec_work_config/android/bin/ec-android-cli
171
$EC test-image -m app -s /tmp/s.png
172
$EC test-image -m app -T 1 -s s.png -B b.png -F matchTemplate -M 5
173
$EC test-image -m app -F findImage -g 0,0,0,0 -l 1 -E 0.7 -H 0.8

1
logd(msg)/logi(msg)/logw(msg)/loge(msg) // Log output (blue/green/yellow/red)
2
toast(msg) // Toast message
3
sleep(ms) // Sleep (milliseconds)
4
exit() // Exit script
5
startEnv() // Start accessibility service
6
isServiceOk() // Check service status

1
text(str)/textMatch(reg) // Text contains / regex
2
textStartsWith(str)/textEndsWith(str) // Text starts/ends with
3
desc(str)/descMatch(reg) // Description contains / regex
4
id(str)/idMatch(reg) // ID contains / regex
5
clz(str)/clzMatch(reg) // Class name contains / regex
6
pkg(str)/pkgMatch(reg) // Package name contains / regex
7
bounds(l,t,r,b) // Bounds
8
selector.and(s2)/selector.or(s2) // AND / OR conditions

1
// Get nodes
2
selector.getOneNodeInfo(timeout) // Get one node
3
selector.getNodeInfo(timeout) // Get all matching nodes
4
selector.has() // Check existence
5
selector.waitExistNode(timeout) // Wait for node
6
// Node properties
7
node.text/node.desc/node.id/node.clz/node.pkg // Text/desc/ID/class/package
8
node.bounds // Bounds {l,t,r,b}
9
node.clickable/node.visible/node.childCount // Clickable/visible/child count
10
// Node actions
11
node.click()/node.longClick() // Click/long press
12
node.inputText(content)/node.clearText() // Input/clear text
13
node.scrollForward()/node.scrollBackward()// Scroll forward/back
14
node.parent()/node.child(index) // Parent/child node

1
clickPoint(x,y)/longClickPoint(x,y)/doubleClickPoint(x,y) // Click/long press/double tap
2
swipeToPoint(x1,y1,x2,y2,duration) // Swipe to coordinates
3
swipeUp()/swipeDown()/swipeLeft()/swipeRight() // Swipe up/down/left/right
4
touchDown(x,y)/touchMove(x,y)/touchUp(x,y)// Touch control
5
inputText(selectors,content) // Input text
6
clearTextField(selectors) // Clear text
7
getOneNodeInfo(selectors,timeout) // Get one node
8
has(selectors)/waitExistNode(selectors,timeout) // Check/wait for node
9
dumpXml() // Get node XML

1
device.getScreenWidth()/getScreenHeight() // Screen width/height
2
device.getIMEI()/getBrand()/getModel() // IMEI/brand/model
3
device.getAndroidId()/getMacAddress() // Android ID/MAC
4
device.getBrightness()/setBrightness(b) // Get/set brightness
5
device.getBattery() // Battery level
6
device.vibrate(millis) // Vibrate

1
utils.openApp(packageName) // Open app
2
utils.openAppByName(appName) // Open by name
3
utils.isAppExist(packageName) // Check if installed
4
utils.getAppVersionCode(packageName) // Get version code
5
utils.showLogWindow()/hideLogWindow() // Show/hide log window

1
image.requestScreenCapture(timeout,type) // Request screenshot permission
2
image.captureScreen() // Capture screen
3
image.captureToFile(retry,x,y,ex,ey,path) // Save screenshot to file
4
image.readImage(path)/saveImage(img,path) // Read/save image
5
image.findImageEx(template,x,y,ex,ey,weakThresh,thresh,limit,method) // Find image
6
image.findColorEx(color,thresh,x,y,ex,ey,limit,orz) // Find color
7
image.findMultiColorEx(firstColor,points,thresh,x,y,ex,ey,limit,orz) // Multi-point color
8
img.getWidth()/getHeight() // Width/height
9
img.pixel(x,y) // Pixel color
10
img.recycle() // Release image

1
let ocrInst=ocr.newOcr()
2
ocrInst.initOcr({"type":"paddleOcrNcnnV5","numThread":2,"padding":32,"maxSideLen":640})
3
let results=ocrInst.ocrImage(img,timeout,map) // Returns [{label,confidence,x,y,width,height}]
4
ocrInst.ocrFile(path,timeout,map) // OCR image file
5
ocrInst.releaseAll() // Release resources

1
file.readFile(path)/writeFile(data,path) // Read/write
2
file.copyFile(src,dest)/moveFile(src,dest)// Copy/move
3
file.deleteFile(path) // Delete
4
file.exists(path)/isFile(path)/isDir(path)// Exists/file/directory
5
file.create(path)/listDir(path) // Create/list directory

1
http.httpGetDefault(url,timeout,headers) // GET
2
http.httpPost(url,params,files,timeout,headers) // POST
3
http.postJSON(url,json,timeout,headers) // POST JSON
4
http.downloadFile(remoteUrl,file,timeout,headers) // Download file

1
sqlite.connectOrCreateDb(dbName) // Connect/create DB
2
sqlite.createTable(tableName,columns) // Create table
3
sqlite.insert(tableName,map) // Insert
4
sqlite.update(tableName,map,where) // Update
5
sqlite.query(sql)/execSql(sql) // Query/execute SQL
6
sqlite.close() // Close DB

1
thread.execAsync(runnable) // Run async; returns thread ID
2
thread.cancelThread(threadId)/stopAll() // Cancel thread/all
3
setTimeout(func,timeout) // Delayed run
4
setInterval(func,interval) // Periodic run

1
ui.layout(name,content) // Load XML layout
2
ui.findViewById(id) // Find view by ID
3
ui.setVisibility(view,visibility) // Set visibility
4
ui.setText(view,text)/getText(view) // Set/get text
5
ui.setEvent(view,eventType,callback) // Event listener
6
ui.putShareData(key,value)/getShareData(key) // Shared data get/set
7
ui.customDialog(params,view,bind,dismiss) // Custom dialog

1
shell.installApp(path) // Install APK
2
shell.uninstallApp(packageName) // Uninstall app
3
shell.stopApp(packageName) // Stop app
4
shell.execCommand(command) // Run shell command
5
shell.sudo(command) // Run root command

1
// Bluetooth HID
2
bleEvent.startConnect(name,save,timeout) // Connect Bluetooth device
3
bleEvent.isConnected() // Connected?
4
bleEvent.clickPoint(x,y)/swipe(x0,y0,x1,y1,duration) // Tap/swipe
5
bleEvent.home()/back() // Home/back
6
// OTG HID
7
otgEvent.init()/connectFirst() // Init/connect
8
otgEvent.isConnected() // Connected?
9
otgEvent.clickPoint(x,y)/swipe(x0,y0,x1,y1,duration) // Tap/swipe

1
// Point
2
point.click()/longClick()/doubleClick() // Click/long press/double tap
3
// Rect
4
rect.click()/clickRandom() // Click center/random point
5
// String
6
str.contains(s)/replaceAll(s1,s2)/trim()/toInt() // Contains/replace/trim/to int

1
// Start environment
2
function main(){if(!autoServiceStart(3)){loge("Service start failed");return;}}
3
function autoServiceStart(time){for(let i=0;i<time;i++){if(isServiceOk())return true;startEnv();sleep(1000);}return isServiceOk();}
4
main();
5
// Find and click
6
let node=text("Recommended").getOneNodeInfo(0);if(node)node.click();else loge("Not found");
7
// Swipe
8
let w=device.getScreenWidth(),h=device.getScreenHeight();swipeToPoint(w/2,h*0.8,w/2,h*0.2,500);
9
// OCR
10
let ocrInst=ocr.newOcr();ocrInst.initOcr({"type":"paddleOcrNcnnV5","numThread":2,"padding":32,"maxSideLen":640});let img=image.captureScreen();let results=ocrInst.ocrImage(img,5000,null);if(results)for(let i=0;i<results.length;i++)logd(results[i].label);ocrInst.releaseAll();