DevEco CLI 将 DevEco Studio 工具链统一封装为一个 CLI，内置 ohpm、hvigor、hdc、emulator、hilog，同时集成 HarmonyOS 技能安装、项目脚手架、本地 HarmonyOS 文档检索和 MCP 服务。

关于数据采集与隐私（遥测打点内容、存储加密、上报及关闭方式），请参阅 PRIVACY.md。

快速开始

前置要求

• 操作系统为 macOS 、 Windows 或 Linux（需配置对应环境变量）
• 安装Node.js，推荐使用22及以上版本
• DevEco Studio >= 6.0.0 或 Command Line Tools >= 26.0.0
  • macOS：必须安装在 ~/Applications 或 /Applications 目录下。

安装

npm install -g @deveco/deveco-cli@latest

安装后可以通过以下命令更新到最新版本：

devecocli update

最短工作流

devecocli create --app-name MyApp
cd MyApp
devecocli run
devecocli log --level E

文档检索

devecocli docs search List
devecocli docs read guides/harmonyos-guides/指南/系统/网络/网络

更多命令和参数可通过 devecocli --help 或各子命令的 --help 查看。

环境变量

devecocli 当需要使用非默认安装路径、多版本并存时固定选型，Command Line Tools或在Linux下运行时，可通过以下环境变量显式指定工具链根：

完整优先级链：

DEVECO_CLI_STUDIO_PATH > DEVECO_CLI_CLT_PATH > Auto_Detect

平台与版本约束

使用示例

# 设置 DevEco Studio
export DEVECO_CLI_STUDIO_PATH="/Applications/DevEco-Studio.app" （可带或不带尾部 Contents）
devecocli device list

# 设置 CLT
export DEVECO_CLI_CLT_PATH=/opt/command-line-tools
devecocli device list

区域与海外支持

devecocli 支持中国大陆（CN）、香港（HK）和澳门（MO）三个区域。其他地区的在线能力（登录、签名、协议查询、镜像下载、知识库下载等）不可用，纯本地命令（create/build/device 等）不受影响。

港澳地区（HK/MO）下，Skills 市场云端命令（skills list/find/add）不可用；已安装 skills 为本地文件，不受影响。

AI Agent 集成

Agent 插件

支持插件的 Agent 可加载 DevEco CLI 插件，获得内置 Skill 和 CLI 检查、安装及调用能力。

插件使用方法见 插件说明，支持的 Agent 及其差异由 平台配置 定义。

命令行安装 Skill / MCP

DevEco CLI 支持通过命令行将自身技能添加到 Agent 中。下面以 opencode 为例展示最短流程：

# 1. 给 opencode 安装 deveco-cli 技能
devecocli init --agent opencode

# 2. 给 opencode 在当前 HarmonyOS 项目配置 MCP
devecocli init --mcp --agent opencode --project ./MyApp

# 3. 进入项目并启动 opencode
cd MyApp
opencode

也支持 atomcode等 Agent，使用方式相同：

# 给 atomcode 安装技能
devecocli init --agent atomcode

如果 Agent 不在 --agent 参数取值范围内，可使用 --path 参数进行添加，参考如下命令：

devecocli init --path D:\work\ARKTS\NewData

进入 Agent 后可以直接描述任务，例如：

• Build this project in release mode and run it on my emulator
• Tail the last error logs from this app
• Check for syntax errors in src/main/ets/pages/Index.ets

说明：

• 在Windows上搭配devecocli使用opencode时，推荐将powershell 7 作为默认执行终端。
• 在Windows上用opencode执行devecocli build/emulator start等指令时，若命令结束后终端无法正常退出，建议将默认终端切换为powershell 7

常用命令

命令集

help

查看版本、帮助信息以及所有子命令

命令格式：

devecocli help

# 返回结果
Usage: devecocli [options] [command]

HarmonyOS application development command line tool

Options:
  -V, -v, --version      output the version number
  -h, --help             display help for command

Commands:
  build [options]        Build the HarmonyOS project
  run [options]          Build and run the project on a connected device
  update                 Update deveco-cli to the latest version
  device                 Manage connected devices
  emulator               Manage emulator instances
  auth                   Authentication commands (login, logout, status, team)
  ui                     Inspect and interact with UI on a connected device
  skills                 Manage HarmonyOS skills
  log [options]          Obtain device application logs
  verify [options]       Run UI verification on a connected device
  create [options]       Scaffold a new HarmonyOS application project
  init [options]         Install bundled skills or configure the deveco-mcp server into AI agents
  serve                  Host bundled auxiliary protocol servers
  docs [options]         Search and read HarmonyOS documentation from local docs directory
  check                  Run DevEco project checks
  signature              Generate application signature
  help [command]         display help for command

design2arkts（别名 d2a）

从 Pixso/Figma 设计稿开发 ArkUI 页面：CLI 提供输入快照、导出、资源准备与受保护导入工具，Agent 按内置 Skill 指引完成分析与生成；完整流程、独立能力（视觉校准、HDS 迁移、React 转换、方案设计）、参数与导入保护见 D2A 使用指南。

方案设计聚焦 UI 页面，仓库分析限于目标页面及关联代码；Pixso 流程由工程理解进入方案设计，组件选型在方案设计中完成。

init

将内置 Skill（deveco-cli、hmos-arkui-develop-skill、hmos-dfx-analyzer）或者 MCP 服务配置到智能体中。内置 Skill 以软链接方式直连 CLI 包内目录，已安装的链接随 npm update 自动更新内容。

