Merge branch 'task/tag-metadata' into 'master'

node: Add support for node tags and metadata management

See merge request app-frameworks/esp-rainmaker-cli!83

Author: shahpiyushv

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All major changes to ESP RainMaker CLI will be documented in this file.
 
+## [1.11.0] - 09-Feb-2-26
+- Add support for Tags and Metadata during provisioning and also after mapping a user. Check `provision`
+  and `node` commands
+
 ## [1.10.0] - 22-Jan-2026
 ### Added
 - BLE local control support for `getparams`, `setparams`, and `getnodeconfig` commands during provisioning phase:

docs/README.md

@@ -59,6 +59,10 @@ The CLI supports the following main commands:
 * `getnodestatus` - Get online/offline status of the node
 * `getnodedetails` - Get detailed information for all nodes or a specific node
 * `removenode` - Remove user node mapping
+* `node add-tags` - Add tags to a node
+* `node remove-tags` - Remove tags from a node
+* `node set-metadata` - Set or update metadata for a node
+* `node delete-metadata` - Delete metadata from a node
 
 ### Parameter Management
 
@@ -105,6 +109,7 @@ For detailed documentation on specific commands, refer to the following files:
 * [Node Sharing](./commands/node_sharing.md)
 * [Parameter Management](./commands/parameters.md)
 * [Node Management](./commands/node_management.md)
+* [Node Tags and Metadata](./commands/node_tags_metadata.md)
 * [Claiming](./commands/claiming.md)
 * [Provisioning](./commands/provisioning.md)
 * [Command Response](./commands/command_response.md)

docs/commands/node_management.md

@@ -202,6 +202,26 @@ esp-rainmaker-cli removenode abcd1234
 
 This removes the association between your user account and the node. The node will need to be claimed again before it can be used.
 
+### Managing Tags and Metadata
+
+Use the `node` command to add/remove tags and set/delete metadata on existing nodes. See the [Node Tags and Metadata](./node_tags_metadata.md) documentation for full details.
+
+```bash
+# Add tags
+esp-rainmaker-cli node add-tags <nodeid> --tags "location:pune,name:espressif"
+
+# Remove tags
+esp-rainmaker-cli node remove-tags <nodeid> --tags "location:pune"
+
+# Set metadata
+esp-rainmaker-cli node set-metadata <nodeid> --data '{"serial_no": "abc123"}'
+
+# Delete metadata
+esp-rainmaker-cli node delete-metadata <nodeid> --key "serial_no"
+```
+
+Tags and metadata can also be attached during provisioning via the `--tags` and `--metadata` options on the `provision` command.
+
 ## Understanding Node Information
 
 ### Node Structure

docs/commands/node_tags_metadata.md

