RainMaker CLI 用户指南

概述

ESP RainMaker CLI 是一个基于 Python 的命令行工具，供开发者和用户管理和操作其 ESP RainMaker 设备。该工具主要用于公有 RainMaker 部署中的测试与验证，也可通过创建自定义配置文件 (profiles) 用于私有部署。

如需了解 RainMaker CLI 与 Admin CLI 之间的区别，请参阅此文档。
本指南参考自 GitHub 上的 RainMaker CLI 用户指南。

配置 RainMaker CLI

安装 Python 3

如果你已安装了 Python 3，请直接跳到下一节。否则，按照以下步骤操作：

从 Python 官网下载适用于你的操作系统的 Python 3 最新版本。
运行操作系统对应的安装程序来安装 Python 3。
在终端运行以下命令，验证是否安装成功。

$ python3 --version

提示

在 Windows 系统中，使用 python --version 命令验证是否安装成功。

安装依赖

首先安装 Python 包管理工具 pip，然后再安装所需的依赖项。具体步骤如下：

安装 pip

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

提示

在 Windows 上，使用 python get-pip.py 命令安装 pip。

安装 RainMaker CLI

安装 RainMaker CLI 有两种方式：

通过 PyPI 安装。
将 esp-rainmaker-cli 项目克隆到本地计算机。

通过 PyPI 安装

ESP RainMaker CLI 已发布在 Python 包索引 (PyPI)，可使用 pip 安装。

全局安装

$ pip install esp-rainmaker-cli

通过虚拟环境安装（推荐）

### 创建虚拟环境
$ python3 -m venv rainmaker-env

### 激活虚拟环境
### macOS 或 Linux 系统
$ source rainmaker-env/bin/activate

### Windows 系统
$ rainmaker-env\Scripts\activate

### 安装 ESP RainMaker CLI
$ pip install esp-rainmaker-cli

### 操作完成后退出虚拟环境
$ deactivate

用 Git 克隆 esp-rainmaker-cli SDK

除了上述方式之外，还可以前往 esp-rainmaker-cli，将该项目直接克隆到本地。

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

python3 -m pip install -e . 的作用

运行 python3 -m pip install -e . 命令时，会以可编辑（开发）模式安装该软件包。此时，对当前项目目录中源代码的任何修改都会立即生效，通过软件包或其 CLI 命令即可使用更新后的功能，无需每次修改后都重新安装。

RainMaker CLI 使用指南

查看可用的配置文件

说明

此步骤会列出所有可用的配置文件，包括内置配置文件和你的自定义配置文件。每个配置文件都存储了端点的基础 URL 和特定地区相关的设置，用于 ESP RainMaker CLI 与相应的云后端进行通信。

内置配置文件（用于公有 RainMaker）
系统提供两个内置配置文件，分别为 Global ESP RainMaker（默认）和 China ESP RainMaker。根据你所选择的区域，将使用相应的内置配置文件来访问 ESP RainMaker 公有云进行开发和测试。

自定义配置文件（用于私有 RainMaker）
通过指定私有 ESP RainMaker 实例的基础 URL，可以定义自己的配置文件，使 CLI 能够访问你的自定义云端环境。如果你部署了私有 RainMaker，并希望使用 RainMaker CLI 测试其功能，请参阅此文档了解如何添加和切换至自定义配置文件。

命令

$ esp-rainmaker-cli profile list

输出（示例为未自定义配置文件的情况）

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

显示当前配置文件

说明

使用以下命令，显示 ESP RainMaker CLI 当前正在使用的配置文件，包括配置文件类型（内置或自定义）、基础 API 端点及登录状态等关键信息。这有助于确认 CLI 正在连接的环境以及当前认证的用户身份。

命令

$ esp-rainmaker-cli profile current

输出

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

切换到指定配置文件

说明

此步骤用于设置当前在用的配置文件，该配置文件决定了 CLI 在后续操作中使用的基础 URL 和认证。由于 ESP RainMaker 在全球和中国区域使用不同的端点，选择与你所在区域相对应的配置文件，可确保 CLI 与正确的后台环境进行通信。

### 选项 1：全球
$ esp-rainmaker-cli profile switch global

### 选项 2：中国
$ esp-rainmaker-cli profile switch china

私有 RainMaker 添加自定义配置文件

提示

如果你使用的是公共 RainMaker，请跳过此步骤。

介绍

你可以在 RainMaker CLI 中创建自定义配置文件，指向你的私有部署，也可以在这些自定义配置文件之间切换，或根据需要将其移除。这种方式适用于不同场景，例如管理多个环境（如开发、预发布、生产环境），或在不同项目或团队中使用不同的私有 ESP RainMaker 云展开测试。