已有 Skill 和 MCP 配置默认跳过。更新已有内容或将复制安装的 Skill 改为软链接，需执行 devecocli init -f（或 --force），旧内容及本地修改会被删除。 可用 --agent、--project 或 --path 选择位置；-f 也允许创建不存在的目标目录。正确安装的软链接随 CLI 更新生效，不需要重复 init；建链失败时回退为复制。CLI 升级新增的内置技能需重新执行 devecocli init 安装。

命令格式：

devecocli init --agent <agents> --project <path> --path <path> --skill --mcp --with-homegraph --force

参数：

示例：

# 配置Skill
devecocli init -f   # 安装或更新全部内置 Skill
devecocli init --skill
devecocli init --agent agentname    # agentname需替换为实际的智能体名称
devecocli init --path D:\work\ARKTS\NewData -f

# 配置MCP
devecocli init --mcp
devecocli init --mcp --agent agentname    # agentname需替换为实际的智能体名称   
devecocli init --mcp --project D:\work\ARKTS\NewData -f
devecocli init --mcp --with-homegraph

MCP 配置支持 opencode、pi、trae-cn、cursor、codebuddy、claude-code 和 codex。

Skill 支持的智能体

支持以下 52 个智能体。使用 --agent 指定名称，多个名称用英文逗号分隔。

amp、antigravity、antigravity-cli、astrbot、atomcode、augment、bob、claude-code、cline、codearts-agent、 codebuddy、codex、continue、crush、cursor、deepagents、deveco、devin、droid、dsh、 gemini-cli、github-copilot、goose、grok、hermes-agent、iflow-cli、junie、kilo、kimi-code-cli、kiro-cli、 kode、lingma、minimax-code、mistral-vibe、neovate、ona、openclaw、opencode、openhands、pi、 qoder、qoder-cn、qwen-code、reasonix、replit、trae、trae-cn、universal、warp、windsurf、 zcode、zed。

未检测到智能体时，可显式指定 --agent 安装。

docs search

将关键词搜索版本说明、指南、API参考、最佳实践、FAQ 、变更预告等中的内容

命令格式：

devecocli docs search <keywords...> --catalog <name> --format <fmt> --limit <n>

参数：

示例：

devecocli docs search 沉浸光感
devecocli docs search '@State' '@Prop' --catalog best-practices --limit 10
devecocli docs search Row Column --format json

docs read

按文档ID查询文档的完整内容

命令格式：

devecocli docs read <documentId> 

参数：

示例：

devecocli docs read guides/harmonyos-guides/指南/系统/网络/网络

docs catalog

查询文档分类和分类名称

命令格式：

devecocli docs catalog --format <fmt> 

参数：

示例：

devecocli docs catalog 
devecocli docs catalog --format json

create

创建 HarmonyOS 应用工程，仅支持创建工程模板中的 Empty Ability 模板

命令格式：

devecocli create --app-name <name> --project-path <path> --bundle-name <bundle> --api-level <level> --device-types <types...>

参数：

示例：

devecocli create --project-path ./MyApp --app-name MyApp
devecocli create --project-path ./MyApp --app-name MyApp --bundle-name com.acme.myapp --api-level 23
devecocli create --app-name MyApp
devecocli create --app-name MyApp --device-types tablet
devecocli create --app-name MyApp --device-types phone wearable

auth login

登录华为开发者账号，打开浏览器完成授权。交互式终端会先等待按 Enter 再拉起浏览器；传入 --no-prompt 可跳过确认直接拉起浏览器（供 Agent / 非交互终端使用；stdin 不是 TTY 时自动跳过）。Agent 执行登录或安装时，沿用会话中已有的相应授权，仅在缺少授权时询问。登录已获授权时直接运行 devecocli auth login --no-prompt，不再要求用户手动执行命令；用户仍需在浏览器完成认证。

命令格式：

devecocli auth login --no-prompt

说明：

• 海外账户暂不支持

auth logout

登出并清除本地存储的凭据

命令格式：

devecocli auth logout

auth status

显示当前登录的用户

命令格式：

devecocli auth status

auth team list

列出当前用户已加入的团队

命令格式：

devecocli auth team list

示例：

devecocli auth team list

build

编译并打包 HarmonyOS 工程或工程中的模块

命令格式：

devecocli build --product <product> --modules <modules> --build-mode <mode> --signing-config <name> [--debug-line]

参数：

示例：

devecocli build --build-mode release
devecocli build --modules entry library
devecocli build --modules library@phone
devecocli build --product oversea --modules entry --build-mode release
devecocli build --product oversea --modules entry --build-mode release --signing-config default_release

说明：

• 选定模块的依赖会被自动解析和构建
• 执行devecocli build --product <name>命令后，产物为 .app
• 执行devecocli build --product <name> --modules <m1>命令后，产物为 .hap / .hsp / .har
• 构建成功后，控制台会打印所有产物的绝对路径（.hap / .hsp / .har / .app），可直接复制使用

build clean

清理 HarmonyOS 项目的构建产物。默认模块模式（--mode module）按模块逐个清理；可指定 --mode 和 --modules 限定作用域。构建选项（analyze/parallel/incremental/daemon 等）由 hvigor-config.json5 的 execution 字段控制，与 DevEco Studio 一致。

命令格式：

