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 device
• Tail the last error logs from this app
• Check for syntax errors in src/main/ets/pages/Index.ets

常用命令

命令集

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 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 /path/to/project -f

# 配置MCP
devecocli init --mcp
devecocli init --mcp --agent agentname    # agentname需替换为实际的智能体名称   
devecocli init --mcp --project /path/to/project -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 lint

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

命令格式：

devecocli check lint [path]

参数：

device list

查询所有已连接的设备

命令格式：

devecocli device list

device view

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

命令格式：

devecocli device view --target <serialOrName>

参数：

示例：

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>

参数：

说明： 在 OpenHarmony 平台上，未指定 --device 时：无设备连接且 bm/aa 可用则在本地运行；有设备连接时需用 --device local 显式指定本地运行，或 --device <serial> 指定设备。

示例：

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.txt

log

查看hilog普通日志或崩溃日志

命令格式：

devecocli log --device <device> --crash --level <level> --bundle-name <bundle-name> --keyword <keyword> --tail <num> --from <start> --to <end> --follow

参数：

示例：

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.app

skills list

查询可用的 Skill

命令格式：

devecocli skills list --long

参数：

示例：

devecocli skills list
devecocli skills list --long
devecocli skills list -l

skills find

按关键词搜索 Skill

命令格式：

devecocli skills find <keyword>

参数：

示例：

devecocli skills find deveco

skills add

将 Skill 添加到智能体中

命令格式：

devecocli skills add --all --agent <agents> --skill <skill-name> --project <path> --path <path> --force

参数：

示例：

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>

参数：

示例：

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 与 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++ 在同一次调用中混合传入。

hover / definition / declaration / references / implementation

位置类语言特性，共享同一入参结构。返回该位置符号的类型/文档信息、定义/声明位置、引用列表或实现列表。

workspaceSymbol

按名称在全工程搜索符号，无需打开具体文件。

documentSymbol

获取单个文件的符号树，适合文件概览、结构化拆解和大文件切片。

callHierarchy

查询某位置函数的调用关系。

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，应请用户排查并修复工程后再重试。

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"
      ]
    }
  }
}

参数：

signature generate

自动生成调试签名材料（包括p12密钥库、csr证书请求文件、p7b配置文件、cer证书文件），并将签名配置写入项目的 build-profile.json5 中。

命令格式：

devecocli signature generate  --product <product> --team-id <team-id> --udid <udid> --force --help

参数：

示例：

# 自动生成签名并写入工程配置
devecocli signature generate

# 指定product
devecocli signature generate --product default

# 指定team-id
devecocli signature generate --team-id 1222

# 为未连接的设备签名（UDID 为 64 位十六进制，可通过已连接设备的 `hdc shell bm get -u` 获取）
devecocli signature generate --udid 1A2B3C4D...

# 为未连接的穿戴设备签名，并同时传入多台
devecocli signature generate --udid 1A2B3C4D...:wearable --udid 5E6F7A8B...

# 强制覆盖已存在的证书文件
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 中的约定与架构说明

许可证

MIT