SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillshbuilderx-cli

hbuilderx-cli

Testing & quality

View repository

Updated 10-15 21:47

About this skill

HBuilderX CLI Reference

This skill covers the HBuilderX CLI command-line tool (@dcloudio/hbuilderx-cli). Use this skill when users need to launch a uni-app development environment via the command line, view platform logs, run automated tests, or configure the HBuilderX CLI.

HBuilderX CLI is the official command-line tool wrapper provided by DCloud, allowing developers to directly use various HBuilderX features through npm scripts or terminal commands, without manually operating the IDE.

Capability Boundaries

✅ Strong Suits

  1. Launch multi-platform development environments such as Web, Android, iOS, HarmonyOS, mini programs, and more via the command line
  2. View run logs (logcat) for each platform in real time
  3. Run uni-app automated tests (Web/Android/iOS/HarmonyOS)
  4. Integrate HBuilderX workflows into npm scripts and CI/CD pipelines
  5. HBuilderX CLI environment detection and configuration (automatic/manual)

⚠️ Requirements

  1. HBuilderX must already be installed (the CLI automatically detects a running HBuilderX process)
  2. uni-launch command requires HBuilderX 5.0+
  3. uni-logcat and uni-test commands require HBuilderX 4.87+
  4. uni-test requires the uni-app automated testing plugin to be installed in HBuilderX first
  5. iOS real-device development requires a valid Apple developer certificate

❌ Out of Scope (and alternatives)

  1. Use and configuration of the HBuilderX IDE itself → use the official HBuilderX documentation
  2. Writing uni-app application code → use the corresponding front-end framework skill (vue3, vue2, etc.)
  3. Native plugin development → use the HBuilderX native plugin development documentation
  4. Cloud build and release → use the uni-app cloud build documentation
  5. Build tools for non-uni-app projects → use the corresponding build skill (webpack, vite, etc.)

When to use this skill

Use this skill when users need to launch uni-app development via the command line, view run logs, run tests, integrate HBuilderX workflows into npm scripts, or configure the HBuilderX CLI environment.

Typical trigger scenarios:

  • "How do I launch uni-app Web development from the command line?"
  • "How do I run an Android emulator via npm scripts?"
  • "How do I view uni-app run logs?"
  • "How do I configure uni-test?"
  • "What should I do if HBuilderX CLI cannot be found?"

Quick Start

Example invocation:

用命令行启动 uni-app 的 Web 开发环境
配置 npm scripts 来运行 Android 和 iOS 开发
查看 Android 模拟器的运行日志
运行 uni-app 的 Web 自动化测试
解决 HBuilderX CLI 找不到的问题

Workflow

Step 1. Confirm the environment — check whether HBuilderX is installed and running, and confirm the version meets the requirements

Step 2. Choose a command — choose according to your needs hbuilderx、uni-launch、uni-logcat or uni-test

Step 3. Configure platform parameters — specify the target platform (web/app-android/app-ios/mp-weixin, etc.) and platform-specific parameters

Step 4. Execute and debug — run the command, and adjust parameters or troubleshoot issues based on the output

Critical: Command Coverage Map

hbuilderx — general-purpose CLI wrapper

Pass any parameters directly to HBuilderX CLI. If HBuilderX is not running, it will be started automatically.

# 检查版本
hbuilderx --version

# 打开项目
hbuilderx project open --path /path/to/project

# 启动 Web 开发
hbuilderx launch web --project /path/to/project

# 查看日志
hbuilderx logcat web --project /path/to/project

uni-launch — development environment launch

⚠️ Requires HBuilderX 5.0+

Launch development environments for each platform, automatically handling project opening and HBuilderX startup.

Web platform

uni-launch web                          # 使用内置浏览器
uni-launch web --browser Chrome         # 指定 Chrome
uni-launch web --browser Safari         # 指定 Safari
uni-launch web --compile true           # 只编译不运行

Android platform

uni-launch app-android                           # 默认设备
uni-launch app-android --deviceId emulator-5554  # 指定模拟器
uni-launch app-android --playground custom       # 自定义基座
uni-launch app-android --native-log true         # 显示原生日志
uni-launch app-android --continue-on-error true  # 编译错误后继续

iOS Platform

