@deveco-test/deveco-cli-hmos
v0.1.0
Published
HarmonyOS application development command line tool
Readme
DevEco CLI 将 DevEco Studio 工具链统一封装为一个 CLI,内置 ohpm、hvigor、hdc、hilog,同时集成 HarmonyOS 技能安装、项目脚手架、本地 HarmonyOS 文档检索和 MCP 服务。
快速开始
前置要求
- 操作系统为
HarmonyOS - 安装 Command Line Tool 工具
- 配置环境变量:
export COMMAND_LINE_TOOL_PATH=path/to/deveco_tools export PATH=$PATH:path/to/deveco_tools/node/bin
安装
npm install -g @deveco-test/hmos-deveco-cli安装后可以通过以下命令更新到最新版本:
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 查看。
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如果 Agent 不在 --agent 参数取值范围内,可使用 --path 参数进行添加,参考如下命令:
devecocli init --path .\work\ARKTS\NewData进入 Agent 后可以直接描述任务,例如:
Build this project in release mode and run it on my deviceTail the last error logs from this appCheck for syntax errors in src/main/ets/pages/Index.ets
常用命令
| 命令 | 用途 |
| ------------------------- | ----------------------------------------- |
| devecocli create | 创建新的 HarmonyOS 项目 |
| devecocli build | 构建项目并产出 .hap / .hsp / .har / .app |
| devecocli check lint | 检查代码规范并输出实践建议与报告 |
| devecocli run | 安装并运行应用 |
| devecocli device list | 查看当前连接设备 |
| devecocli log | 查看 hilog 或崩溃日志 |
| devecocli docs search | 搜索本地 HarmonyOS 文档 |
| devecocli init | 安装内置技能或配置 MCP |
| devecocli skills | 管理 HarmonyOS 技能市场中的技能 |
| devecocli signature generate | 自动生成调试签名材料并配置到项目 |
命令集
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
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 commandinit
将deveco-cli Skill 或者 MCP 服务配置到智能体中
命令格式:
devecocli init --agent <agents> --project <path> --path <path> --skill --mcp --force参数:
| 参数名 | 说明 |
| ----------- | ----------------------------------------------------------------------------------------- |
| --agent | 可选,智能体名称,多个智能体名称以英文逗号分隔。缺省时配置到所有已检测到的智能体中 |
| --project | 可选,指定工程路径,将deveco-cli Skill 或 MCP 服务安装到该工程项目中 |
| --path | 可选,指定 deveco-cli Skill 的配置路径。不可与 --project 、--agent 、 --mcp 同时使用 |
| --skill | 可选,安装 deveco-cli Skill。不可与 --mcp 同时使用。--mcp 与 --skill 都缺省时,执行 --skill |
| --mcp | 可选,配置 MCP 服务,与 --project 一起使用表示配置工程级 MCP 服务,独立使用表示配置用户级 MCP 服务。不可与 --skill 同时使用 |
| -f, --force | 可选,当目标位置已存在 deveco-cli Skill 或 MCP 服务时,覆盖重装 |
示例:
# 配置Skill
devecocli init -f # 安装或更新deveco-cli Skill
devecocli init --skill
devecocli init --agent agentname # agentname需替换为实际的智能体名称
devecocli init --path /path/to/project -f
# 配置MCP
devecocli init --mcp
devecocli init --mcp --agent agentname # agentname需替换为实际的智能体名称
devecocli init --mcp --project /path/to/project -fdocs search
将关键词搜索版本说明、指南、API参考、最佳实践、FAQ 、变更预告等中的内容
命令格式:
devecocli docs search <keywords...> --catalog <name> --format <fmt> --limit <n>参数:
| 参数名 | 说明 |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| keywords... | 必选,搜索关键词,多个关键词用空格隔开 |
| --catalog | 可选,文档类别,取值包含harmonyos-releases(版本说明)、 harmonyos-guides(指南)、harmonyos-references(API参考)、best-practices(最佳实践)、harmonyos-faqs(FAQ)、harmonyos-roadmap(变更预告)、all(所有分类,默认) |
| --format | 可选,控制输出格式,取值包括 default 、json ,默认为default ,输出结果包括文档ID、标题、文档的概括内容 |
| --limit | 可选,设置搜索结果返回条数,默认为20 |
示例:
devecocli docs search 沉浸光感
devecocli docs search '@State' '@Prop' --catalog best-practices --limit 10
devecocli docs search Row Column --format jsondocs read
按文档ID查询文档的完整内容
命令格式:
devecocli docs read <documentId> 参数:
| 参数名 | 说明 | | ---------- | ------- | | documentId | 必选,文档ID |
示例:
devecocli docs read 开发指南/应用框架/UI_Design_Kit_UI设计套件/沉浸光感/ui-design-hds-component-materialdocs catalog
查询文档分类和分类名称
命令格式:
devecocli docs catalog --format <fmt> 参数:
| 参数名 | 说明 |
| -------- | ----------------------------------------- |
| --format | 可选,输出格式,default 或 json ,默认为 default |
示例:
devecocli docs catalog
devecocli docs catalog --format jsoncreate
创建 HarmonyOS 应用工程,仅支持创建工程模板中的 Empty Ability 模板
命令格式:
devecocli create --app-name <name> --project-path <path> --bundle-name <bundle> --api-level <level> 参数:
| 参数名 | 说明 |
| -------------- | ----------------------------------------------------------------- |
| --app-name | 必选,应用名称 |
| --project-path | 可选,工程路径,默认为:./<appname> |
| --bundle-name | 可选,包名,默认为:com.example.<appname> ,appname 自动转为小写 |
| --api-level | 可选,API级别,最小值为17,最大值从安装的 Deveco Studio 的 HarmonyOS SDK 中自动获取 |
示例:
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 MyAppauth login
登录华为开发者账号,打开浏览器完成授权。
命令格式:
devecocli auth login说明:
- 海外账户暂不支持
auth logout
登出并清除本地存储的凭据
命令格式:
devecocli auth logoutauth status
显示当前登录的用户
命令格式:
devecocli auth statusauth team list
列出当前用户已加入的团队
命令格式:
devecocli auth team list示例:
devecocli auth team listbuild
编译并打包 HarmonyOS 工程或工程中的模块
命令格式:
devecocli build --product <product> --modules <modules> --build-mode <mode>参数:
| 参数名 | 说明 |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| --product | 可选,产品的名称,默认为 default |
| --modules | 可选,模块的名称。如需指定模块的 target 信息,使用 module@target 形式。当工程中只有一个模块时,可缺省;当工程中存在多个模块,且仅存在一个 entry 类型的模块时,可缺省 |
| --build-mode | 可选,构建模式,默认为 debug |
示例:
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 cleancheck 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 |
| --output-path <path> | 完整报告文件或目录;目录形式会自动生成带时间戳的报告文件 |
| --limit <number> | 未指定 --output-path 时,限制终端显示的问题数量 |
device list
查询所有已连接的设备
命令格式:
devecocli device listdevice view
查询已连接的设备的详细信息,包括设备序列号、设备名称、设备类型、 OS 版本等
命令格式:
devecocli device view --target <serialOrName>参数:
| 参数名 | 说明 | | ----------- | ------------------------------------- | | -t,--target | 可选,目标设备名称或序列号。多设备缺省时,会列出所有已连接设备序列号和名称 |
示例:
devecocli device view
devecocli device view --target 127.0.0.1:5555
devecocli device view -t "My Device Name"run
构建应用后,将应用安装到设备上,并启动执行
命令格式:
devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build --apply <txtFile>参数:
| 参数名 | 说明 |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| --module | 可选,模块名称。如需指定模块的 target 信息,使用 module@target 形式。当工程中只有一个可运行模块( entry / feature / shared )时,可缺省 |
| --device | 设备名称或设备序列号,单设备时可选,多设备时必选 |
| --product | 可选,产品的名称,默认为 default |
| --build-mode | 可选,构建模式名称,默认为 debug |
| --ability | 可选,待启动的 Ability ,默认:模块 module.json5 中的mainElement |
| --uninstall | 可选,安装前先卸载已有应用 |
| --skip-build | 可选,跳过构建操作,直接安装应用 。**说明:**使用该参数时,需确保对应模块已有构建产物 |
| --apply <fileName> | 可选,快速增量部署:仅重编改动文件 → signed hqf → bm quickfix -a -f -o 安装 → 重启,比全量 run 快。<fileName> 是工程 .hvigor/ 目录下的纯文件名(调用方把清单写到此目录,文件名做安全校验防穿越);内容为本轮改动的源文件路径清单(每行一个相对工程根路径;#/空行忽略;.ets/.ts/.cpp/资源文件;changeFileList 增量累积,只需列本轮改的,历史文件自动保留)。模块从清单路径自动识别(无需 --module)。前提:先 devecocli run 全量构建部署一次(生成 buildConfig.json 缓存);没生效排查:检查 <module>/build/config/buildConfig.json 有无内容(空/无 = 没跑过 devecocli run);失败兜底:直接 devecocli run |
示例:
devecocli run
devecocli run --module entry --device 127.0.0.1:5555
devecocli run --module library@phone --device 127.0.0.1:5555
devecocli run --product oversea --module entry --ability EntryAbility
devecocli run --build-mode release
devecocli run --uninstall
devecocli run --apply changes.txtlog
查看hilog普通日志或崩溃日志
命令格式:
devecocli log --device <device> --crash --level <level> --bundle-name <bundle-name> --keyword <keyword> --tail <num> --from <start> --to <end> --follow参数:
| 参数名 | 说明 |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| --device | 设备名称或设备序列号,单设备时可选,多设备时必选 |
| --crash | 可选,查看崩溃日志 |
| --level | 可选,日志级别,取值包括D( Debug )、I( Info )、W( Warn )、E( Error )、F( Fatal ) |
| --bundle-name | 可选,根据包名查看日志 |
| --keyword | 可选,根据关键词查看日志,关键词区分大小写 |
| --tail | 可选,显示最新的N行日志,取值为正整数 |
| --from | 可选,起始时间,单位为m和s,m和s为小写,默认为s,start的取值需要大于等于end |
| --to | 可选,结束时间,单位为m和s,m和s为小写,默认为s 。不可与--follow同时使用。说明: 如当前时间为05:00,start设置为30s,end设置为10s,则起始时间为04:30,结束时间为04:50 |
| --follow | 可选,实时输出日志。不可与--to同时使用 |
示例:
devecocli log --level E
devecocli log --crash --bundle-name com.example.app
devecocli log --device 127.0.0.1:5555 --level W --keyword Init
devecocli log --tail 100 --from 5m --to 2m
devecocli log --follow --bundle-name com.example.appskills list
查询可用的 Skill
命令格式:
devecocli skills list --long参数:
| 参数名 | 说明 |
| --------- | ----------------------------------------------- |
| -l,--long | 可选,Skill 详情,包括描述和已安装的智能体列表。缺省时,仅显示 Skill 名称 |
示例:
devecocli skills list
devecocli skills list --long
devecocli skills list -lskills find
按关键词搜索 Skill
命令格式:
devecocli skills find <keyword>参数:
| 参数名 | 说明 | | ------- | -------- | | keyword | 必选,搜索关键词 |
示例:
devecocli skills find devecoskills add
将 Skill 添加到智能体中
命令格式:
devecocli skills add --all --agent <agents> --skill <skill-name> --project <path> --path <path> --force参数:
| 参数名 | 说明 |
| ---------- | --------------------------------------------------------- |
| --all | 可选,添加所有可用的 Skill ,与 --skill 二选一 |
| --agent | 可选,智能体名称,多个智能体时以英文逗号分隔。缺省时,添加到已检测到的智能体中 |
| --skill | 可选,待添加的 Skill 名称,与 --all 二选一 |
| --project | 可选,指定项目路径,将 Skill 添加到该工程项目中 |
| --path | 可选,指定路径,将 Skill 添加到该路径,不可与 --project 或 --agent 同时使用 |
| -f,--force | 可选,当目标位置已有同名 Skill 时,覆盖重添加 |
示例:
devecocli skills add --all
devecocli skills add --skill skillname --agent agentname --force # skillname需替换成实际的Skill名称
devecocli skills add --skill skillname --project ./my-app # skillname需替换成实际的Skill名称skills remove
从智能体中删除已添加的 Skill
命令格式:
devecocli skills remove --skill <skill-name> --agent <agents> --project <path> --path <path>参数:
| 参数名 | 说明 |
| --------- | -------------------------------------------------------- |
| --skill | 必选,待删除的 Skill 名称 |
| --agent | 可选,智能体名称,多个智能体时以英文逗号分隔。缺省时,删除到已检测到的智能体中的 Skill |
| --project | 可选,指定项目路径,删除该项目中的 Skill |
| --path | 可选,指定路径,删除该项目中的 Skill,不可与 --project 或 --agent 同时使用 |
示例:
devecocli skills remove --skill skillname # skillname需替换成实际的Skill名称
devecocli skills remove --skill skillname --agent agentname # skillname需替换成实际的Skill名称serve mcp
启动本地 MCP 服务。智能体配置 MCP 服务后,可通过 MCP 协议调用下方列出的代码分析与语言特性工具。不同智能体平台配置 MCP 服务的界面不一样,一个智能体平台的配置示例如下。
推荐通过 devecocli init --mcp 自动配置
{
"mcp": {
"deveco-mcp": {
"type": "local",
"command": [
"devecocli",
"serve",
"mcp"
],
"environment":{
"PROJECT_PATH": "/path/to/project", // 工程路径
"NODE_MAX_OLD_SPACE_SIZE": "8192", // 可选,设置内部node进程最大的老生代内存大小,默认为8192
},
"enbale": true
}
}
}MCP 工具
deveco-mcp 服务遵循 MCP 规范,通过 tools/list 暴露工具、由模型经 tools/call 调用。每个工具由名称、描述和 JSON Schema 入参定义;返回值为 content 文本数组,isError: true 表示执行错误。
工具总览:
| 工具名 | 用途 | 支持语言 |
| --- | --- | --- |
| check | 静态语法分析,返回结构化诊断信息 | ArkTS、C/C++ |
| hover | 获取指定位置的悬浮信息(类型、文档) | ArkTS、C/C++ |
| definition | 查找符号定义位置 | ArkTS、C/C++ |
| declaration | 查找符号声明位置(ArkTS 中可能与定义不同) | ArkTS、C/C++ |
| references | 查找符号在全工程中的所有引用 | ArkTS、C/C++ |
| implementation | 查找符号的实现(如接口实现) | ArkTS、C/C++ |
| workspaceSymbol | 按名称在全工程搜索符号 | ArkTS、C/C++ |
| documentSymbol | 获取单文件的符号树(函数、类、变量及范围) | ArkTS、C/C++ |
| callHierarchy | 查询函数调用关系(incoming=调用方,outgoing=被调用方) | ArkTS 双向、C/C++ 仅 incoming |
| restart | 原地重启(重置状态 + 重新 sync/init),不杀进程、客户端不断开;ERROR 态可用 | ArkTS、C/C++(可按 target 单选) |
可用性说明:
check与restart始终注册;其余 7 个语言特性工具仅在 DevEco Studio 附带标准 LSP 服务入口(standardIndex/index.js)时注册,老版本将不暴露这些工具。- 所有语言特性工具需项目进入
READY状态(ohpm install+hvigor sync+ LSP 初始化完成)后才可用;未就绪时返回please retry in N seconds,模型可稍后重试。restart例外:它正是用于把 server 从ERROR态拉回,调用后返回"约 10 秒后重试",后台异步重置并重新 sync/init。 - C/C++ 工具需要工程包含 C++ 模块;无 C++ 代码时返回
No C++ code。 - 支持的文件扩展名:ArkTS 为
.ets;C/C++ 为.c.cc.cpp.cxx.c++.h.hh.hpp.hxx.h++.ipp.ixx.inl.inc.tpp。 - 不属于当前工程的路径会被拒绝。
入参定义:
check
对传入的源文件进行静态语法分析并返回诊断信息,支持 ArkTS 与 C/C++ 在同一次调用中混合传入。
| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| files | string[] | 是 | 待检查的源文件路径列表,相对工程根目录,至少 1 个 |
hover / definition / declaration / references / implementation
位置类语言特性,共享同一入参结构。返回该位置符号的类型/文档信息、定义/声明位置、引用列表或实现列表。
| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| file | string | 是 | 源文件路径,相对工程根目录,支持 .ets 与 C/C++ 扩展名 |
| line | number | 是 | 行号,0-based |
| character | number | 是 | 列号(字符偏移),0-based |
workspaceSymbol
按名称在全工程搜索符号,无需打开具体文件。
| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| query | string | 是 | 符号名称或片段,非空 |
documentSymbol
获取单个文件的符号树,适合文件概览、结构化拆解和大文件切片。
| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| file | string | 是 | 源文件路径,相对工程根目录,支持 .ets 与 C/C++ 扩展名 |
callHierarchy
查询某位置函数的调用关系。
| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| file | string | 是 | 源文件路径,相对工程根目录,支持 .ets 与 C/C++ 扩展名 |
| line | number | 是 | 行号,0-based |
| character | number | 是 | 列号(字符偏移),0-based |
| direction | enum | 是 | incoming=谁调用了该函数;outgoing=该函数调用了谁。ArkTS 支持双向,C/C++(clangd)仅 incoming |
restart
原地重启 MCP server:重置双侧状态并重新 sync/init(ohpm install + hvigor sync + compileNative + LSP 握手),不杀进程、客户端连接保持。用于 sync/init 失败导致 server 停在 ERROR 态时(免去退出并重开 agent)。fire-and-forget:立即返回"约 10 秒后重试",重置在后台异步进行。注意:restart 仅在修复根因后用于恢复,不能修复错误的工程配置。若重启后再次失败,说明是持久性配置问题(oh-package.json5/build-profile.json5 无效、ohpm install 或 hvigor sync 失败、SDK 版本不符等),不要循环调用 restart,应请用户排查并修复工程后再重试。
| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| target | enum | 否 | 重启哪一侧:arkts(ArkTS ace-server)、cpp(C++ clangd)、all(双侧,默认)。省略等同 all |
serve lsp
启动本地 LSP 语言服务。智能体配置 LSP 服务后,可通过 LSP 协议获取代码补全、跳转定义、悬浮提示、引用查找、诊断等语言特性。当前支持 ArkTS和 clangd。
{
"lsp": {
"ArkTS": {
"command": [
"devecocli",
"serve",
"lsp",
"--arkts"
],
"extensions": [
".ets"
]
},
"clangd": {
"command": [
"devecocli",
"serve",
"lsp",
"--cpp"
],
"extensions": [
".c",
".cpp",
".cc",
".cxx",
".h",
".hpp",
".hxx",
".hh"
]
}
}
}参数:
| 参数名 | 说明 |
| --- | --- |
| --arkts | 与 --cpp 二选一,启动 ArkTS 语言服务(ace-server) |
| --cpp | 与 --arkts 二选一,启动 C/C++ 语言服务(clangd) |
| --project-path <path> | 可选,工程根路径,默认为当前工作目录 |
| --auto-detect | 可选,当前目录向下查找工程根(检查当前目录自身及其子目录,最多 3 层子目录);适用于 --arkts 和 --cpp;指定了 --project-path 则忽略 |
signature generate
自动生成调试签名材料(包括p12密钥库、csr证书请求文件、p7b配置文件、cer证书文件),并将签名配置写入项目的 build-profile.json5 中。
命令格式:
devecocli signature generate --product <product> --team-id <team-id> --force --help参数:
| 参数名 | 说明 |
|-----------------------|-----------------------------------------|
| --product <product> | 可选,指定product生成签名,默认为 default |
| --team-id <team-id> | 可选,指定生效的team-id,默认使用自身作为团队信息 |
| --force | 可选,强制覆盖已存在的证书文件 |
| --help,--h | 可选,查看帮助信息 |
示例:
# 自动生成签名并写入工程配置
devecocli signature generate
# 指定product
devecocli signature generate --product default
# 指定team-id
devecocli signature generate --team-id 1222
# 强制覆盖已存在的证书文件
devecocli signature generate --force
# 查询帮助信息
devecocli signature generate --help常见问题
如何本地推包运行
当没有真机设备连接时,可以通过无线调试实现自连,在本地推包运行应用:
步骤 1:开启无线调试
在设备上进入:系统 → 开发者选项 → 无线调试,开启无线调试功能。
步骤 2:配置 hdc 命令路径
将 hdc 工具路径添加到环境变量:
export PATH=$PATH:path/to/deveco_tools/sdk/default/openharmony/toolchains步骤 3:通过 hdc 命令自连
使用 hdc 命令连接设备的 IP 和端口:
hdc tconn IP:端口连接成功后,即可使用 devecocli run 命令推包运行应用。
开发
npm install
npm run dev
npm start -- <command>
npm run lint
npm run format
npm run build- 架构与目录说明见
AGENTS.md - 如需参与维护,建议先阅读
AGENTS.md中的约定与架构说明
