RainMaker CLI User Guide

about

The ESP RainMaker CLI is a Python-based command-line tool that allows developers and users to manage and interact with their ESP RainMaker devices. It is primarily used for testing and validation on public RainMaker deployments. It can also be used with private deployments by creating custom "profiles".

• To understand the difference between RainMaker CLI and Admin CLI, please click here.
• This guide refers to the RainMaker CLI User Guide on GitHub.

Setup RainMaker CLI

Installing Python 3

If you have Python 3 already installed, just move on to the next section. Otherwise, follow these steps:

1. Download the lastest version of Python 3 for your OS from the Python website.
2. Run the OS specific installer to install Python 3.
3. Verify the installation by running following command on terminal.

$ python3 --version

note

On Windows, use python-- version to verify the installation.

---

Installing Dependencies

We will have to first install pip, which is a package installer for Python, and then install the dependencies. Here are the steps:

Install pip

$ curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
$ python3 get-pip.py

note

On Windows, use python get-pip.py for pip installation.

---

Install RainMaker CLI

There are two ways to install RainMaker CLI:

1. Install via PyPI.
2. Git clone esp-rainmaker-cli project into your local machine directly.

---

Install via PyPI

ESP RainMaker CLI is available on the Python Package Index (PyPI). It can be installed using pip.

Global Installation

$ pip install esp-rainmaker-cli

Installation via Virtual Environment (recommended)

### Create a virtual environment
$ python3 -m venv rainmaker-env

### Activate the virtual environment
### On macOS/Linux:
$ source rainmaker-env/bin/activate

### On Windows:
$ rainmaker-env\Scripts\activate

### Install ESP RainMaker CLI
$ pip install esp-rainmaker-cli

### When finished, you can deactivate the virtual environment
$ deactivate

---

Git clone esp-rainmaker-cli SDK

Alternatively, you can head over to esp-rainmaker-cli and git clone the project into your local machine directly.

$ git clone https://github.com/espressif/esp-rainmaker-cli.gitcd /path/to/esp-rainmaker-cli/
$ python3 -m pip install -e .

What does python3 -m pip install -e . do?

python3 -m pip install -e . installs the package in editable (development) mode, so that any changes made to the source code in the current directory are immediately reflected when the package or its CLI command is run, without needing to reinstall.

RainMaker CLI Usage Guide

Check Available Profiles

About

This step lists all available profiles, including both built-in and custom (user-defined) profiles. Each profile stores the endpoint base URL and region-specific settings used by the ESP RainMaker CLI to communicate with the appropriate cloud backend.

Built-in profiles (For public RainMaker)
There are two built-in profiles. Mainly Global ESP RainMaker (default) and China ESP RainMaker. Depending on your chosen region, the selected in-built profile is used to access the public ESP RainMaker cloud for development and testing.

Custom profiles (For private RainMaker)
You can define your own profiles by specifying the base URL of a privately deployed ESP RainMaker instance, enabling CLI access to your custom cloud environment. Please refer here to learn how to add and switch a custom profile if you have a private deployment and want to test RainMaker features using RainMaker CLI.

Command

$ esp-rainmaker-cli profile list

Output (Without any user-defined profiles)

global (current)
    Type: builtin
    Description: Global ESP RainMaker (Rest of World)
    Host: https://api.rainmaker.espressif.com/v1/
    Status: Not logged in

china
    Type: builtin
    Description: China ESP RainMaker
    Host: https://api2.rainmaker.espressif.com.cn/v1/
    Status: Not logged in

---

Show Current Profile

About

This command displays the currently active profile used by the ESP RainMaker CLI, including key details such as the profile type (built-in or custom), base API endpoint, and login status. It helps verify which environment the CLI is interacting with and which user is currently authenticated.

Command

$ esp-rainmaker-cli profile current

Output

Current profile: global
Type: builtin
Description: Global ESP RainMaker (Rest of World)
Host: https://api.rainmaker.espressif.com/v1/
Login status: Logged in as user@example.com

---

Switch to Desired Profile

About

This step sets the active profile, which determines the base URL and authentication credentials the CLI will use for all subsequent operations. Since ESP RainMaker has different endpoints for the Global and China regions, selecting the appropriate profile based on the region you are in ensures that the CLI communicates with the intended backend environment.

