@oniroproject/oniro-app

Cross-platform command-line interface for Oniro / OpenHarmony application development. One binary drives the whole inner loop — install the SDK and toolchain, scaffold a project, sign and build it, boot the emulator, then install, launch, and drive the app over hdc — on Linux, macOS, and Windows.

It is built for non-interactive use (CI, scripts, agents): every command takes explicit flags, results print to stdout (plain text, or JSON with --json), progress and logs go to stderr, and the process exit code reflects success or failure. No prompts, no TTY assumptions.

This is the CLI frontend for @oniroproject/core — install that package instead if you want to call the same functionality from your own code (see its README for the API).

Install

Requires Node.js 20+. For oniro-app sign you also need a JDK on PATH (java, keytool).

npm install -g @oniroproject/oniro-app
oniro-app --help

Global flags: --version, --help. Run oniro-app <command> --help for the authoritative, up-to-date flags of any command.

Quick start

Set up the toolchain, scaffold an app, then build and run it on the emulator:

# One-time: toolchain + emulator
oniro-app sdk install 6.1
oniro-app cmdtools install
oniro-app emulator install

# Per project
oniro-app create --name HelloOniro --bundle com.example.hello \
                 --location ~/projects --sdk 23
cd ~/projects/HelloOniro
oniro-app sign
oniro-app build

# Run it
oniro-app emulator start --wait-for-hdc 300
oniro-app app install
oniro-app app launch

Once a device or emulator is connected you can inspect and drive it:

oniro-app devices --json
oniro-app screenshot -o shot.jpeg
oniro-app dump layout --json
oniro-app input --type click --x 200 --y 400
oniro-app watch --log 'error|fault' --for 5000 --json

Command reference

Environment & toolchain

Install commands are idempotent (they skip when already present); pass --force to reinstall.

sdk — manage OpenHarmony SDK installs

| Command | Description | | --- | --- | | sdk install <version> [--force] [--tmp-dir <path>] | Download and install an OpenHarmony SDK (e.g. 6.1). --tmp-dir overrides where download/extract temporaries go (see Temporary space). | | sdk list [--json] | List known SDK versions; an * marks installed ones. | | sdk remove <api> | Remove an installed SDK by API level (e.g. 18, 20). |

cmdtools — manage the OpenHarmony command-line tools (provides hvigorw, ohpm, hdc, codelinter)

| Command | Description | | --- | --- | | cmdtools install [--from-zip <path>] [--force] [--tmp-dir <path>] | Install the tools. --from-zip installs from a local archive instead of downloading (required on Windows/macOS — see Configuration); --tmp-dir overrides where download/extract temporaries go (see Temporary space). | | cmdtools status [--json] | Report whether the tools are installed and their version. Exits non-zero when not installed. | | cmdtools remove | Delete the configured command-line-tools directory. |

emulator — manage the Oniro emulator (QEMU-based)

| Command | Description | | --- | --- | | emulator install [--force] [--tmp-dir <path>] | Download and install the emulator. --tmp-dir overrides where the downloaded ZIP goes (see Temporary space). | | emulator start [options] | Start the emulator via the bundled launcher and detach, so the CLI can exit while it keeps running. | | emulator stop | Kill running emulator processes. | | emulator connect [--address <host:port>] | Attempt an hdc connection (default 127.0.0.1:55555). | | emulator remove | Delete the configured emulator directory. |

emulator start options:

| Flag | Description | | --- | --- | | --headless | Launch headless (VNC + telnet serial, no local window). Required in CI. | | --log <path> | Redirect launcher stdout/stderr to a file (default: discard). | | --wait-for-hdc <seconds> | Block until hdc connects, up to N seconds. 0 (default) returns as soon as the launcher spawns. | | --connect <host:port> | Override the launcher's hdc port-forward bind address. Pass 0.0.0.0:55555 on hosts where QEMU refuses to bind 127.0.0.1 (some CI runners). |

Project lifecycle

create — scaffold a new app from a template

All flags are required except where a default is shown (non-interactive). On success the project path is printed to stdout.

