RainMaker Home App CLI

A command-line tool to quickly initialize ESP RainMaker Home app projects with automatic configuration.

Quick Start

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

Follow the interactive prompts to set up your project in minutes!

Installation

Using npx (No Installation Required)

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

Global Installation

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

Commands

init - Initialize New Project

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

What it does:

1. Prompts for project name and template source
2. Clones the RainMaker Home app template (or copies a local template)
3. Collects app identity, versioning, and SDK configuration
4. Optionally configures third-party auth, agents, and CDF autosync
5. Creates configuration file (.env in root directory)
6. Runs npm run prebuild in the generated project
7. Sets up your project ready to use

Example:

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

? App Name / Project Name: MySmartHome
? Application ID: com.example.smarthome
? App Slug: esp-rainmaker-home
? App Schema: rainmaker
? App Version: 3.4.0
? Android Version Code: 31

? Base URL: https://api.rainmaker.espressif.com
? API Version: v1

? Do you want to enable third party auth? Yes

? Auth URL: https://3pauth.rainmaker.espressif.com
? Redirect URL: rainmaker://com.espressif.novahome/success
? Client ID: 1h7ujqjs8140n17v0ahb4n51m2
? Select Third Party Providers: (Google, SignInWithApple)

? Do you want to enable agents? Yes

? Agents Deep Link Host: agents.espressif.com
? Agents Deep Link Path Prefix: /try/agents

? Do you want to enable CDF autosync? Yes
...

✓ Project "MySmartHome" initialized successfully!

cleanup - Clean iOS Dependencies

rainmaker-home-app-cli cleanup --ios

Removes iOS Pods, cleans cache, and reinstalls dependencies.

How It Works

Step-by-Step Process

1. Template Setup

   • Clones template from git repository or copies from local path
   • Supports custom templates: rainmaker-home-app-cli init --template <url|path>
   • Preserves the template .git folder to keep history

2. Configuration Prompts

   • Collects app identity, versioning, and SDK settings
   • Optional flows for third-party auth, agents, and CDF autosync

3. Configuration Generation

   • Creates .env in the root directory with all your settings
   • Stores app identity, SDK URLs, feature flags, and auth settings

4. Prebuild Step

   • Runs npm run prebuild inside the new project
   • Applies the configuration to the template

Generated Project Structure

test/
└── ESP RainMaker Home/
    ├── .env                  # Configuration file
    ├── android/              # Android project
    ├── ios/                  # iOS project
    ├── app/                  # Source code
    └── package.json

Configuration

Required Fields

• App Name: Project name (letters, numbers, hyphens, underscores, spaces)
• Application ID: Bundle identifier (format: com.example.app)
• Base URL: RainMaker API endpoint
• API Version: API version (v1, v2, v3)

Defaults are provided for all fields. Press Enter to accept defaults.

Optional Fields

• App Identity: App slug, schema, version, Android version code
• Third-Party Login: Google, SignInWithApple
• CDF Autosync: Cloud Data Framework autosync
• OAuth Settings: Auth URL, client ID

The CLI generates the redirect URL as <app_schema>://<application_id>/success and prints it during setup so you can use it when configuring third-party login.

• Agents: Deep link host and path prefix

Configuration File

All settings are saved in .env (root directory):

# APP IDENTITY & BRANDING
APP_NAME=MySmartHome
APP_APPLICATION_ID=com.example.smarthome
APP_SLUG=esp-rainmaker-home
APP_SCHEMA=rainmaker

# VERSION INFORMATION
APP_VERSION=3.4.0
ANDROID_VERSION_CODE=31

# SDK CONFIGURATION
BASE_URL=https://api.rainmaker.espressif.com
API_VERSION=v1

# FEATURE FLAGS & OPTIONS
ENABLE_CDF_AUTOSYNC=true
ENABLE_AGENTS=true
ENABLE_THIRD_PARTY_AUTH=true

# THIRD PARTY AUTH CONFIGURATION
THIRD_PARTY_AUTH_REDIRECT_SCHEME=rainmaker
THIRD_PARTY_AUTH_REDIRECT_HOST=com.example.smarthome
THIRD_PARTY_AUTH_CLIENT_ID=1h7ujqjs8140n17v0ahb4n51m2
THIRD_PARTY_AUTH_AUTH_URL=https://3pauth.rainmaker.espressif.com
THIRD_PARTY_AUTH_REDIRECT_URL=rainmaker://com.example.smarthome/success
THIRD_PARTY_AUTH_ENABLED_THIRD_PARTY_PROVIDERS=Google,SignInWithApple

# DEEP LINK & URL SCHEMES
AGENTS_DEEP_LINK_SCHEME=rainmaker
AGENTS_DEEP_LINK_SCHEME_PACKAGE=com.example.smarthome
AGENTS_DEEP_LINK_HOST=agents.espressif.com
AGENTS_DEEP_LINK_PATH_PREFIX=/try/agents

# MATTER CONFIGURATION
MATTER_VENDOR_ID=0x131B
MATTER_ECOSYSTEM_NAME=ESP RainMaker Home

Development

Setup

# Clone repository
git clone <repository-url>
cd rainmaker-app-cli

# Install dependencies
npm install

# Build project
npm run build

# Link for local testing
npm link
rainmaker-home-app-cli init

Scripts

npm run build    # Build TypeScript
npm run watch    # Watch mode for development

Examples

Basic Usage

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

Custom Template

npx @espressif/rainmaker-home-app-cli init --template https://github.com/user/custom-template.git

Local Template

npx @espressif/rainmaker-home-app-cli init --template /path/to/local/template

Troubleshooting

Issue: Template cloning fails

• Solution: Check internet connection or verify template URL

Issue: Application ID validation error

• Solution: Ensure the Application ID format is correct (com.example.app) or press Enter to accept the default

Issue: Android build fails after init

• Solution: Verify package structure was renamed correctly

License

Apache-2.0 License - see LICENSE file for details.

Resources

• ESP RainMaker Documentation
• Report Issues
• Community Forum