HarmonyOS Build & Deploy
One-command build, sign, and deploy for HarmonyOS applications. Works on Windows, macOS, and Linux
out of the box — installing DevEco Studio is enough; the CLI locates the SDK toolchains, ohpm, and
the bundled JBR automatically.
Requirements
- Node.js >= 14
- DevEco Studio (any 5.x or 6.x) — provides hvigorw, hdc, ohpm, and a bundled JBR
- Configured signing certificate (for real-device installation)
Pre-flight Check
Run npx harmonyos-deploy --check to verify the environment (Node, DEVECO_SDK_HOME, JAVA_HOME,
hvigorw, hdc, ohpm, connected devices, signing config, modelVersion consistency, and target SDK
compatibility).
Quick Start
npx harmonyos-deploy --all --launch # Build all + install + launch
npx harmonyos-deploy --all --release --launch # Release mode
npx harmonyos-deploy --app --release # Build .app for AppGallery
CLI Reference
Build Options
| Flag |
Description |
-a, --all |
Build all modules (auto dependency order) |
-m, --module <n> |
Build specific module (default: entry) |
-p, --product <n> |
Product flavor (default: default) |
-b, --build-mode <mode> |
Build mode: debug, release, test |
--release |
Shorthand for -b release |
Device Options
| Flag |
Description |
-d, --device <id> |
Target device ID |
-l, --launch |
Launch app after install |
-u, --uninstall |
Uninstall before install |
--list-devices |
List connected devices |
APP Packaging (AppGallery)
| Flag |
Description |
-A, --app |
Build .app for AppGallery |
-o, --output <dir> |
Output directory |
-n, --name <name> |
Custom filename |
Logging
| Flag |
Description |
--log |
Show device log after deploy |
--log-only |
Only show log, skip build |
--filter <tag> |
Filter log by tag |
Build Commands
# HAP/HSP (device install)
hvigorw assembleHap --mode module -p product={product} -p buildMode={mode} --no-daemon
# APP (AppGallery, always debuggable=false)
hvigorw --mode project -p product={product} -p buildMode={mode} -p debuggable=false assembleApp --no-daemon
Output Paths
# HAP/HSP
{module}/build/{product}/outputs/default/*.hap
# APP
build/outputs/{product}/*.app
Examples
# Full workflow
npx harmonyos-deploy --all --release --launch --log
# Different products
npx harmonyos-deploy --all -p production --release
npx harmonyos-deploy --all -p staging --debug
# APP for store submission
npx harmonyos-deploy --app -p production --release -o ./dist -n MyApp.app
# Debug with logs
npx harmonyos-deploy --log-only --filter MyTag
Troubleshooting
- hdc / hvigorw / ohpm not found: v2.5+ auto-discovers them from DevEco Studio's install dir on Windows, macOS, and Linux. If detection still misses, run
--check to see the candidate paths and fall back to adding SDK toolchains to PATH.
- "Unable to locate a Java Runtime" (PackageHap on macOS): v2.6+ auto-sets
JAVA_HOME to DevEco's bundled JBR. If hit on an older version, export it manually: export JAVA_HOME="/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home".
- targetSdkVersion not installed locally: v2.6+ accepts any local SDK whose API ≥ project target (hvigor 6+ behaviour). To use the exact declared version, install it via DevEco Studio → SDK Manager.
- Signing error: Configure signing in
build-profile.json5.
- Install fails silently: Tool auto force-stops the app before install; if still stuck, use
--uninstall for a clean install.
Links
Source: supermanaaaa/harmonyos-build-deploy — distributed by TomeVault.
1---2name: supermanaaaa-harmonyos-build-deploy-harmonyos-build-deploy3description: HarmonyOS Build & Deploy4---56# HarmonyOS Build & Deploy78One-command build, sign, and deploy for HarmonyOS applications. Works on Windows, macOS, and Linux9out of the box — installing DevEco Studio is enough; the CLI locates the SDK toolchains, ohpm, and10the bundled JBR automatically.1112## Requirements1314- Node.js >= 1415- DevEco Studio (any 5.x or 6.x) — provides hvigorw, hdc, ohpm, and a bundled JBR16- Configured signing certificate (for real-device installation)1718## Pre-flight Check1920Run `npx harmonyos-deploy --check` to verify the environment (Node, DEVECO_SDK_HOME, JAVA_HOME,21hvigorw, hdc, ohpm, connected devices, signing config, modelVersion consistency, and target SDK22compatibility).2324## Quick Start2526```bash27npx harmonyos-deploy --all --launch # Build all + install + launch28npx harmonyos-deploy --all --release --launch # Release mode29npx harmonyos-deploy --app --release # Build .app for AppGallery30```3132## CLI Reference3334### Build Options35| Flag | Description |36|------|-------------|37| `-a, --all` | Build all modules (auto dependency order) |38| `-m, --module <n>` | Build specific module (default: entry) |39| `-p, --product <n>` | Product flavor (default: default) |40| `-b, --build-mode <mode>` | Build mode: debug, release, test |41| `--release` | Shorthand for `-b release` |4243### Device Options44| Flag | Description |45|------|-------------|46| `-d, --device <id>` | Target device ID |47| `-l, --launch` | Launch app after install |48| `-u, --uninstall` | Uninstall before install |49| `--list-devices` | List connected devices |5051### APP Packaging (AppGallery)52| Flag | Description |53|------|-------------|54| `-A, --app` | Build .app for AppGallery |55| `-o, --output <dir>` | Output directory |56| `-n, --name <name>` | Custom filename |5758### Logging59| Flag | Description |60|------|-------------|61| `--log` | Show device log after deploy |62| `--log-only` | Only show log, skip build |63| `--filter <tag>` | Filter log by tag |6465## Build Commands6667```bash68# HAP/HSP (device install)69hvigorw assembleHap --mode module -p product={product} -p buildMode={mode} --no-daemon7071# APP (AppGallery, always debuggable=false)72hvigorw --mode project -p product={product} -p buildMode={mode} -p debuggable=false assembleApp --no-daemon73```7475## Output Paths7677```78# HAP/HSP79{module}/build/{product}/outputs/default/*.hap8081# APP82build/outputs/{product}/*.app83```8485## Examples8687```bash88# Full workflow89npx harmonyos-deploy --all --release --launch --log9091# Different products92npx harmonyos-deploy --all -p production --release93npx harmonyos-deploy --all -p staging --debug9495# APP for store submission96npx harmonyos-deploy --app -p production --release -o ./dist -n MyApp.app9798# Debug with logs99npx harmonyos-deploy --log-only --filter MyTag100```101102## Troubleshooting103104- **hdc / hvigorw / ohpm not found**: v2.5+ auto-discovers them from DevEco Studio's install dir on Windows, macOS, and Linux. If detection still misses, run `--check` to see the candidate paths and fall back to adding SDK toolchains to PATH.105- **"Unable to locate a Java Runtime"** (PackageHap on macOS): v2.6+ auto-sets `JAVA_HOME` to DevEco's bundled JBR. If hit on an older version, export it manually: `export JAVA_HOME="/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home"`.106- **targetSdkVersion not installed locally**: v2.6+ accepts any local SDK whose API ≥ project target (hvigor 6+ behaviour). To use the exact declared version, install it via DevEco Studio → SDK Manager.107- **Signing error**: Configure signing in `build-profile.json5`.108- **Install fails silently**: Tool auto force-stops the app before install; if still stuck, use `--uninstall` for a clean install.109110## Links111112- npm: https://www.npmjs.com/package/harmonyos-deploy113- GitHub: https://github.com/supermanaaaa/harmonyos-build-deploy114115---116> Source: [supermanaaaa/harmonyos-build-deploy](https://github.com/supermanaaaa/harmonyos-build-deploy) — distributed by [TomeVault](https://tomevault.io).117<!-- tomevault:4.0:skill_md:2026-06-19 -->