@@ -0,0 +1,172 @@
+# Node Tags and Metadata
+
+## Overview
+
+ESP RainMaker allows you to attach **tags** and **metadata** to nodes. Tags are simple key-value labels useful for categorization and filtering, while metadata is freeform JSON data for storing custom information about a node.
+
+Tags and metadata can be:
+- **Set during provisioning** (at mapping time, via the `provision` command)
+- **Managed on existing nodes** (via the `node` command)
+
+## The `node` Command
+
+The `node` command provides subcommands for managing tags and metadata on existing nodes.
+
+```bash
+esp-rainmaker-cli node --help
+```
+
+### Add Tags
+
+Add tags to a node. Tags must be in `key:value` format.
+
+```bash
+esp-rainmaker-cli node add-tags <nodeid> --tags <tags>
+```
+
+**Parameters:**
+- `<nodeid>`: Node ID (required)
+- `--tags`: Comma-separated list of tags in `key:value` format (required)
+
+**Examples:**
+```bash
+# Add a single tag
+esp-rainmaker-cli node add-tags mynode123 --tags "location:pune"
+
+# Add multiple tags
+esp-rainmaker-cli node add-tags mynode123 --tags "location:pune,name:espressif,env:production"
+```
+
+### Remove Tags
+
+Remove specific tags from a node.
+
+```bash
+esp-rainmaker-cli node remove-tags <nodeid> --tags <tags>
+```
+
+**Parameters:**
+- `<nodeid>`: Node ID (required)
+- `--tags`: Comma-separated list of tags to remove (required)
+
+**Examples:**
+```bash
+# Remove a single tag
+esp-rainmaker-cli node remove-tags mynode123 --tags "location:pune"
+
+# Remove multiple tags
+esp-rainmaker-cli node remove-tags mynode123 --tags "location:pune,env:production"
+```
+
+### Set Metadata
+
+Set or update metadata for a node. Metadata follows shadow-style merge rules:
+- New keys are added, existing keys are updated
+- Setting a key to `null` deletes that specific key
+- Arrays are overwritten (not merged)
+
+```bash
+esp-rainmaker-cli node set-metadata <nodeid> --data <json>
+esp-rainmaker-cli node set-metadata <nodeid> --filepath <path>
+```
+
+**Parameters:**
+- `<nodeid>`: Node ID (required)
+- `--data`: Metadata as a JSON string (mutually exclusive with `--filepath`)
+- `--filepath`: Path to a JSON file containing metadata (mutually exclusive with `--data`)
+
+**Examples:**
+```bash
+# Set metadata using inline JSON
+esp-rainmaker-cli node set-metadata mynode123 --data '{"serial_no": "abc123", "region": "us"}'
+
+# Set metadata from a file
+esp-rainmaker-cli node set-metadata mynode123 --filepath metadata.json
+
+# Update a specific key (other keys are preserved)
+esp-rainmaker-cli node set-metadata mynode123 --data '{"region": "eu"}'
+
+# Delete a specific key by setting it to null
+esp-rainmaker-cli node set-metadata mynode123 --data '{"region": null}'
+```
+
+### Delete Metadata
+
+Delete metadata from a node. Without `--key`, deletes all metadata. With `--key`, deletes only the specified key(s).
+
+```bash
+esp-rainmaker-cli node delete-metadata <nodeid> [--key <keys>]
+```
+
+**Parameters:**
+- `<nodeid>`: Node ID (required)
+- `--key`: Comma-separated list of metadata keys to delete (optional; if omitted, all metadata is deleted)
+
+**Examples:**
+```bash
+# Delete specific metadata keys
+esp-rainmaker-cli node delete-metadata mynode123 --key "region,serial_no"
+
+# Delete all metadata
+esp-rainmaker-cli node delete-metadata mynode123
+```
+
+## Tags and Metadata During Provisioning
+
+Tags and metadata can also be attached at the time of node mapping during provisioning. This works with all transport modes (BLE, SoftAP, on-network) and both mapping flows (traditional and challenge-response).
+
+```bash
+esp-rainmaker-cli provision [provisioning options] --tags <tags> --metadata <json>
+```
+
+**Parameters:**
+- `--tags`: Comma-separated list of tags in `key:value` format
+- `--metadata`: Metadata as a JSON string
+
+**Examples:**
+```bash
+# BLE provisioning with tags and metadata
+esp-rainmaker-cli provision --pop abcd1234 \
+  --transport ble --device_name PROV_d76c30 \
+  --tags "location:mumbai,env:production" \
+  --metadata '{"serial_no": "abc123", "batch": "2026-Q1"}'
+
+# On-network mapping with tags
+esp-rainmaker-cli provision --transport on-network \
+  --device-ip 192.168.1.50 --pop abcd1234 \
+  --tags "esp.location:office"
+
+# SoftAP provisioning with metadata only
+esp-rainmaker-cli provision --pop abcd1234 \
+  --transport softap \
+  --metadata '{"firmware": "v2.0", "hw_rev": "B"}'
+```
+
+## Tag Format
+
+Tags must follow the `key:value` format:
+- Both key and value are strings
+- Example valid tags: `location:pune`, `name:espressif`, `esp.location:mumbai`
+- Invalid tags (missing colon) will be rejected by the API with error code `105046`
+
+## Metadata Merge Rules
+
+Metadata updates follow shadow-style merge semantics:
+
+| Operation | Payload | Effect |
+|-----------|---------|--------|
+| Add/update keys | `{"key": "value"}` | Upserts the specified keys |
+| Delete a key | `{"key": null}` | Removes that specific key |
+| Delete all metadata | `null` (via `delete-metadata` without `--key`) | Removes all metadata |
+| Overwrite array | `{"regions": ["a", "b"]}` | Replaces the entire array |
+| Empty object | `{}` | No change |
+
+## Viewing Tags and Metadata
+
+Tags and metadata for a node are displayed by the `getnodedetails` command:
+
+```bash
+esp-rainmaker-cli getnodedetails <nodeid>
+```
+
+The output includes `Tags` and `Metadata` sections when they are set on a node.