devecocli build clean [--mode <mode>] [--modules <m1> <m2>]

参数：

check compat

基于 DevEco Studio 自带的 apkanalyzer-apiscan 插件（≥ 26.0.0.810）或 Command Line Tools 内置的 apicompat 组件（≥ 26.0.1），扫描源代码在两个 SDK 版本之间的 API 变更情况。Linux 下需使用 Command Line Tools。

子命令：

命令格式：

devecocli check compat [files...] --source-version <ver> --target-version <ver> [--modules <m...>] [--format <default|csv|json>] [--output-path <path>] [--limit <n>]

参数：

版本号说明：

• 可用版本可通过 devecocli check compat versions 查看
• zsh 环境下版本号需用引号包裹（包含括号），例如 "<source_version>"、"<target_version>"

compat versions 参数：

格式与输出组合：

示例：

# 工程级扫描，输出到控制台
devecocli check compat --source-version "<source_version>" --target-version "<target_version>"

# 输出 JSON 到控制台
devecocli check compat --format json --source-version "<source_version>" --target-version "<target_version>"

# 输出报告到目录（默认 csv）
devecocli check compat --output-path ./report --source-version "<source_version>" --target-version "<target_version>"

# 输出 JSON 报告到目录（生成 apiChange-res{N}.json）
devecocli check compat --output-path ./report --format json --source-version "<source_version>" --target-version "<target_version>"

# 输出报告到指定文件
devecocli check compat --output-path ./report.json --format json --source-version "<source_version>" --target-version "<target_version>"

# 文件级扫描
devecocli check compat ./entry/src/main/ets/pages/Index.ets --source-version "<source_version>" --target-version "<target_version>"

# 模块级扫描
devecocli check compat --modules entry har1 --source-version "<source_version>" --target-version "<target_version>"

check lint

检查代码规范并输出实践建议与报告。

命令格式：

devecocli check lint [path]

参数：

emulator 版本要求： DevEco Studio ≥ 6.1.0

check arkts

对 .ets 源文件执行 ArkTS 静态检查，基于 DevEco Studio 的 etsStandaloneChecker。

命令格式：

devecocli check arkts [files...] [--fix] [--project <path>]

参数：

示例：

# 检查整个项目
devecocli check arkts

# 检查指定文件并自动修复
devecocli check arkts --fix entry/src/main/ets/pages/Index.ets

# 指定项目路径
devecocli check arkts --project /path/to/project

emulator list

查看模拟器实例

命令格式：

devecocli emulator list [--format <table|json>]
devecocli emulator list --details

参数：

示例：

devecocli emulator list
devecocli emulator list --format json
devecocli emulator list --details

emulator start

启动模拟器。首次使用时，需要签署 HarmonyOS 软件许可与服务协议，具体请参考 emulator license

命令格式：

devecocli emulator start [names...]

参数：

示例：

devecocli emulator start Phone
devecocli emulator start Phone1 Phone2
devecocli emulator start Phone --hdcport 12345
devecocli emulator start Phone --boot-mode coldboot --no-window

说明：

• emulator start 命令仅支持启动 release 版本的模拟器

emulator stop

关闭模拟器

命令格式：

devecocli emulator stop [names...]

参数：

示例：

devecocli emulator stop Phone
devecocli emulator stop 127.0.0.1:5555

emulator 场景操作

控制运行中的模拟器实例，直接映射 DevEco Studio 内置 Emulator 公开命令行参数。新增场景控制命令要求 Emulator 7.0 或更高版本；低版本会直接提示升级。截图不属于模拟器场景操作，统一通过 devecocli ui screenshot 执行。

示例：

devecocli emulator shake --target Phone
devecocli emulator power --target Phone
devecocli emulator rotate left --target Phone
devecocli emulator volume up --target Phone
devecocli emulator fold half-open --target Phone
devecocli emulator battery --target Phone --level 90
devecocli emulator battery --target Phone --status charging
devecocli emulator battery --target Phone --level 80 --status charging
devecocli emulator geolocation --target Phone --longitude 116.40024 --latitude 39.908
devecocli emulator scene outdoorRunning --target Phone
devecocli emulator sensor --target Phone --heartrate 80

说明：

• --target 支持模拟器名称或 127.0.0.1:<port> 序列号。

• battery --level 与 battery --status 可同时传入（一次调用同时设置电量与充电状态）。

• battery --level 会自动查询模拟器当前充电状态：充电时取值范围为整数 [0, 100]，未充电时为 [1, 100]。

• battery --status 取值为 charging 或 discharging。

• --level 0 与 --status discharging 组合非法（电量 0 仅在充电时允许），会被拒绝。

• geolocation 支持 --longitude、--latitude、--altitude、--direction。

• scene 取值为 outdoorRunning、outdoorCycling、drivingNavigation。

• sensor 支持 --light-intensity、--humidity、--temperature、--steps、--heartrate，可同时传入多个。

• geolocation/battery/sensor 多参数为逐项串行下发、非原子：第 N 项失败时前 N−1 项已生效且不回滚，建议失败后整体重跑。

• fold <state> 会根据目标模拟器的设备类型校验状态，设备与参数必须匹配：

  设备类型	支持的 state
  foldable	open、half-open、close
  2in1_foldable	open、vertical-open、half-open、close
  triplefold	single、double、triple、left-folded-right-half-folded、left-half-folded-right-expanded、left-expanded-right-folded、left-half-folded-right-folded、left-expanded-right-half-folded、left-half-folded-right-half-folded

  校验以目标模拟器实际返回的 deviceType 为准。非上述三种设备类型以及不属于目标设备类型的状态会在命令下发前被拒绝。校验通过后，底层映射为 Emulator -instance <name> -foldedState <state>。