| Flag | Description | | --- | --- | | --name <name> | Project folder name (letters, digits, ._-, no slashes). | | --bundle <bundleName> | Bundle name in reverse-DNS form, e.g. com.example.myapp. | | --location <dir> | Parent directory the new project folder is created in. | | --sdk <api> | Target SDK API level (e.g. 18, 20). | | --template <id> | Template id (default EmptyAbility; HarmonyOSApp targets HarmonyOS). | | --module <name> | Module folder name (defaults to the template default, usually entry). | | --overwrite | Replace the destination if it already exists. |

templates — inspect bundled templates

| Command | Description | | --- | --- | | templates list [--json] | List the project templates shipped with the CLI. |

auth — sign in to a Huawei developer account

Only needed for HarmonyOS signing; see HarmonyOS apps.

| Command | Description | | --- | --- | | auth login [--timeout <s>] | Sign in via the browser (default timeout 600s). | | auth logout | Delete the locally stored token. | | auth status [--json] | Show the signed-in account; exits non-zero when signed out. | | auth team list [--json] | List AGC teams. |

sign — generate signing keys, certs, and signingConfigs

sign [project-dir] (defaults to the current directory). Requires java on PATH. Rewrites only the signingConfigs block of build-profile.json5 (other keys are preserved). The generated profile uses the SDK's built-in development cert (issuer=pki_internal) and its validity window — dev/local builds only, not distribution. See Signing apps that need system permissions for --apl / --acls.

| Flag | Description | | --- | --- | | --apl <level> | Ability Privilege Level: normal (default), system_basic, or system_core. | | --app-feature <feature> | hos_normal_app or hos_system_app. Defaults follow --apl. | | --acls <list> | Comma-separated permissions to write into the profile's acls.allowed-acls. | | --bootstrap | No-op if signing material is already present; otherwise generate it. | | --harmonyos | Sign a HarmonyOS project via AppGallery Connect instead of the offline flow. See HarmonyOS apps. | | --team-id <id> | With --harmonyos: AGC team to sign under. | | --product <name> | With --harmonyos: product to sign (default default). | | --force | With --harmonyos: regenerate even when the existing material is still valid. | | --store-password <pwd> / --key-password <pwd> | Keystore passwords (default 123456, the SDK keystore password). |

build — build the app via hvigorw

build [project-dir] (defaults to the current directory). Modules build in parallel by default.

| Flag | Description | | --- | --- | | --product <product> | hvigor product name (default default). | | --module <module> | Restrict the build to a single module. | | --mode <mode> | hvigor build mode (e.g. release, debug). | | --task <task> | hvigor task to run (default assembleHap). | | --no-deps | Skip the automatic ohpm install --all when oh_modules/ is missing. | | --no-parallel | Build modules serially. | | --json | Emit the result (discovered HAPs grouped by module, warnings) as JSON. |

lint — run the OpenHarmony codelinter

lint [project-dir] (defaults to the current directory). Exits with the codelinter's exit code.

| Flag | Description | | --- | --- | | --files <globs...> | Specific files/globs to lint (default: the whole project). | | --json | Emit findings as JSON. |

Device & app

These commands target a connected device or emulator over hdc. Most accept --device <serial> to address a specific target; omit it to use the single connected device.

devices — list connected hdc devices

| Command | Description | | --- | --- | | devices [--json] | List connected targets (serial, connection, status). |

app — install, launch, and manage built apps

| Command | Description | | --- | --- | | app install [project-dir] [--hap <path>] [--device <serial>] | Install the signed .hap via hdc. --hap overrides the resolved path. | | app launch [project-dir] [--module <m>] [--ability <name>] [--device <serial>] | Launch the app. --ability defaults to the module's mainElement / first visible ability. | | app apply [project-dir] --bundle <b> [options] | Install a HAP and verify the running process took the change — handles sign-info mismatch, asset-cache invalidation, and persistent-bundle restart. | | app uninstall <bundle> [--device <serial>] | Uninstall an app by bundle name. | | app stop <bundle> [--device <serial>] | Force-stop an app by bundle name. |

app apply options:

