dsh-deveco-cli

<div align="center"> <h1>DevEco CLI</h1> <p>一个面向 HarmonyOS 应用开发的统一命令行入口。</p> <p> <a href="https://www.npmjs.com/package/@ah-plugins/dsh-deveco-cli"><img src="https://img.shields.io/npm/v/@ah-plugins/dsh-deveco-cli.svg" alt="NPM Version" /></a> <a href="https://www.npmjs.com/package/@ah-plugins/dsh-deveco-cli"><img src="https://img.shields.io/npm/dm/@ah-plugins/dsh-deveco-cli.svg" alt="NPM Downloads" /></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-green.svg" alt="Node.js" /></a> <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue.svg" alt="Platform" /> <a href="https://developer.huawei.com/consumer/cn/download/"><img src="https://img.shields.io/badge/DevEco%20Studio-%3E%3D6.0.0-orange.svg" alt="DevEco Studio" /></a> <img src="https://img.shields.io/badge/Command%20Line%20Tools-%3E%3D26.0.0-orange.svg" alt="Command Line Tools" /> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a> </p> </div>

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

> 关于数据采集与隐私（遥测打点内容、存储加密、上报及关闭方式），请参阅 [PRIVACY.md](./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 @ah-plugins/dsh-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 harmonyos-guides/application-models/arkts-page-start-overview

更多命令和参数可通过 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

AI Agent 集成

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

DeepSeek Harness 插件

DevEco CLI 同时发布为 dsh bundle。安装后，DeepSeek Harness 会注册 deveco_cli 工具，供 Agent 以结构化参数调用 devecocli：

dsh plugin add @ah-plugins/dsh-deveco-cli
dsh web

工具参数为 command、args 和可选 cwd。args 是 argv 数组，不是 shell 字符串：

{
  "command": "docs",
  "args": ["search", "List", "--format", "json"],
  "cwd": "/path/to/HarmonyOSProject"
}

该插件复用当前包内的 dist/cli.js，因此发布前需要执行 npm run build。

常用命令

命令集

help

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

命令格式：

devecocli help

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

HarmonyOS application development command line tool

Options:
  -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
  create [options]       Scaffold a new HarmonyOS application project
  init [options]         Install the deveco-cli skill 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

init

将deveco-cli Skill 或者 MCP 服务配置到智能体中

命令格式：

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

参数：

示例：

# 配置Skill
devecocli init -f   # 安装或更新deveco-cli 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

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 开发指南/应用框架/UI_Design_Kit_UI设计套件/沉浸光感/ui-design-hds-component-material

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> 

参数：

示例：

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

auth login

登录华为开发者账号，打开浏览器完成授权。

命令格式：

devecocli auth login

说明：

• 海外账户暂不支持

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>

参数：

示例：

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 <name>命令后，产物为 .app
• 执行devecocli build --product <name> --modules <m1>命令后，产物为 .hap / .hsp / .har

build clean

清理 HarmonyOS 项目的构建产物

命令格式：

devecocli build clean

check compat

基于 DevEco Studio 自带的 apkanalyzer-apiscan 插件，扫描源代码在两个 SDK 版本之间的 API 变更情况。

子命令：

命令格式：

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]

参数：

| 参数名 | 说明 | | ---------------------------- | --------------------------------------------------------------------- | | [path] | 可选，待检查的文件或目录；默认使用 build-profile.json5 所在的项目根目录，否则使用当前目录 | | --config-path <path> | Code Linter 配置文件路径，仅支持 .json 或 .json5；默认使用待检查项目根目录下的 code-linter.json5，显式指定时必须与待检查路径属于同一项目 | | --fix | 自动修复可修复的问题 | | --incremental | 仅检查 Git 未提交文件 | | --product <name> | build-profile.json5 中定义的 product，默认为 default | | --format <default\|json> | 完整报告格式；default 输出 Markdown，json 输出 JSON；要求 DevEco Studio ≥ 6.1.0 | | --output-path <path> | 完整报告文件或目录,目录形式会自动生成带时间戳的报告文件；要求 DevEco Studio ≥ 6.1.0 | | --limit <number> | 未指定 --output-path 时，限制终端显示的问题数量 |

emulator 版本要求： DevEco Studio ≥ 6.1.0

emulator list

查看模拟器实例

命令格式：

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

参数：

示例：

devecocli emulator list
devecocli emulator list --format json

emulator start

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

命令格式：

devecocli emulator start [names...]

参数：

示例：

devecocli emulator start Phone
devecocli emulator start Phone1 Phone2

说明：

• 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 geolocation --target Phone --longitude 116.400244
devecocli emulator scene outdoorRunning --target Phone
devecocli emulator sensor --target Phone --heartrate 80

说明：

• --target 支持模拟器名称或 127.0.0.1:<port> 序列号。
• battery --level 会自动查询模拟器当前充电状态：充电时取值范围为整数 [0, 100]，未充电时为 [1, 100]。
• battery --status 取值为 charging 或 discharging。
• geolocation 支持 --longitude、--latitude、--altitude、--direction。
• scene 取值为 outdoorRunning、outdoorCycling、drivingNavigation。
• sensor 支持 --light-intensity、--humidity、--temperature、--steps、--heartrate。
• fold <state> 会根据目标模拟器的设备类型校验状态，设备与参数必须匹配：

…