docs/commands/provisioning.md

@@ -235,6 +235,23 @@ esp-rainmaker-cli provision --sec_ver 2 \
   --sec2_password mypass
 ```
 
+### Provisioning with Tags and Metadata
+
+You can attach tags and metadata to a node at mapping time. This works with all transport modes and both mapping flows (traditional and challenge-response). See [Node Tags and Metadata](./node_tags_metadata.md) for details.
+
+```bash
+# BLE provisioning with tags and metadata
+esp-rainmaker-cli provision --pop abcd1234 \
+  --transport ble --device_name PROV_d76c30 \
+  --tags "location:mumbai,env:production" \
+  --metadata '{"serial_no": "abc123"}'
+
+# On-network mapping with tags
+esp-rainmaker-cli provision --transport on-network \
+  --device-ip 192.168.1.50 --pop abcd1234 \
+  --tags "esp.location:office"
+```
+
 ### User-Node Mapping Without Wi-Fi Provisioning
 ```bash
 # Perform challenge-response mapping and skip sending Wi-Fi credentials
@@ -272,6 +289,8 @@ This workflow will be useful for BLE-only cases in future, wherein the nodes wil
 | `--discovery-timeout` | mDNS discovery timeout in seconds for on-network transport (default: 5.0) | `--discovery-timeout 10.0` |
 | `--disable-chal-resp` | Disable challenge-response on device after successful mapping (default: True for on-network, False for BLE/SoftAP) | `--disable-chal-resp` |
 | `--no-disable-chal-resp` | Do NOT disable challenge-response after successful mapping (overrides `--disable-chal-resp`) | `--no-disable-chal-resp` |
+| `--tags` | Comma-separated tags in `key:value` format to attach during node mapping | `--tags "location:pune,name:espressif"` |
+| `--metadata` | Metadata as JSON string to attach during node mapping | `--metadata '{"serial_no": "abc123"}'` |
 
 ## Provisioning Process
 

rainmaker/rainmaker.py

@@ -7,6 +7,7 @@
 import sys
 import argparse
 from rmaker_cmd.node import *
+from rmaker_cmd.node import node_add_tags, node_remove_tags, node_set_metadata, node_delete_metadata
 from rmaker_cmd.user import signup, login, forgot_password,\
                             get_user_details, logout, set_region_configuration, \
                             profile_list, profile_current, profile_switch, profile_add, profile_remove, delete_user
@@ -483,6 +484,16 @@ def main():
                                   help='Do NOT disable challenge-response on device after successful mapping.\n'
                                        'Overrides the transport-specific default behavior.')
 
+    provision_parser.add_argument('--tags',
+                                  type=str,
+                                  help='Comma-separated list of tags to attach during node mapping\n'
+                                       '(e.g., "location:pune,name:espressif"). Tags must be in key:value format.')
+
+    provision_parser.add_argument('--metadata',
+                                  type=str,
+                                  help='Metadata as JSON string to attach during node mapping\n'
+                                       '(e.g., \'{"serial_no": "abc123", "region": "us"}\')')
+
     add_profile_argument(provision_parser)
     provision_parser.set_defaults(func=provision)
 
@@ -839,6 +850,89 @@ def main():
     add_profile_argument(group_list_nodes_parser)
     group_list_nodes_parser.set_defaults(func=group_list_nodes)
 
