| name | deveco-cli |
| description | **MUST** use 'devecocli' for HarmonyOS apps (scaffold, build, run, debug, devices, emulators, logs, docs, 鸿蒙开发文档, skills). **REQUIRED** and **MANDATORY** if workspace has build-profile.json5 or oh-package.json5, or user mentions HarmonyOS, 鸿蒙, DevEco, ArkTS, ArkUI, docs, 鸿蒙文档, 知识, 搜索, or skills. |
DevEco CLI
devecocli wraps DevEco Studio's hvigor, ohpm, hdc, emulator toolchain, and HarmonyOS-skills installer. Prefer devecocli over invoking underlying tools directly.
Available commands: build, run, update, device, emulator, skills, log, create, init, serve, docs.
Sandbox Rule: Commands tagged [Outside sandbox] must be run outside the sandbox.
1. Code → Build → Deploy → Run → Debug
devecocli create
Scaffold a new HarmonyOS project.
--app-name <name> (Req): 1–200 chars, ^[a-zA-Z][a-zA-Z0-9_]*$--project-path <path>: Auto-created if omitted (./<app-name>). Must be empty if exists.--bundle-name <bundle>: Default com.example.<appname-lowercase>. 7–128 chars, ≥3 segments.--api-level <level>: int ≥17 (default: auto or 23).
Ex: devecocli create --app-name MyApp --project-path ./CustomDir --api-level 23
devecocli build [Outside sandbox]
Compile and package project/modules. (Defaults: --product default, --build-mode debug)
| Goal | Command |
|---|
Single-module / single-entry | devecocli build |
| Specific modules | devecocli build --modules <m1> <m2>@<target> |
| Whole product bundle (.app) | devecocli build --product <name> |
| Clean build outputs | devecocli build clean |
devecocli emulator
Manage local emulator instances and system images.
list: Show instances (status, serial, device type).start <names...>: Start instances. Quote names with spaces. (See Troubleshooting if blocked).stop <names...>: Stop by name or serial (127.0.0.1:<port>).create <name> (Req: --device-type, --os-version): Create instance. Optional: --force.delete <name>: Delete instance.image list: List downloaded images. Opts: --device-type <type>, --all, --format <table|json>.image download / image remove (Req: --device-type, --os-version): Download/remove image. (Takes 30+ min, set long timeout).
Device types: phone, foldable, widefold, triplefold, tablet, 2in1, 2in1 foldable, wearable, tv.
devecocli docs
Search/read local HarmonyOS docs.
search <keywords...>: Match any keyword. Opts: --catalog <name>, --format <default|json>, --limit <n>.read <documentId>: Read full content by ID (e.g. devecocli docs read 开发指南/冷启动_Launch分析/Launch模板基本操作/ide-insight-session-launch).catalog: List available catalogs.
devecocli device
list: Show active real devices and running emulators.view: Detailed info. Req -t <name|serial> on multi-device hosts.
devecocli run [Outside sandbox]
Build, install, and launch.
--module <module>: Target module (auto-selected if only one runnable).--device <name|serial>: Target device (Req if multiple connected).--product <product> / --build-mode <mode>: Defaults: default / debug.--ability <ability>: Default from module.json5.--uninstall: Uninstall existing app first (Fixes signing key issues).--skip-build: Deploy existing artifacts.
devecocli log
Fetch hilog or crash logs. Req --device <name|serial> on multi-device hosts.
--crash: Dump crash logs.--level D|I|W|E|F: Filter by level.--bundle-name / --keyword: Filter output.--from <start> / --to <end>: Relative offsets (30s, 5m).--tail <num> / --follow: Keep last N lines / stream real-time (no --to).
Ex: devecocli log --crash --bundle-name com.example.app, devecocli log --level E --from 5m --tail 200
2. Setup
devecocli init
MUTUALLY EXCLUSIVE modes for setup:
--skill (Default): Install deveco-cli skill to AI agents.--mcp: Configure deveco-mcp server (ArkTS/C++ syntax checking).
Options:
--agent <agents>: Comma-separated (e.g. opencode,cursor). Omitting targets all.--project <path>: Project-level config (Abs path for MCP).--path <path>: Direct skill install path.-f, --force: Overwrite existing config.
MCP Rules: Global MCP (no --project) only supports opencode and cursor. Others require --project.
devecocli skills
Manage HarmonyOS skills in AI agents/projects.
list [-l|--long] / find <keyword>: List or search skills.add (--all | --skill <name>) [--agent <a,b…>] [--project <path>] [--path <path>] [-f]: Install.remove --skill <name> [...]: Uninstall.
3. Maintenance
devecocli update [Outside sandbox]: Update CLI to latest version.devecocli serve mcp: Host stdio MCP server (check tool for .ets/C/C++). Used via init --mcp. (Env: PROJECT_PATH, DEVECO_PATH, NODE_MAX_OLD_SPACE_SIZE, DEBUG=1).
Recipes
- Fresh checkout to emulator:
devecocli build -> devecocli emulator list -> devecocli emulator start "Name" -> devecocli run
- Diagnose crash:
devecocli log --crash --bundle-name <bundle>
- Release build:
devecocli build --product oversea --build-mode release
Troubleshooting
- "Product / Build mode
<x> not found": Check build-profile.json5.
- "Multiple entry modules" / "No entry module": Pass
--modules (build) or --module (run).
- "No active devices" / "Multiple devices connected": Connect/start emulator. Pass
-t <serial> (device view) or --device <name|serial> (run/log).
error:install sign info inconsistent: Signing key changed. Run devecocli run --uninstall.skills add agent not found: Valid: codebuddy, cursor, opencode, qoder, trae-cn.emulator start / image download blocked on agreement: User MUST run devecocli emulator license accept in interactive TTY. Agents cannot do this. Do not retry until accepted.image download failure / timeout: Do NOT auto-retry. Give the command to the user to run manually in their terminal.emulator create timeout: Treat as user-action step. Ask user to open DevEco Studio -> Device Manager. Check emulator list after user confirms. Do NOT auto-retry or edit SDK files.image list duplicate OS rows: phone/foldable/widefold/triplefold share the same image. Download/remove ONCE per OS version.