添加自定义配置文件

### 添加基本自定义配置文件
$ esp-rainmaker-cli profile add company-staging \
    --base-url https://staging.rainmaker.company.com/api/

### 附加描述文字
$ esp-rainmaker-cli profile add company-prod \
    --base-url https://rainmaker.company.com/api/ \
    --description "Company Production Environment"

自定义配置文件的要求

必须提供 --base-url 参数。
base-url 应指向你部署的 ESP RainMaker API 接口地址。
配置文件名只能包含字母和数字，并可以选择性地包含 _、-、.、# 字符。

切换自定义配置文件

$ esp-rainmaker-cli profile switch my-company

删除自定义配置文件

$ esp-rainmaker-cli profile remove company-staging

备注

注意：内置配置文件 global 和 china 无法删除。

有关管理和操作自定义配置文件的详细信息，请参阅配置文件管理文档。

注册或登录 ESP RainMaker 账号

如果你还没有 ESP RainMaker 账号，请使用以下命令注册：

全球区域

$ esp-rainmaker-cli signup <user_name>

按照步骤完成账号注册。
注册成功后，执行以下命令即可基于登录凭证进行登录：

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

中国区域

由于 ESP RainMaker 中国区部署仅支持基于 OAuth 的认证，必须通过交互 UI 界面进行登录。

### 打开浏览器并基于 UI 登录
$ esp-rainmaker-cli login

私有 RainMaker 切换配置文件

说明

如果你使用的是公共 RainMaker，请跳过此步骤。

对自定义配置文件

需要基于登录凭证进行登录（不支持 UI 界面登录）：

### 切换到自定义配置文件
$ esp-rainmaker-cli profile switch my-company

### 登录时必须使用 --user_name 参数
$ esp-rainmaker-cli login --user_name your_email@company.com

获取帮助

运行以下命令，获取任意命令的帮助信息：

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

查看所有可用命令列表：

$ esp-rainmaker-cli --help

可用命令列表

类型	命令	描述
配置及配置文件管理	`configure --region <region>`	配置 ESP RainMaker 区域（中国或全球）
	`profile list`	列出所有可用的配置文件
	`profile current`	显示当前配置文件信息
	`profile switch <name>`	切换到其他配置文件
	`profile add <name> --base-url <url>`	添加新的自定义配置文件
	`profile remove <name>`	删除自定义配置文件
用户管理	`login`	登录 ESP RainMaker 服务
	`logout`	退出 ESP RainMaker 服务
	`signup`	注册新的 ESP RainMaker 账号
	`forgotpassword`	忘记密码，进行密码重置
	`getuserinfo`	获取当前登录用户的详细信息
节点管理	`getnodes`	列出用户关联的所有节点
	`getnodeconfig`	获取节点配置
	`getnodestatus`	获取节点的在线状态
	`getnodedetails`	获取所有节点或指定节点的详细信息
	`removenode`	删除用户与节点的映射关系
参数管理	`getparams`	获取节点参数
	`setparams`	设置节点参数
定时管理	`getschedules`	获取指定节点的定时信息
	`setschedule`	管理指定节点的定时任务（添加/编辑/删除/启用/禁用）
节点共享	`sharing add_user`	请求添加用户以共享节点
	`sharing remove_user`	从共享节点中移除用户
	`sharing accept`	接受共享请求
	`sharing decline`	拒绝共享请求
	`sharing cancel`	取消共享请求
	`sharing list_nodes`	列出节点共享详情
	`sharing list_requests`	列出待处理请求
命令响应（测试版）	`create_cmd_request`	为节点创建一个命令响应请求
	`get_cmd_requests`	获取命令响应请求详情
设备设置	`claim`	对连接在串口的节点进行 Claiming（获取云端登录凭证）
	`provision`	配置节点加入 Wi-Fi 网络
其他操作	`getmqtthost`	获取固件中使用的 MQTT 主机 URL

配置 RainMaker CLI​

安装 Python 3​

安装依赖​

安装 pip​

安装 RainMaker CLI​

通过 PyPI 安装​

用 Git 克隆 esp-rainmaker-cli SDK​

RainMaker CLI 使用指南​

查看可用的配置文件​

显示当前配置文件​

切换到指定配置文件​

私有 RainMaker 添加自定义配置文件​

注册或登录 ESP RainMaker 账号​

私有 RainMaker 切换配置文件​

获取帮助​

可用命令列表​