zeus-cli

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
# or
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

1. Create — zeus create my-app (or zeus init in an existing folder); answer prompts or pass --appType/--APILevel.
2. Develop — open the Device Simulator app, then zeus dev. Edit code; the simulator auto-refreshes.
3. Test on device — zeus preview, scan the QR with the Zepp App (device needs Developer Mode on). Use -s to pick the device.
4. 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

• references/commands-and-flags.md — full command list + every flag, verified from package source @zeppos/zeus-cli@1.9.1
• Official docs: https://docs.zepp.com/docs/guides/tools/cli/