• 设置 DEVECO_CLI_DEBUG=1 可查看底层命令映射，例如 Emulator -instance <name> -shake。

emulator create

创建模拟器

命令格式：

devecocli emulator create <name> \
  --device-type <type> \
  --os-version <version> \
  [--instance-path <path>] \
  [--image-root <path>] \
  [--screen-profile <model>] \
  [--screen <config...>] \
  [--storage <size>] \
  [--memory <size>] \
  [--hot-boot <true|false>] \
  [--force]

参数：

--screen-profile 和 --screen 可同时指定，此时使用 --screen。

示例：

devecocli emulator create MyPhone --device-type phone --os-version "HarmonyOS 6.0.1(21)"

devecocli emulator create MyPhone \
  --device-type phone \
  --os-version "HarmonyOS 6.0.1(21)" \
  --screen-profile "Mate 70 Pro" \
  --storage 8 \
  --memory 8

devecocli emulator create Foldable \
  --device-type foldable \
  --os-version "HarmonyOS 6.0.1(21)" \
  --screen "2200 2480 480 7.8" "1080 2480 480 6.4"

emulator delete

删除模拟器

命令格式：

devecocli emulator delete <name> [--instance-path <path>]

参数：

示例：

devecocli emulator delete MyPhone

devecocli emulator delete MyPhone --instance-path /custom/instance/path

emulator image list

查询模拟器镜像列表

命令格式：

devecocli emulator image list --device-type <type> --all --format <format>

参数：

示例：

devecocli emulator image list
devecocli emulator image list --all
devecocli emulator image list --device-type phone
devecocli emulator image list --format json

emulator image download

下载模拟器镜像。首次使用时，需要签署 HarmonyOS SDK 许可协议，具体请参考 emulator license

命令格式：

devecocli emulator image download --device-type <type> --os-version <version> --force

参数：

示例：

devecocli emulator image download --device-type phone --os-version "HarmonyOS 6.0.1(21)" --force

说明：

• emulator image download 命令仅支持下载 release 版本的模拟器镜像

emulator image remove

删除模拟器镜像

命令格式：

devecocli emulator image remove --device-type <type> --os-version <version>

参数：

示例：

devecocli emulator image remove --device-type phone --os-version "HarmonyOS 6.0.1(21)"

emulator license view

查看协议文本（只读）

命令格式：

devecocli emulator license view

emulator license

交互式查看并接受协议。打印完整协议文本后提示 y/N 确认。使用模拟器需要同意 HarmonyOS 软件许可与服务协议，下载镜像需要同意 HarmonyOS SDK 许可协议。若已同意则直接提示已接受。非交互终端下会报错，请改用 emulator license accept

命令格式：

devecocli emulator license

emulator license accept

非交互式同意模拟器所有协议，直接写入同意记录，跳过协议展示和确认提示。适用于 Agent、自动化脚本、CI 或非交互终端环境。若已同意则直接提示已接受。Agent 遇到协议阻塞时，沿用用户已有的协议接受授权，直接执行此命令，成功后继续原操作；仅在缺少授权时询问。需要查看协议内容时使用只读的 devecocli emulator license view。

命令格式：

devecocli emulator license accept

device list

查询所有已连接的设备，包括真机设备和运行中的模拟器

命令格式：

devecocli device list [--format <table|json>]

参数：

device view

查询已连接的设备的详细信息，包括设备序列号、设备名称、设备类型、 OS 版本等

命令格式：

devecocli device view [--target <serialOrName>] [--format <table|json>]

参数：

示例：

devecocli device view
devecocli device view --target 127.0.0.1:5555
devecocli device view -t "My Device Name"
devecocli device view -t 127.0.0.1:5555 --format json

device file

在主机与设备（真机或模拟器）之间传输文件，以及检查、删除设备端文件。

命令格式：

devecocli device file [--device <name|serial>] send <src> <dst>
devecocli device file [--device <name|serial>] recv <src> <dst>
devecocli device file [--device <name|serial>] exist <path>
devecocli device file [--device <name|serial>] delete <path>

参数：

示例：

devecocli device file send ./local.txt /data/local/tmp/remote.txt
devecocli device file recv /data/local/tmp/remote.txt ./local.txt --device 127.0.0.1:5555
devecocli device file exist /data/local/tmp/testfile.txt
devecocli device file delete /data/local/tmp/testfile.txt

device sqlite3

在设备上执行 sqlite3，底层映射为 hdc -t <serial> shell sqlite3 <db-path> [args...]，后续参数原样透传给设备的 sqlite3。

命令格式：

devecocli device sqlite3 [--device <name|serial>] <db-path> [args...]

参数：

示例：

devecocli device sqlite3 /data/app/el2/100/database/com.example.app/foo.db "select * from user limit 5" -json

device app

管理设备上的应用，包括安装、卸载、查询、启动、停止和数据清理。

子命令：

命令格式：