| Flag | Description | | --- | --- | | --bundle <bundle> | Required. Bundle to apply changes to. | | --module <module> | Module to resolve the HAP from (multi-module projects). | | --hap <path> | Explicit .hap path (else resolved from the project + module). | | --installed-hap <path> | Local copy of the currently-installed HAP, to enable the asset-cache reboot diff. | | --system | Treat as a persistent/system bundle (refuses to uninstall on a sign-info mismatch). | | --allow-uninstall | Permit uninstalling a system bundle on sign-info mismatch (dangerous). | | --device <serial> | Target device serial. | | --json | Emit the result (method, pre/post-install pid, cacheCleared) as JSON. |

file — transfer files to/from the device

| Command | Description | | --- | --- | | file send <local> <remote> [--device <serial>] | Push a local file to the device. | | file recv <remote> <local> [--device <serial>] | Pull a file from the device. |

reboot — reboot the device

| Flag | Description | | --- | --- | | --mode <mode> | system (default), bootloader, or recovery. | | --wait-bundle <bundle> | After a system reboot, wait until this bundle is running again. | | --timeout <ms> | Max time to wait for the bundle (default 180000). | | --device <serial> | Target device serial. For a TCP target (an emulator at host:port), passing this reconnects the session across the reboot. |

wait — wait for a device condition

Specify exactly one of --log, --boot, or --bundle.

| Flag | Description | | --- | --- | | --log <pattern> | Resolve when a hilog line (tag: message) matches this regex. | | --boot | Resolve when the device is reachable. | | --bundle <bundle> | With --log: filter to this bundle. Alone: wait until this bundle is running. | | --pid-of <name> | With --boot: also require this process to have a pid. | | --domain <domain> | With --log: hilog domain filter (e.g. 0xD003900). | | --timeout <ms> | Max wait (default 30000). | | --device <serial> | Target device serial. | | --json | With --log: emit the matched entry as JSON. |

watch — collect matching hilog lines for a fixed duration

| Flag | Description | | --- | --- | | --log <pattern> | Required. Regex tested against each line (tag: message). | | --for <ms> | Duration to watch (default 10000). | | --bundle <bundle> | Filter to this bundle. | | --domain <domain> | hilog domain filter. | | --no-dedup | Do not collapse consecutive duplicate lines. | | --device <serial> | Target device serial. | | --json | Emit the collected entries as JSON. |

screenshot — capture the screen as a JPEG

Default: writes the full-resolution raw JPEG. --grid reproduces the old MCP screenshot (downscaled + grid overlay). --contact-sheet captures a burst (default 8 frames) into one tiled sheet and prints per-frame diffs (0..1) on stdout — one image instead of N, pointing you at the frame where something changed.

| Flag | Description | | --- | --- | | -o, --output <file> | Output path (default screenshot.jpeg). | | --grid | Downscale to --max-dim and overlay a 10x10 grid (axes 0.0–1.0) for picking tap coordinates. | | --max-dim <px> | Longest-side cap for --grid / --contact-sheet (256–4096, default 1024). On its own, downscales without a grid. | | --contact-sheet | Capture a burst and composite it into one tiled image with per-frame change diffs. | | --burst <count> | Capture N frames; writes <base>-<i><ext> (or sets the --contact-sheet frame count). | | --interval <ms> | Delay between burst frames (default 50). | | --json | With --contact-sheet, emit the full result object as JSON on stdout. | | --device <serial> | Target device serial. |

dump — dump device state as JSON

| Command | Description | | --- | --- | | dump [layout] | Dump the on-screen UI layout (the default and currently only target) as a pruned, 0–1-normalized tree to stdout. |

| Flag | Description | | --- | --- | | --bundle <bundle> | Filter the layout to a single window/bundle. | | --raw | Return the unpruned tree. | | --device <serial> | Target device serial. |

input / gesture — inject UI input

input injects a single event in pixel coordinates via uitest uiInput:

