| name | zeus-cli |
| description | Use when the task is about the Zepp OS Zeus command line tool, @zeppos/zeus-cli, or the zeus command - creating projects, previewing in the simulator, live preview, building or packaging .zab output, QR install/deploy to a watch, login, config, developer bridge, or compiling Mini Program/watchface projects. |
Zeus CLI
Overview
Zeus is the official command-line tool for Zepp OS development. It scaffolds Mini Program / Watchface projects, previews them in the simulator or on a real Amazfit/Zepp device, builds the distributable .zab bundle, and manages devices over a developer bridge. Package: @zeppos/zeus-cli. Binary: zeus.
Requires Node.js >= 14.0.0 (Node 18+ recommended). Add -h / --help to any command for its flags (commands are powered by yargs).
Install
npm i @zeppos/zeus-cli -g
yarn global add @zeppos/zeus-cli
Verify: zeus --version (latest is 1.9.x).
Command Reference
| Command | Purpose |
|---|
zeus create <projectName> | Scaffold a new project — typically creates a new <projectName>/ subfolder (interactive prompts) |
zeus init | Same scaffolding, but in the current directory |
zeus dev | Run in development mode — preview in the simulator with auto-refresh |
zeus preview | Build + show a QR code to install on a real device via the Zepp App |
zeus build | Build for production → .zab bundle in dist/ |
zeus prune | Remove intermediate products from the build artifacts |
zeus bridge | Enter Developer Bridge REPL (bridge$ prompt) — connect to App/Simulator for development and debugging |
zeus cache | Clean or update the device caches |
zeus login / zeus logout | Sign in to / out of your Open Platform account |
zeus status | Show login + simulator/emulator connection status |
zeus config <op> | Manage config values (see below) |
Commands inside zeus bridge (REPL)
After running zeus bridge, a bridge$ prompt opens. The following commands are available only inside the REPL, not as top-level zeus commands:
| Bridge command | Purpose |
|---|
connect | Establish connection to the online App or Simulator |
install | Build and push the project to the connected device |
uninstall [appid] | Uninstall an app / watchface from the connected device |
screenshot | Take a screenshot of the current watch screen (OS 2.0+) |
exit | Exit the bridge REPL |
Flags (verified from source)
create / init — each flag skips its interactive prompt; pass all of them for a fully non-interactive scaffold, or omit any to be prompted for it:
--APILevel <v> — valid: 1.0, 2.0, 3.0, 3.5, 4.0--appType <t> — valid: APP, WATCHFACE, WORKOUT_EXTENSION--withAppSide — include the app-side component--withSettings — include the settings component--template <name>, --shape <shape>
dev
-t, --target "<target>" — set the preview target device
preview / build
-t, --target "<target>" — set the target device-s, --select — enable interactive device-selection mode (default off)--legacy-zpk-name — use the legacy zpk naming convention (default off)
config — generic key/value store managed by the CLI:
zeus config set <key>=<value> [<key>=<value> ...]
zeus config get <key> [<key> ...]
zeus config delete <key> [<key> ...]
zeus config list [--json]
Typical Workflow
- Create —
zeus create my-app (or zeus init in an existing folder); answer prompts or pass --appType/--APILevel.
- Develop — open the Device Simulator app, then
zeus dev. Edit code; the simulator auto-refreshes.
- Test on device —
zeus preview, scan the QR with the Zepp App (device needs Developer Mode on). Use -s to pick the device.
- Ship —
zeus build → grab the .zab from dist/.
Key Distinctions (don't confuse these)
zeus dev vs zeus preview: dev = simulator with live reload; preview = QR code → physical device. Not interchangeable.zeus bridge sub-commands vs top-level: connect, install, uninstall, screenshot are only available inside the zeus bridge REPL (bridge$ prompt), not as standalone zeus commands. Running zeus screenshot at the shell will fail.zeus preview vs bridge install: to put an app on a real device during development, use zeus preview (build → QR → Zepp App). Bridge install is the low-level "push a package to a connected device" primitive inside the REPL — reach for preview unless you specifically need it.zeus create vs zeus init: create typically makes a new subfolder; init scaffolds into the current directory.- Build output is a
.zab file in dist/, never the project root.
Common Mistakes
- Running
zeus dev without the Device Simulator app open → no preview. Launch it first.
- Expecting
zeus preview to target the simulator — it's for real devices; enable Developer Mode in the Zepp App.
- Account actions (
preview, install, publish) failing because you never ran zeus login. Check zeus status.
- Searching for the build in the project root instead of
dist/, or expecting .zip/.zpk — the artifact is .zab.
Reference