devecocli device app install [files...] [--replace] [--shared <path>] [--wait <seconds>] [--user <userId>] [--device <name|serial>]
devecocli device app uninstall --bundle <name> [--device <name|serial>]
devecocli device app list [--format <default|json>] [--device <name|serial>]
devecocli device app info <bundleName> [--format <default|json>] [--device <name|serial>]
devecocli device app foreground [--format <default|json>] [--device <name|serial>]
devecocli device app start [--bundle <name>] [--ability <name>] [--action <action>] [--uri <uri>] [--device <name|serial>]
devecocli device app stop --bundle <name> [--device <name|serial>]
devecocli device app cleardata --bundle <name> [--device <name|serial>]
devecocli device app clearcache --bundle <name> [--device <name|serial>]

参数：

示例：

devecocli device app install /path/to/app.hap
devecocli device app install /path/to/app.hap --replace --device Phone
devecocli device app uninstall --bundle com.example.app
devecocli device app list --format json
devecocli device app info com.example.app
devecocli device app foreground
devecocli device app start --bundle com.example.app --ability EntryAbility
devecocli device app stop --bundle com.example.app
devecocli device app cleardata --bundle com.example.app
devecocli device app clearcache --bundle com.example.app

device wake / device sleep / device status

控制设备屏幕唤醒、休眠及查询屏幕状态。

命令格式：

devecocli device wake [--device <name|serial>]
devecocli device sleep [--device <name|serial>]
devecocli device status [--device <name|serial>]

示例：

devecocli device wake --device Phone
devecocli device sleep --device Phone
devecocli device status --device Phone

device unlock

唤醒设备并上滑解锁。仅支持 phone 和 tablet，不支持 2in1 设备。

命令格式：

devecocli device unlock [--device <name|serial>]

示例：

devecocli device unlock --device Phone

device open-control-center / device open-notification-center

通过滑动手势打开控制中心或通知中心。仅支持 phone 和 tablet，不支持 2in1 设备。

命令格式：

devecocli device open-control-center [--device <name|serial>]
devecocli device open-notification-center [--device <name|serial>]

示例：

devecocli device open-control-center --device Phone
devecocli device open-notification-center --device Phone

device time / device timezone

获取或设置设备系统时间和时区。省略参数时为获取，提供参数时为设置。

命令格式：

devecocli device time [datetime] [--device <name|serial>]
devecocli device timezone [timezone] [--device <name|serial>]

参数：

示例：

devecocli device time
devecocli device time "2026-01-01 12:00:00"
devecocli device timezone
devecocli device timezone "Asia/Shanghai"

device screen

控制设备屏幕，包括尺寸查询、旋转控制和熄屏超时。

子命令：

命令格式：

devecocli device screen size [--format <default|json>] [--device <name|serial>]
devecocli device screen rotation [--device <name|serial>]
devecocli device screen rotate <0|90|180|270> [--device <name|serial>]
devecocli device screen rotation-lock <on|off> [--device <name|serial>]
devecocli device screen sleeptime <ms> [--device <name|serial>]

参数：

示例：

devecocli device screen size
devecocli device screen size --format json --device Phone
devecocli device screen rotation
devecocli device screen rotate 90
devecocli device screen rotation-lock on
devecocli device screen rotation-lock off
devecocli device screen sleeptime -1
devecocli device screen sleeptime 30000

device clipboard

读写或清空设备剪贴板。

命令格式：

devecocli device clipboard read [--device <name|serial>]
devecocli device clipboard write <text> [--device <name|serial>]
devecocli device clipboard clear [--device <name|serial>]

示例：

devecocli device clipboard read
devecocli device clipboard write "Hello World" --device Phone
devecocli device clipboard clear

device font

管理设备字体，包括查询、安装和卸载。

命令格式：

devecocli device font info <fontpath> [--device <name|serial>]
devecocli device font install <fontpath> [--device <name|serial>]
devecocli device font uninstall <name> [--device <name|serial>]

参数：

示例：

devecocli device font info /path/to/font.ttf
devecocli device font install /path/to/font.ttf --device Phone
devecocli device font uninstall "MyCustomFont"

device viewmode

获取或设置设备视图模式（深色/浅色）。省略参数时为获取，提供参数时为设置。

命令格式：

devecocli device viewmode [dark|light] [--device <name|serial>]

参数：

示例：

devecocli device viewmode
devecocli device viewmode dark --device Phone
devecocli device viewmode light

device location

模拟设备位置或关闭位置模拟，基于 testhelper（系统版本 7.0+）。支持经纬度模式和 GPX 文件模式（互斥）。

命令格式：

devecocli device location set --latitude <degrees> --longitude <degrees> [--altitude <m>] [--speed <m/s>] [--direction <degrees>] [--interval <s>] [--device <name|serial>]
devecocli device location set --gpx-file <path> [--interval <s>] [--device <name|serial>]
devecocli device location enable [--device <name|serial>]
devecocli device location disable [--device <name|serial>]

示例：

devecocli device location set --latitude 39.908 --longitude 116.40024
devecocli device location set --gpx-file ./route.gpx --interval 2
devecocli device location disable

说明：

• --latitude/--longitude 与 --gpx-file 互斥。--altitude/--speed/--direction 仅经纬度模式有效。
• --interval（1-3600 秒，默认 1）两种模式均支持，作为 testhelper 命令参数传递，不修改 GPX 文件内容。
• set 会自动启用位置模拟，无需单独 enable。
• GPX 文件支持标准 GPX 1.1 格式，详见 testhelper 官方文档。
• 只有 debug 签名的应用才能获取到模拟位置信息，开启模拟后非 debug 应用将获取位置失败。