| Flag | Description | | --- | --- | | --type <type> | Required. One of click, doubleClick, longClick, swipe, drag, fling, keyEvent, inputText. | | --x <px> / --y <px> | Start coordinate (click / swipe start). | | --x2 <px> / --y2 <px> | End coordinate (swipe / drag / fling). | | --speed <px-per-s> | Velocity for swipe / drag / fling. | | --key <key> | Key id or symbolic name (Back / Home / Power) for keyEvent. | | --text <text> | Text for inputText. | | --device <serial> | Target device serial. |

gesture injects a multi-waypoint path:

| Flag | Description | | --- | --- | | --waypoints <json> | Required. JSON array of pixel waypoints [{"x":..,"y":..,"t":..}] (t = ms from start). | | --hold-start <ms> / --hold-end <ms> | Hold at the first/last point before moving/lifting (routes via uinput). | | --device <serial> | Target device serial. |

oniro-app gesture --waypoints '[{"x":200,"y":600,"t":0},{"x":200,"y":200,"t":400}]'

Output & exit codes

• Results → stdout. Plain text by default; --json (where supported) writes JSON.stringify(..., null, 2). Read/observe commands (sdk list, cmdtools status, templates list, devices, wait --log, watch, lint, app apply, build) accept --json (and screenshot with --contact-sheet); dump always emits JSON; action-only commands do not.
• Progress & logs → stderr. stdout stays clean for machine consumers, so oniro-app create … > path.txt or oniro-app devices --json | jq work cleanly.
• Exit code. 0 on success, non-zero on failure (the error message is written to stderr). Set ONIRO_DEBUG=1 to also print full stack traces.

Configuration

The CLI reads paths and URLs from environment variables. All are optional; defaults match the layout used historically by this project. ${userHome} inside any value expands to the current user's home directory.

| Variable | Default | Purpose | | --- | --- | --- | | ONIRO_SDK_ROOT_DIR | ~/setup-ohos-sdk | SDK install root | | ONIRO_CMD_TOOLS_PATH | ~/command-line-tools | Command-line tools install root | | ONIRO_EMULATOR_DIR | ~/oniro-emulator | Emulator install root | | ONIRO_HAP_PATH | entry/build/.../entry-default-signed.hap | Default .hap used by app install (relative to the project) | | ONIRO_SDK_URL_BASE | https://repo.huaweicloud.com/openharmony/os | Base URL for SDK downloads (point at a private/CI mirror) | | ONIRO_CMD_TOOLS_URL_LINUX | Huawei mirror, x64 5.1.0.840 | Override the Linux cmd-tools URL | | ONIRO_CMD_TOOLS_URL_WINDOWS | (unset) | Self-hosted Windows cmd-tools URL | | ONIRO_CMD_TOOLS_URL_MAC | (unset) | Self-hosted macOS cmd-tools URL | | ONIRO_EMULATOR_URL | Latest oniro_emulator.zip | Emulator download URL | | ONIRO_TMP_DIR | <install root>/.oniro-tmp | Scratch directory for download/extract temporaries (see Temporary space) | | ONIRO_APPLICATION_CERT_PATH | (unset) | External application-cert chain to use when signing system apps | | ONIRO_HARMONYOS_SDK_PATH | autodetected | HarmonyOS SDK: a DevEco Studio or HarmonyOS command-line-tools install, or its sdk directory | | ONIRO_HARMONYOS_AUTH_DIR | ~/.oniro/harmonyos | Where the encrypted Huawei account token is stored | | ONIRO_HARMONYOS_SIGNING_DIR | ~/.ohos/config | Where generated HarmonyOS signing material (p12/csr/cer/p7b) is written | | ONIRO_DEBUG | (unset) | Set to 1 for full stack traces on error |

Temporary space

sdk install, cmdtools install, and emulator install download a multi-GB archive and extract it in a scratch directory before moving the result into place. That scratch directory lives next to the install target — .oniro-tmp beside the SDK root, the command-line-tools directory, or the emulator directory — for two reasons:

• The system temp dir is not involved. On many Linux systems /tmp is a RAM-backed tmpfs sized from available memory, so a machine with plenty of disk but little free RAM would run out of "disk" mid-download.
• Temporaries and their destination share a filesystem, so finishing an install is a rename rather than a multi-GB copy across a device boundary.