### Option 1 - Global Region:
$ esp-rainmaker-cli profile switch global

### Option 2 - China Region:
$ esp-rainmaker-cli profile switch china

---

For private RainMaker deployments

disclaimer

Skip this if you are using public RainMaker.

About

You can create custom profiles in the RainMaker CLI to point to your private deployment, switch between these custom profiles, or remove them as needed. This is useful in scenarios such as managing multiple environments (e.g., development, staging, production) or working with different private ESP RainMaker clouds across various projects or teams for testing.

Add Custom Profile

### Basic custom profile
$ esp-rainmaker-cli profile add company-staging \
    --base-url https://staging.rainmaker.company.com/api/

### With description
$ esp-rainmaker-cli profile add company-prod \
    --base-url https://rainmaker.company.com/api/ \
    --description "Company Production Environment"

Requirements for custom profiles

• Must provide --base-url parameter.
• Base URL should point to your ESP RainMaker API endpoint.
• Profile names must be alphanumeric with optional _, -, ., # characters.

---

Switch to Custom Profile

$ esp-rainmaker-cli profile switch my-company

---

Remove Custom Profile

$ esp-rainmaker-cli profile remove company-staging

note

Note: Built-in profiles (global and china) cannot be removed.

For detailed information on managing and operating custom profiles, please refer to the Profile Management documentation.

---

Sign up and/or log in to an ESP RainMaker Account

If you do not have an ESP RainMaker account, please proceed to sign up using the following command:

For Global region

$ esp-rainmaker-cli signup <user_name>

• Then follow the steps to sign up for an account.
• Once you have an account, execute the following command to execute credential-based login:

$ esp-rainmaker-cli login --user_name <email_addr> --password <password>

---

For China region

Since ESP RainMaker China deployments support only OAuth-based authentication, users must log in through the interactive UI-based login flow.

### UI-based login (opens browser)
$ esp-rainmaker-cli login

---

For private RainMaker deployments

disclaimer

Skip this if you are using public RainMaker

For Custom Profiles

Require credential-based login (UI login not supported):

### Switch to custom profile
$ esp-rainmaker-cli profile switch my-company

### Must use --user_name for login
$ esp-rainmaker-cli login --user_name your_email@company.com

---

Getting Help

You can get help on any command by running:

$ esp-rainmaker-cli <command> --help

For the full list of available commands:

$ esp-rainmaker-cli --help

---

Available Commands

Category	Command	Description
Configuration and Profile Management	configure --region <region>	Configure ESP RainMaker region (china, global)
	profile list	List all available profiles
	profile current	Show current profile information
	profile switch <name>	Switch to a different profile
	profile add <name> --base-url <url>	Add a new custom profile
	profile remove <name>	Remove a custom profile
User Management	login	Log in to the ESP RainMaker service
	logout	Log out from the ESP RainMaker service
	signup	Sign up for a new ESP RainMaker account
	forgotpassword	Reset a forgotten password
	getuserinfo	Get details of the currently logged-in user
Node Management	getnodes	List all nodes associated with the user
	getnodeconfig	Get node configuration
	getnodestatus	Get online/offline status of the node
	getnodedetails	Get detailed information for all nodes or a specific node
	removenode	Remove user node mapping
Parameter Management	getparams	Get node parameters
	setparams	Set node parameters
Schedule Management	getschedules	Get schedule information for a specific node
	setschedule	Manage schedules for a specific node (add/edit/remove/enable/disable)
Node Sharing	sharing add_user	Request to add user for sharing nodes
	sharing remove_user	Remove user from shared nodes
	sharing accept	Accept sharing request
	sharing decline	Decline sharing request
	sharing cancel	Cancel sharing request
	sharing list_nodes	List nodes sharing details
	sharing list_requests	List pending requests
Command Response (Beta)	create_cmd_request	Create a command response request for nodes
	get_cmd_requests	Get command response requests details
Device Setup	claim	Claim the node connected to a serial port (get cloud credentials)
	provision	Provision the node to join Wi-Fi network
Other Operations	getmqtthost	Get the MQTT Host URL to be used in the firmware