device network-sim

基于 netcopilot（API 20+）模拟设备网络状况，用于弱网/断网/切换等测试场景。

命令格式：

devecocli device network-sim start --id <id> [--device <name|serial>]
devecocli device network-sim start --name <name> --up-bandwidth <bps> --down-bandwidth <bps> --up-latency <ms> --down-latency <ms> --up-drop <rate> --down-drop <rate> [--device <name|serial>]
devecocli device network-sim stop [--device <name|serial>]
devecocli device network-sim list [--device <name|serial>]
devecocli device network-sim status [--device <name|serial>]

示例：

devecocli device network-sim start --id 5
devecocli device network-sim start --name weak-net --up-bandwidth 100000 --down-bandwidth 500000 --up-latency 200 --down-latency 200 --up-drop 0.05 --down-drop 0.01
devecocli device network-sim stop
devecocli device network-sim list

说明：

• --id（预置场景 1-8）与 --name+自定义网络参数互斥。
• 预置场景 1-3 需同时连接 WLAN 和蜂窝网络；4-8 需 WLAN 或蜂窝网络之一。
• stop 停止模拟、删除自定义场景、自动关闭 netcopilot，无参数、幂等。

device playback

基于 ohos-avsession-manager（系统版本 6.1+）控制设备媒体播放中心。

命令格式：