Override it per command or globally when the install target's filesystem is the cramped one:

oniro-app cmdtools install --tmp-dir ~/.cache/oniro-tmp
export ONIRO_TMP_DIR=~/.cache/oniro-tmp        # applies to all three install commands

Precedence is --tmp-dir → ONIRO_TMP_DIR → <install root>/.oniro-tmp. The directory is created if it does not exist; the per-run folder inside it is removed afterwards, and so is .oniro-tmp itself once empty. If the install target's parent cannot be written to at all (a root-owned prefix, a read-only mount), the system temp dir is used instead and the CLI says so. When space runs short, the install fails with a message naming the directory, how much room it needed, whether that directory is RAM-backed, and this flag — rather than crashing part-way through.

Command-line tools on Windows / macOS. The Huawei mirror only publishes a Linux build of the command-line tools. On Windows and macOS you must either download the ZIP manually from the Huawei developer portal and install it with oniro-app cmdtools install --from-zip path/to/commandline-tools-<platform>.zip, or host the archive yourself and set ONIRO_CMD_TOOLS_URL_WINDOWS / ONIRO_CMD_TOOLS_URL_MAC so cmdtools install can fetch it.

HarmonyOS apps

oniro-app builds and signs HarmonyOS projects as well as OpenHarmony ones. A project is HarmonyOS when its product declares runtimeOS: "HarmonyOS" in build-profile.json5, as DevEco Studio writes; every other project is OpenHarmony and behaves exactly as before.

The two paths differ in one way that matters:

| | OpenHarmony | HarmonyOS | | --- | --- | --- | | SDK | oniro-app sdk install downloads it | Ships inside DevEco Studio or the HarmonyOS command-line tools. Found automatically in Studio's default location or at the command-line-tools path; otherwise set ONIRO_HARMONYOS_SDK_PATH | | Signing | oniro-app sign — fully offline, uses the SDK's development certificate | oniro-app sign --harmonyos — AppGallery Connect issues the certificate and profile | | Account | none | a Huawei developer account (oniro-app auth login) | | Network | none | required | | Device | not required | one registered to the AGC team — a debug profile names the devices it is valid for |

Workflow

oniro-app auth login                       # once per machine
oniro-app create --name MyApp --bundle com.example.myapp \
                 --location ~/projects --sdk 24 --template HarmonyOSApp
cd ~/projects/MyApp
oniro-app sign --harmonyos                 # registers any connected device
oniro-app build
oniro-app app install && oniro-app app launch

Pass --sdk the API level of the installed HarmonyOS SDK (apiVersion in its default/sdk-pkg.json). hvigor builds a HarmonyOS project only against the release its compileSdkVersion names ("SDK component missing" otherwise), so create writes the installed SDK's release, e.g. 6.1.1(24), and warns when --sdk asks for another one.

oniro-app auth

| Command | What it does | | --- | --- | | auth login [--timeout <s>] | Opens the Huawei sign-in page and waits for the browser to redirect back to a loopback port. The URL is also printed, so a headless host can be signed in from another machine. | | auth logout | Deletes the locally stored token. | | auth status [--json] | Prints the signed-in account, and warns when it is not allowed to sign. Exits non-zero when signed out. | | auth team list [--json] | Lists AGC teams; pass an id to sign --harmonyos --team-id. |

The token is stored encrypted under ONIRO_HARMONYOS_AUTH_DIR. It is a credential: the directory is created 0700 and the files 0600.

oniro-app sign --harmonyos

Mirrors DevEco Studio's automatic signing:

1. generates a local p12 keystore and a CSR (via the SDK's hap-sign-tool.jar, so a JDK is needed — DevEco Studio's bundled JBR is used when present);
2. has AppGallery Connect issue a debug certificate for that CSR;
3. registers every connected device's UDID with the team — no device is needed when the team already has some registered (from another machine, or by DevEco Studio);
4. issues a debug provisioning profile naming that certificate, all of the team's registered devices, and any ACL-gated permissions the project requests;
5. writes an encrypted signingConfigs entry into build-profile.json5, leaving other entries untouched.

