deveco-cli

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:

1. --skill (Default): Install deveco-cli skill to AI agents.
2. --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.