devecocli device playback list [--device <name|serial>]
devecocli device playback play [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback pause [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback next [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback previous [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback forward [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback rewind [--id <id>] [--bundle <name>] [--device <name|serial>]
devecocli device playback seek --position <seconds> [--id <id>] [--bundle <name>] [--device <name|serial>]

示例：

devecocli device playback list
devecocli device playback play --bundle com.example.music
devecocli device playback seek --position 120 --bundle com.example.music

说明：

• 控制命令需要 --id 或 --bundle（至少提供一个）。--bundle 会自动解析会话 ID。
• forward/rewind 步长由应用决定，不支持设置时间。
• seek --position 跳转到指定位置（秒），非负数（支持整数和浮点数，如 0、120、1.5）。

ui screenshot

对真机或模拟器执行 UI 截图。

命令格式：

devecocli ui screenshot --device <name|serial> --display <displayId> --path <path>

参数：

示例：

mkdir -p screenshots
devecocli ui screenshot --device Phone --path ./screenshots
devecocli ui screenshot --device Phone --display 0 --path ./screenshots/phone.png

说明：

• ui screenshot 支持真机和模拟器。
• 仅有一个可用设备时可省略 --device，多个设备同时连接时必须指定。
• --path 可以使用相对于当前目录的路径。可以指定已存在的文件夹并自动生成 PNG 文件名，也可以指定完整的 PNG 文件路径；不会自动创建目录或覆盖已有文件。
• 截图能力统一通过 ui screenshot 提供，不放在模拟器场景操作命令中。
• 截图统一使用 hdc shell snapshot_display 和 hdc file recv 实现；设置 DEVECO_CLI_DEBUG=1 可查看实际执行命令。

ui screenrecord

录制真机屏幕并保存为 MP4。仅支持提供系统录屏服务和 mediatool 的真机，不支持模拟器。

命令格式：

devecocli ui screenrecord [start] --device <name|serial> --path <dir|file.mp4>
devecocli ui screenrecord stop --device <name|serial> [--force]
devecocli ui screenrecord status --device <name|serial> [--format table|json]

参数：

示例：

mkdir -p recordings
# 直接录制，按 Ctrl+C 停止并保存
devecocli ui screenrecord --device Phone --path ./recordings/demo.mp4

# 分步控制
devecocli ui screenrecord start --device Phone --path ./recordings
devecocli ui screenrecord status --device Phone --format json
devecocli ui screenrecord stop --device Phone

说明：

• 不带子命令时进入交互录制；start 确认启动后立即返回，之后用 stop 停止并保存到启动时指定的位置。
• --path 支持相对路径；输入目录则自动生成文件名，不创建目录、不覆盖已有文件。录制期间目标被占用时，使用带 -recovered 后缀的文件名。
• status 返回 recording（本 CLI 录屏）、busy（非本 CLI 登记的录屏）或 idle（未录屏）；查询不会改变设备状态。
• 设备端已停止或视频保存失败时，可重试 stop 取回；再次启动会删除中断会话登记，不取回旧视频，原件保留在设备图库。跨终端操作需使用同一个 DEVECO_CLI_DATA_DIR。
• 设备图库保留视频原件。进程被强制结束且登记尚未完成时，需检查设备状态和图库。

ui click

点击指定坐标、节点 ID 或 Selector 定位的元素中心位置。

命令格式：

devecocli ui click [x] [y] --device <name|serial> --id <id> --selector <expr> --window <windowId>

参数：

示例：

devecocli ui click 100 200
devecocli ui click 100 200 --device Phone
devecocli ui click --id submit_button
devecocli ui click --id submit_button --window main_window
devecocli ui click --selector "text=登录,type=Button"
devecocli ui click --selector "xpath=//Button[@key='login_btn']"

ui doubleclick

双击指定坐标、节点 ID 或 Selector 定位的元素中心位置。

命令格式：

devecocli ui doubleclick [x] [y] --device <name|serial> --id <id> --selector <expr> --window <windowId>

参数：

示例：

devecocli ui doubleclick 100 200
devecocli ui doubleclick 100 200 --device Phone
devecocli ui doubleclick --id photo_thumb
devecocli ui doubleclick --id photo_thumb --window main_window
devecocli ui doubleclick --selector "key=photo_item"

ui longclick

长按指定坐标或节点 ID 的中心位置。

命令格式：

devecocli ui longclick [x] [y] --device <name|serial> --id <id> --selector <expr> --duration <ms> --window <windowId>

参数：

示例：

devecocli ui longclick 100 200
devecocli ui longclick 100 200 --device Phone
devecocli ui longclick 100 200 --duration 3000
devecocli ui longclick --id menu_item
devecocli ui longclick --id menu_item --window main_window
devecocli ui longclick --selector "id=btn_longclick" --duration 1500

ui swipe

自定义滑动，支持坐标模式和元素模式（通过 --start/--end Selector 定位起终点）。

命令格式：

# 坐标模式
devecocli ui swipe <x1> <y1> <x2> <y2> --device <name|serial> --speed <n>

# 元素模式
devecocli ui swipe --start <expr> --end <expr> --device <name|serial> --speed <n> --window <windowId>

参数：

示例：

# 坐标模式
devecocli ui swipe 100 500 100 200
devecocli ui swipe 100 500 100 200 --device Phone
devecocli ui swipe 100 500 100 200 --speed 1000

# 元素模式
devecocli ui swipe --start "key=header_text" --end "key=footer_button"
devecocli ui swipe --start "text=顶部" --end "text=底部" --speed 500

ui fling

快速滑动（Fling）。

命令格式：

devecocli ui fling <x1> <y1> <x2> <y2> --device <name|serial> --speed <n>

参数：

示例：

devecocli ui fling 100 800 100 200
devecocli ui fling 100 800 100 200 --device Phone
devecocli ui fling 100 800 100 200 --speed 3000

ui drag

拖拽操作，支持坐标模式和元素模式（通过 --start/--end Selector 定位起终点）。

命令格式：

# 坐标模式
devecocli ui drag <x1> <y1> <x2> <y2> --device <name|serial> --speed <n>

# 元素模式
devecocli ui drag --start <expr> --end <expr> --device <name|serial> --speed <n> --window <windowId>

参数：

示例：

# 坐标模式
devecocli ui drag 100 500 100 200
devecocli ui drag 100 500 100 200 --device Phone
devecocli ui drag 100 500 100 200 --speed 1500

# 元素模式
devecocli ui drag --start "key=item_1" --end "key=drop_zone"
devecocli ui drag --start "text=卡片" --end "text=回收站" --speed 800

ui dircfling

向指定方向快速滑动。

命令格式：

devecocli ui dircfling <direction> --device <name|serial>

参数：

示例：

devecocli ui dircfling up
devecocli ui dircfling down --device Phone
devecocli ui dircfling left
devecocli ui dircfling right

与 ui swipe 的区别：

• ui swipe 需要指定精确的起点和终点坐标，支持自定义速度，适用于特定区域滑动。
• ui dircfling 仅需指定方向，使用系统默认速度，适用于页面滚动或列表快速滑动。

ui text

输入文本到当前焦点、指定坐标或指定节点位置。

命令格式：

devecocli ui text <text> [x] [y] --device <name|serial> --id <id> --selector <expr> --window <windowId>

参数：

示例：

devecocli ui text "Hello World"
devecocli ui text "Hello World" --device Phone
devecocli ui text "Hello World" 100 200
devecocli ui text "Hello World" --id search_box
devecocli ui text "Hello World" --id search_box --window main_window
devecocli ui text "hello" --selector "key=search_box"

ui cleartext

清空文本内容（通过 Ctrl+A + Del），可选先点击目标元素再清空。

命令格式：

devecocli ui cleartext --device <name|serial> --selector <expr> --window <windowId>

参数：

示例：

devecocli ui cleartext
devecocli ui cleartext --device Phone
devecocli ui cleartext --selector "id=search_box"

ui scrolltostart

将可滚动容器滚动到起始位置（顶部）。

命令格式：

devecocli ui scrolltostart --device <name|serial> --selector <expr> --speed <n> --timeout <ms>

参数：

示例：

devecocli ui scrolltostart
devecocli ui scrolltostart --selector "id=scroll_list" --device Phone
devecocli ui scrolltostart --selector "id=scroll_list" --speed 2000

ui scrolltoend

将可滚动容器滚动到结束位置（底部）。

命令格式：

devecocli ui scrolltoend --device <name|serial> --selector <expr> --speed <n> --timeout <ms>

参数：

示例：

devecocli ui scrolltoend
devecocli ui scrolltoend --selector "id=scroll_list" --device Phone

ui scrollsearch

在可滚动容器内滚动并查找目标元素。

命令格式：

devecocli ui scrollsearch <selector> --device <name|serial> --scroll-selector <expr> --vertical <true|false> --offset <n> --timeout <ms>

参数：

示例：

devecocli ui scrollsearch "id=target_item"
devecocli ui scrollsearch "id=target_item" --scroll-selector "id=scroll_list" --device Phone
devecocli ui scrollsearch "id=swiper_page_3" --scroll-selector "id=swiper" --vertical false

ui pinch

在指定坐标、元素或屏幕中心执行捏合（缩放）手势。

命令格式：

devecocli ui pinch <scale> [x] [y] --device <name|serial> --selector <expr> --area-radius <n> --speed <n> --window <windowId>

参数：

示例：

devecocli ui pinch 2.0
devecocli ui pinch 2.0 500 500 --device Phone
devecocli ui pinch 0.5 --selector "id=gesture_area_pinch"
devecocli ui pinch 2.0 --selector "id=gesture_area_pinch" --area-radius 300
devecocli ui pinch 2.0 500 500 --speed 1200

ui rotate

在指定坐标、元素或屏幕中心执行双指旋转手势。

命令格式：

devecocli ui rotate <angle> [x] [y] --device <name|serial> --direction <cw|ccw> --selector <expr> --radius <n> --speed <n> --window <windowId>

参数：

示例：

devecocli ui rotate 90
devecocli ui rotate 90 --direction ccw --device Phone
devecocli ui rotate 180 500 500
devecocli ui rotate 90 --selector "id=gesture_area_rotate"
devecocli ui rotate 90 --selector "id=gesture_area_rotate" --radius 200 --speed 1000

ui press_key

按压硬件/系统按键，最多支持 3 个按键组合（组合键）。

命令格式：

devecocli ui press_key <key1> [key2] [key3] --device <name|serial>

参数：

按键名称（不区分大小写）：back、enter、escape、tab、ctrl_left、shift_left 等；也可直接传数字 keycode（如 2048）。

示例：

devecocli ui press_key back
devecocli ui press_key enter --device Phone
devecocli ui press_key ctrl_left c
devecocli ui press_key ctrl_left shift_left escape
devecocli ui press_key 2048

ui find

通过 Selector DSL、XPath 或 base64 编码查找 UI 控件。在 --timeout 时间内每 300ms 轮询控件树，直至匹配成功或超时。

命令格式：

devecocli ui find [selector] --device <name|serial> --window <windowId> --all --timeout <ms> --format <default|json>

参数：

Selector DSL 语法：

key op value 子句，支持 , 分隔多条件 AND、[n] 索引。操作符：=（精确）、*=（包含）、^=（前缀）、$=（后缀）、/=（正则）。支持 xpath= 前缀（XPath 1.0 表达式）和 base64= 前缀（base64 编码 selector）。同一属性不可重复指定（desc 与 description 视为同一属性），重复会报错。

示例：

devecocli ui find "text=登录"
devecocli ui find "type=Button" --all --format json
devecocli ui find "id=login_btn" --device Phone
devecocli ui find "xpath=//Button[@text='登录']"
devecocli ui find "base64=dHlwZT1UZXh0"  # base64 解码后为 type=Text
devecocli ui find "text=不存在的文本" --timeout 1000  # 超时后报错退出

ui wait

等待元素出现、消失，或纯等待（sleep）。无 selector 时为纯等待，有 selector 时轮询控件树直至元素出现（默认）或消失（--disappear）。

命令格式：

# 纯等待（sleep）
devecocli ui wait [timeoutMs] --device <name|serial>

# 等待元素出现/消失
devecocli ui wait <selector> [timeoutMs] [--disappear] --device <name|serial> --window <windowId>

参数：

示例：

# 等待元素出现
devecocli ui wait "text=登录" 10000
devecocli ui wait "text=照片" 10000 --device Phone

# 等待元素消失
devecocli ui wait "text=加载中" 5000 --disappear

# 纯等待（sleep）
devecocli ui wait 2000

ui layout

导出设备屏幕上的 UI 节点树，输出每个节点的类型、节点 ID、坐标边界 [left,top,right,bottom]、文本及可交互标志（clickable / longClickable / scrollable / checkable）。

设备要求：需设备 API 20 及以上。

命令格式：

devecocli ui layout --device <name|serial> --id <id> --window <windowId> --all-windows --depth <n> --format <fmt> --mode <full|simplified>

参数：

示例：

devecocli ui layout
devecocli ui layout --device Phone
devecocli ui layout --device Phone --format json
devecocli ui layout --mode full --depth 2
devecocli ui layout --id submit_button
devecocli ui layout --window 15 --format json

说明：

• --mode simplified（默认）会折叠无 id、无 text、无任何可交互标志的包装节点，使输出聚焦于有意义的可操作节点；根节点始终保留。--depth 在折叠后截断。
• --id 用于按节点 ID 查询，返回所有匹配节点（children 置空），常配合 ui click --id / ui text --id 定位坐标。
• 节点 bounds 为 [left, top, right, bottom]，ui click --id 等交互命令据此取中心坐标点击。
• --window 的窗口 ID 可通过 devecocli ui window list 获取。

ui window list

查看设备上的窗口列表，输出窗口 ID、名称、PID、所属屏幕 ID 及是否聚焦。为 ui layout --window、ui click --window 等命令提供窗口 ID。

命令格式：

devecocli ui window list --device <name|serial> --format <fmt> --all

参数：

示例：

devecocli ui window list
devecocli ui window list --device Phone
devecocli ui window list --format json
devecocli ui window list --all

说明：

• 聚焦窗口在 default 格式下高亮显示。
• 缺省时仅列出应用窗口；加 --all 可查看系统窗口，用于排查多窗口场景。

run

构建应用后，将应用安装到真机设备或模拟器上，并启动执行

命令格式：

devecocli run --module <m1> [m2...] --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build --apply <fileName> --hotreload [action] --hotreload-apply <fileName> [--debug-line]

参数：