Material lands in ONIRO_HARMONYOS_SIGNING_DIR (default ~/.ohos/config, the directory DevEco Studio also uses) and is reused, without contacting AGC for anything, while it is still valid: same bundle name and team, unexpired, naming the attached devices and requested permissions, and wired into this project's build-profile.json5. Certificates are a small per-team quota; --force regenerates anyway.

The AGC certificate is named oniro_debug_<team>.cer, distinct from DevEco Studio's auto_debug_<team>.cer: each tool replaces only its own certificate when regenerating, so using both on one team does not revoke the other's signing material.

| Flag | Meaning | | --- | --- | | --harmonyos | Use the AGC path instead of the offline OpenHarmony one | | --team-id <id> | AGC team to issue under (default: the account's own id) | | --product <name> | Product to sign (default default) | | --force | Regenerate even when the existing material is still valid |

Account regions

Accounts from every Huawei region can sign. Sign-in redirects to the account's own region, which then decides the hosts every later call goes to — the ones DevEco Studio resolves through Huawei's routing service:

| Region | Sign-in host | AGC signing host | | --- | --- | --- | | CN | cn.devecostudio.huawei.com | connect-api.cloud.huawei.com | | EU | de.devecostudio.huawei.com | connect-api-dre.cloud.huawei.com | | SG | sg.devecostudio.huawei.com | connect-api-dra.cloud.huawei.com | | RU | ru.devecostudio.huawei.com | connect-api-drru.cloud.huawei.com |

The whole flow has been run with an EU account. Huawei's own CLI accepts only CN accounts.

Limitations

• Real-name verification is not required, but an account without it must have accepted the current HUAWEI Developer Basic Service Agreement — in AppGallery Connect, or by running automatic signing once in DevEco Studio. oniro-app auth status --json reports it as developerAgreement; oniro-app checks it but never accepts it for you.
• A refusal from AGC surfaces as a permissions or not-enrolled error, not as a crash.
• The AGC endpoints are private and undocumented, and can change without notice. See packages/core/src/harmonyos/NOTICE.md for provenance and attribution.

Signing apps that need system permissions

oniro-app sign defaults to --apl normal / --app-feature hos_normal_app, which is fine for ordinary apps. Apps that request permissions above normal (anything with system_basic or system_core availability — e.g. ohos.permission.GET_WIFI_INFO_INTERNAL, ohos.permission.ACCESS_PIN_AUTH) need a higher APL, otherwise bm install fails with grant request permissions failed.

oniro-app sign --apl system_basic           # implies --app-feature hos_system_app
oniro-app sign --apl system_core            # implies --app-feature hos_system_app
oniro-app sign --apl system_basic --app-feature hos_normal_app  # explicit override

When --apl is system_basic or system_core, the HAP signing key automatically switches from OpenHarmony Application Profile Release to OpenHarmony Application Release, and the profile's distribution-certificate is set to the matching CA-signed OpenHarmony Application Release leaf (shipped as a code resource — the SDK only bundles the Profile Release chain). This matches the convention used by every preinstalled OpenHarmony system app's signature/ directory and is required to get past BMS's parse-profile-prop check on install.

Some privileged permissions (e.g. ohos.permission.REBOOT, ohos.permission.INJECT_INPUT_EVENT, ohos.permission.CAPTURE_SCREEN) must additionally appear in the profile's acls.allowed-acls. Pass them via --acls:

oniro-app sign --apl system_core \
    --acls ohos.permission.REBOOT,ohos.permission.INJECT_INPUT_EVENT

The signingConfigs block written to build-profile.json5 mirrors the names used by the project's products[*].signingConfig (e.g. applications/standard/systemui uses release, launcher uses default). If the project has no products section, default is used.

Programmatic use

Everything the CLI does is exposed as a library by @oniroproject/core, so you can embed the same SDK/build/sign/emulator/hdc functionality in an editor extension, an MCP server, or your own tooling. See that package's README for the API reference.

License

Apache-2.0 — see LICENSE.