RainMaker Home App CLI

CLI to initialize and manage ESP RainMaker Home app projects.

Requires Node.js >=22

Quick Start

npx @espressif/rainmaker-home-app-cli init

Installation

# One-shot (no install)
npx @espressif/rainmaker-home-app-cli init

# Or install globally
npm install -g @espressif/rainmaker-home-app-cli
rainmaker-home-app-cli init

Commands

| Command | What it does | Prerequisites | |---------|----------------|---------------| | init | Create a project with the setup wizard | Node.js, git, network (to clone the template) | | config | View or edit project env | Run from project root; .env / .env.global / .env.cn | | doctor | Check or set up the Android build environment | Run from project root after init | | cleanup | Clean and reinstall iOS CocoaPods | macOS, Xcode, CocoaPods; ios/ present | | flash | Download and flash Launchpad firmware | USB serial port, esptool on PATH | | agent | Start/stop the MCP agent HTTP server | Node.js (installs agent deps on first start) | | debug | Stream device / mobile / cloud logs | Depends on source — see below |

init — project wizard

Prerequisites: Node.js, git, internet (unless using a local --template).

npx @espressif/rainmaker-home-app-cli init
npx @espressif/rainmaker-home-app-cli init --template <url|path>
npx @espressif/rainmaker-home-app-cli init --branch <name>
npx @espressif/rainmaker-home-app-cli init --config <url|path>

What the wizard covers

1. Project — folder name and app name; clones the Home app template
2. Regions — Global and/or China (you can pick both)
3. Per region
   • App identity (Application ID, schema, version)
   • Backend: ESP RainMaker Classic or ESP RainMaker Neo
   • ESP RainMaker Classic: Base URL, API version, Active SDK (rainmaker-base-sdk or rainmaker-matter-sdk)
   • ESP RainMaker Neo: Neo API / Cognito / IoT fields; Active SDK is fixed to rainmaker-neo-base-sdk
   • Feature flags (set depends on SDK)
   • Third-party login (when enabled), including WeChat options
   • Optional Android release signing
4. China reuse — if both regions are selected, you can reuse Global settings for China (with China cloud defaults applied)
5. Review & write — saves .env.global, .env.cn, and .env

Stack JSON (--config)

Skip backend/SDK prompts by passing a preset:

npx @espressif/rainmaker-home-app-cli init --config ./stack.json
# aliases: config=./stack.json  or  source=./stack.json

Supported shapes:

• ESP RainMaker Classic — { "sdk": "rainmaker-base-sdk"|"rainmaker-matter-sdk", "config": { "baseUrl", "version"|"apiVersion", ... } }
• ESP RainMaker Neo — CDK client outputs (rmneo-base / espuser-base, or legacy rmng-base / esp-user-base)

config — view / edit env

Prerequisites: Project root with env files from init (.env.global / .env.cn, or .env).

rainmaker-home-app-cli config --view
rainmaker-home-app-cli config --edit
rainmaker-home-app-cli config --edit --config ./stack.json

• --view — print Global and China settings
• --edit — interactive review/update; writes .env.global, .env.cn, and .env
• --config — only with --edit; merge a stack preset into the first selected region

doctor — Android developer environment

Prerequisites: Run from the project root after init (ideally after npm install and prebuild:android).

rainmaker-home-app-cli doctor --check
rainmaker-home-app-cli doctor --check --strict
rainmaker-home-app-cli doctor --fix

• --check — verify Node 22, JDK 17, Android SDK packages, and key project files
• --strict — treat warnings as failures
• --fix — sets up / repairs the Android developer environment (guided, with confirmation before each step):
  • Install or configure Node and JDK via the platform package manager (Homebrew / winget / apt)
  • Download Android SDK command-line tools and install platform-tools, platform, build-tools, and NDK via sdkmanager
  • Set ANDROID_HOME (and related PATH) in your shell profile
  • Write android/local.properties when android/ already exists
  • Run npm install if node_modules is missing

Typical flow:

npm install
npm run prebuild:android
rainmaker-home-app-cli doctor --check   # or doctor --fix if something is missing

cleanup — iOS pods

Prerequisites: macOS, Xcode, CocoaPods (pod), and an ios/ folder in the project.

rainmaker-home-app-cli cleanup --ios

Removes Pods, cleans the pod cache, and reinstalls.

flash — Launchpad firmware

Prerequisites: ESP board on USB, serial drivers, and esptool available on PATH. Network needed if the Launchpad config downloads firmware.

rainmaker-home-app-cli flash --config <launchpad.toml url|path>
rainmaker-home-app-cli flash --config <url> --port <path> --baud <rate>
rainmaker-home-app-cli flash --config <url> --app RainMaker_switch --erase

agent — MCP server

Prerequisites: Node.js. First --start may install agent dependencies.

rainmaker-home-app-cli agent --start
rainmaker-home-app-cli agent --start --port 3000 --host 127.0.0.1
rainmaker-home-app-cli agent --start --detach
rainmaker-home-app-cli agent --stop

debug — live logs

Streams selected sources over WebSocket (default port 9234).

Prerequisites by source:

| Source | What you need | |--------|----------------| | Mobile (Android logcat) | adb on PATH, USB debugging enabled, phone connected (or emulator), app running | | ESP UART | USB serial, drivers, esptool on PATH | | CloudWatch | AWS credentials (aws profile / env) with access to the log groups |

rainmaker-home-app-cli debug
rainmaker-home-app-cli debug --open
rainmaker-home-app-cli debug --help

After sources connect, the CLI prints the Debug Hub URL and (on a TTY) asks whether to open it in your browser. Use --open / --no-open to skip that prompt.

See --help for sources, serial ports, packages, devices, and CloudWatch options.

Development

git clone <repository-url>
cd rainmaker-app-cli
npm install
npm run build
npm link

npm run build    # TypeScript build
npm run watch    # Watch mode

License

Apache-2.0 — see LICENSE.

Resources

• ESP RainMaker Documentation
• Report Issues
• Community Forum