uni-launch app-ios --iosTarget device      # 真机
uni-launch app-ios --iosTarget simulator   # 模拟器
uni-launch app-ios --deviceId iPhone-15-Pro  # 指定设备

Mini Program Platform

uni-launch mp-weixin --runtime-log true    # 微信小程序
uni-launch mp-alipay --runtime-log true    # 支付宝小程序
uni-launch mp-toutiao --runtime-log true   # 抖音小程序

HarmonyOS Platform

uni-launch app-harmony                      # 默认设备
uni-launch app-harmony --deviceId emulator-5554  # 指定模拟器

uni-logcat — Log Viewer

⚠️ Requires HBuilderX 4.87+

View runtime logs for each platform, automatically handling project opening and HBuilderX startup.

uni-logcat web                                    # Web 日志
uni-logcat app-android --deviceId emulator-5554   # Android 指定设备
uni-logcat app-ios --iosTarget device             # iOS 真机
uni-logcat app-ios --iosTarget simulator          # iOS 模拟器
uni-logcat mp-weixin                              # 微信小程序

uni-test — Automated Testing

⚠️ Requires HBuilderX 4.87+ ⚠️ Prerequisite: You must first install the uni-app automated testing plugin

# Web 测试（支持 Chrome/Safari/Firefox，默认 Chrome）
uni-test web --testcaseFile tests/login.test.js
uni-test web --browser Chrome --testcaseFile tests/login.test.js
uni-test web --browser Safari --testcaseFile tests/login.test.js
uni-test web --browser Firefox --testcaseFile tests/login.test.js

# Android 测试（支持真机和模拟器）
uni-test app-android --device_id emulator-5554

# iOS 测试（仅支持模拟器）
uni-test app-ios --device_id iPhone-15-Pro

# HarmonyOS 测试（支持真机和模拟器）
uni-test app-harmony --device_id emulator-5554

Critical: Platform Support Matrix

Platform uni-launch uni-logcat uni-test
Web ✅ ✅ ✅ Chrome/Safari/Firefox
Android ✅ Real device + simulator ✅ ✅ Real device + simulator
iOS ✅ Real device + simulator ✅ ⚠️ Simulator only
HarmonyOS ✅ Real device + simulator ✅ ✅ Real device + simulator
WeChat Mini Program ✅ ✅ —
Alipay Mini Program ✅ ✅ —
Douyin Mini Program ✅ ✅ —

Critical: Version Requirements

Command Minimum HBuilderX Version Description
hbuilderx Any version General-purpose wrapper, no version restrictions
uni-launch 5.0+ Development environment startup command
uni-logcat 4.87+ Log viewer command
uni-test 4.87+ Automated testing command

Check HBuilderX version:

cli --version

Critical: Environment Configuration

Automatic detection (recommended)

HBuilderX CLI automatically detects the running HBuilderX process, no additional configuration required.

Manual configuration

If automatic detection fails, set the HBUILDERX_CLI_PATH environment variable:

# macOS/Linux
export HBUILDERX_CLI_PATH="/Applications/HBuilderX.app/Contents/MacOS/cli"

# Windows (cmd)
set HBUILDERX_CLI_PATH="C:\Program Files\HBuilderX\cli.exe"

# Windows (PowerShell)
$env:HBUILDERX_CLI_PATH = "C:\Program Files\HBuilderX\cli.exe"

Critical: npm scripts Integration

In package.json , configure common commands:

{
  "scripts": {
    "hbuilderx": "hbuilderx",
    "dev:web": "uni-launch web",
    "dev:app-android": "uni-launch app-android",
    "dev:app-ios": "uni-launch app-ios",
    "dev:mp-weixin": "uni-launch mp-weixin",
    "dev:mp-alipay": "uni-launch mp-alipay",
    "dev:mp-toutiao": "uni-launch mp-toutiao",
    "logcat:web": "uni-logcat web",
    "logcat:app-android": "uni-logcat app-android",
    "logcat:app-ios": "uni-logcat app-ios",
    "test:web": "uni-test web",
    "test:app-android": "uni-test app-android",
    "test:app-ios": "uni-test app-ios"
  }
}

Use npm scripts:

npm run dev:web
npm run dev:app-android -- --deviceId emulator-5554
npm run logcat:web
npm run test:web -- --testcaseFile tests/login.test.js

Installation

Global installation (recommended)

npm install -g @dcloudio/hbuilderx-cli