+    # Node Management (tags, metadata)
+    node_parser = subparsers.add_parser('node',
+                                        help='Manage node properties (tags, metadata)')
+    node_parser.set_defaults(func=lambda vars=None: node_parser.print_help())
+    node_subparsers = node_parser.add_subparsers(dest='node_command', help='Node operations')
+
+    # node add-tags
+    node_add_tags_parser = node_subparsers.add_parser('add-tags',
+                                                       help='Add tags to a node',
+                                                       description='Add tags to a node. Tags must be in key:value format.')
+    node_add_tags_parser.add_argument('nodeid',
+                                      type=str,
+                                      metavar='<nodeid>',
+                                      help='Node ID for the node')
+    node_add_tags_parser.add_argument('--tags',
+                                      type=str,
+                                      required=True,
+                                      metavar='<tags>',
+                                      help='Comma-separated list of tags in key:value format\n'
+                                           '(e.g., "location:pune,name:espressif")')
+    add_profile_argument(node_add_tags_parser)
+    node_add_tags_parser.set_defaults(func=node_add_tags)
+
+    # node remove-tags
+    node_remove_tags_parser = node_subparsers.add_parser('remove-tags',
+                                                          help='Remove tags from a node',
+                                                          description='Remove specific tags from a node.')
+    node_remove_tags_parser.add_argument('nodeid',
+                                         type=str,
+                                         metavar='<nodeid>',
+                                         help='Node ID for the node')
+    node_remove_tags_parser.add_argument('--tags',
+                                         type=str,
+                                         required=True,
+                                         metavar='<tags>',
+                                         help='Comma-separated list of tags to remove\n'
+                                              '(e.g., "location:pune,name:espressif")')
+    add_profile_argument(node_remove_tags_parser)
+    node_remove_tags_parser.set_defaults(func=node_remove_tags)
+
+    # node set-metadata
+    node_set_metadata_parser = node_subparsers.add_parser('set-metadata',
+                                                           help='Set or update metadata for a node',
+                                                           description='Set or update metadata for a node.\n'
+                                                                       'Follows shadow-style merge rules:\n'
+                                                                       '  - New keys are added, existing keys are updated\n'
+                                                                       '  - Set a key to null to delete it\n'
+                                                                       '  - Arrays are overwritten (not merged)')
+    node_set_metadata_parser.add_argument('nodeid',
+                                          type=str,
+                                          metavar='<nodeid>',
+                                          help='Node ID for the node')
+    node_set_metadata_data_group = node_set_metadata_parser.add_mutually_exclusive_group(required=True)
+    node_set_metadata_data_group.add_argument('--data',
+                                              type=str,
+                                              metavar='<json>',
+                                              help='Metadata as JSON string\n'
+                                                   '(e.g., \'{"key": "value", "region": "us"}\')')
+    node_set_metadata_data_group.add_argument('--filepath',
+                                              type=str,
+                                              metavar='<path>',
+                                              help='Path to JSON file containing metadata')
+    add_profile_argument(node_set_metadata_parser)
+    node_set_metadata_parser.set_defaults(func=node_set_metadata)
+
+    # node delete-metadata
+    node_delete_metadata_parser = node_subparsers.add_parser('delete-metadata',
+                                                              help='Delete metadata from a node',
+                                                              description='Delete metadata from a node.\n'
+                                                                          'Without --key, deletes all metadata.\n'
+                                                                          'With --key, deletes only the specified key(s).')
+    node_delete_metadata_parser.add_argument('nodeid',
+                                             type=str,
+                                             metavar='<nodeid>',
+                                             help='Node ID for the node')
+    node_delete_metadata_parser.add_argument('--key',
+                                             type=str,
+                                             metavar='<keys>',
+                                             help='Comma-separated list of metadata keys to delete\n'
+                                                  '(e.g., "region,name"). If omitted, all metadata is deleted.')
+    add_profile_argument(node_delete_metadata_parser)
+    node_delete_metadata_parser.set_defaults(func=node_delete_metadata)
+
     # Raw API command
     raw_api_parser = subparsers.add_parser('raw-api',
                                           help='Make raw API calls to RainMaker backend',

rainmaker/version.py

@@ -5,4 +5,4 @@
 # SPDX-License-Identifier: Apache-2.0
 
 # This file contains the version information for the ESP RainMaker CLI
-VERSION = "1.10.0"
+VERSION = "1.11.0"