After global installation, you can directly use the hbuilderx、uni-launch、uni-logcat、uni-test command.

Local installation

npm install @dcloudio/hbuilderx-cli --save-dev

After local installation, use it via npm scripts or npx .

Quick Fixes

Problem Solution
command not found: hbuilderx Confirm that npm install -g @dcloudio/hbuilderx-cliis globally installed, or check PATH
找不到 HBuilderX Ensure HBuilderX is started, or manually set the HBUILDERX_CLI_PATH environment variable
uni-launch 命令不可用 Upgrade HBuilderX to version 5.0+
uni-logcat/uni-test 命令不可用 Upgrade HBuilderX to version 4.87+
uni-test 找不到测试插件 Install the uni-app automated testing plugin in HBuilderX
iOS 真机测试失败 iOS only supports simulator testing, not real devices
Android 设备未找到 Check ADB connection:adb devices, confirm the simulator is started or the real device is connected
HBuilderX 版本过低 Check the version via cli --version and update to the latest version
npm scripts 参数传递失败 Passing parameters in npm scripts requires adding --, e.g. npm run dev:web -- --browser Chrome
Windows 路径问题 On Windows, HBUILDERX_CLI_PATH use backslashes or wrap the path in double quotes

Official References

Audience

User Type Usage
uni-app developers Quickly start the development environment via the command line instead of manually operating the IDE
CI/CD engineers Integrate uni-app builds and tests into automated pipelines
Team collaboration Unify the team's development startup commands and standardize workflows via npm scripts
Multi-platform developer A toolchain to manage multi-platform development such as Web/Android/iOS/Mini Programs

Custom options:

  • Specify the target platform (web/app-android/app-ios/mp-weixin, etc.)
  • Specify the device (deviceId/iosTarget)
  • Specify the browser (Chrome/Safari/Firefox)
  • Configure the log level and output

Gotchas

  1. HBuilderX must be started first — The CLI depends on the HBuilderX process; make sure HBuilderX is running or set HBUILDERX_CLI_PATH
  2. Version requirements are not consistent — uni-launch requires 5.0+,uni-logcat and uni-test require 4.87+; confirm the version before use
  3. iOS testing only supports simulators — uni-test app-ios real devices are not supported; this is a platform limitation rather than a tool limitation
  4. The testing plugin must be pre-installed — uni-test The automated testing plugin needs to be installed in HBuilderX first, otherwise the command will fail
  5. npm scripts parameter passing — To pass CLI parameters through npm run you must add the -- separator
  6. Manually configure when automatic detection is unreliable — Automatic detection may fail in some environments (such as multiple instances or non-standard installations); in this case you must set HBUILDERX_CLI_PATH
  7. Note escaping for Windows paths — On Windows, environment variable paths containing spaces need to be wrapped in double quotes

FAQ

Q: hbuilderx and uni-launch What is the difference? A: hbuilderx is a general-purpose wrapper that passes parameters directly through to the HBuilderX CLI;uni-launch is a dedicated development start command that automatically handles project opening and HBuilderX startup, and requires HBuilderX 5.0+. It is recommended to use uni-launch for daily development.

Q: How do I use it in CI/CD? A: Install globally @dcloudio/hbuilderx-cli, make sure HBuilderX is installed and in PATH, set the HBUILDERX_CLI_PATH environment variable, then call uni-launch or uni-test。

Q: Which Mini Program platforms are supported? A: It supports mainstream Mini Program platforms such as WeChat Mini Program (mp-weixin), Alipay Mini Program (mp-alipay), and Douyin Mini Program (mp-toutiao).

Q: How do I view logs for a specific device? A: Use the --deviceId parameter to specify the device, such as uni-logcat app-android --deviceId emulator-5554. On iOS, use the --iosTarget parameter to distinguish between real devices and simulators.

Q: Can I run development environments for multiple platforms at the same time? A: Yes, each platform command runs independently. Just execute the corresponding uni-launch command in different terminal windows.

Q: How do I set environment variables on Windows? A: For cmd use set HBUILDERX_CLI_PATH="C:\Program Files\HBuilderX\cli.exe", and for PowerShell use $env:HBUILDERX_CLI_PATH = "C:\Program Files\HBuilderX\cli.exe". It is recommended to add the settings to the system environment variables for persistence.