esp-rainmaker-cli 1.13.1__tar.gz → 1.14.0__tar.gz

{esp_rainmaker_cli-1.13.1 → esp_rainmaker_cli-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: esp-rainmaker-cli
-Version: 1.13.1
+Version: 1.14.0
 Summary: A python utility to perform host based claiming
 Home-page: https://github.com/espressif/esp-rainmaker-cli
 Author: Espressif Systems
@@ -122,6 +122,13 @@ Changelog
 
 All major changes to ESP RainMaker CLI will be documented in this file.
 
+## [1.14.0] - 24-Apr-2026
+### Added
+- New `group sharing` subcommand for sharing device groups / Matter fabrics between users:
+  - `add`, `remove`, `list`, `list-requests`, `accept`, `decline`, `cancel` operations
+  - Supports primary/secondary roles, sub-roles (1-4), metadata, and ownership transfer (`--transfer`, `--new-role`)
+  - Parsed, human-readable output by default; pass `--raw` on any operation to get the underlying JSON response
+
 ## [1.13.1] - 23-Apr-2026
 ### Added
 - Node sharing enhancements:

{esp_rainmaker_cli-1.13.1 → esp_rainmaker_cli-1.14.0}/esp_rainmaker_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: esp-rainmaker-cli
-Version: 1.13.1
+Version: 1.14.0
 Summary: A python utility to perform host based claiming
 Home-page: https://github.com/espressif/esp-rainmaker-cli
 Author: Espressif Systems
@@ -122,6 +122,13 @@ Changelog
 
 All major changes to ESP RainMaker CLI will be documented in this file.
 
+## [1.14.0] - 24-Apr-2026
+### Added
+- New `group sharing` subcommand for sharing device groups / Matter fabrics between users:
+  - `add`, `remove`, `list`, `list-requests`, `accept`, `decline`, `cancel` operations
+  - Supports primary/secondary roles, sub-roles (1-4), metadata, and ownership transfer (`--transfer`, `--new-role`)
+  - Parsed, human-readable output by default; pass `--raw` on any operation to get the underlying JSON response
+
 ## [1.13.1] - 23-Apr-2026
 ### Added
 - Node sharing enhancements:

{esp_rainmaker_cli-1.13.1 → esp_rainmaker_cli-1.14.0}/rainmaker/rainmaker.py

@@ -15,7 +15,12 @@ from rmaker_cmd.cmd_response import get_cmd_requests, create_cmd_request
 from rmaker_cmd.provision import provision
 from rmaker_cmd.test import test
 from rmaker_lib.logger import log
-from rmaker_cmd.group import group_add, group_remove, group_edit, group_list, group_show, group_add_nodes, group_remove_nodes, group_list_nodes
+from rmaker_cmd.group import (group_add, group_remove, group_edit, group_list,
+                              group_show, group_add_nodes, group_remove_nodes,
+                              group_list_nodes, group_sharing_add,
+                              group_sharing_remove, group_sharing_list,
+                              group_sharing_list_requests, group_sharing_accept,
+                              group_sharing_decline, group_sharing_cancel)
 from rmaker_cmd.automation import automation_add, automation_edit, automation_remove, automation_get
 from rmaker_cmd.cache import cache_manage
 from rmaker_cmd.stream import stream_video
@@ -934,6 +939,127 @@ def main():
     add_profile_argument(group_list_nodes_parser)
     group_list_nodes_parser.set_defaults(func=group_list_nodes)
 
+    # group sharing
+    group_sharing_parser = group_subparsers.add_parser(
+        'sharing',
+        help='Share groups / matter fabrics between users',
+        formatter_class=argparse.RawTextHelpFormatter,
+        description='Share groups or matter fabrics with other users.\n'
+                    'Primary users can share groups; secondary users can view '
+                    'their sharing or leave groups they have access to.')
+    group_sharing_parser.set_defaults(
+        func=lambda vars=None: group_sharing_parser.print_help())
+    group_sharing_subparsers = group_sharing_parser.add_subparsers(
+        dest='sharing_command', help='Group sharing operations')
+
+    # group sharing add
+    gs_add_parser = group_sharing_subparsers.add_parser(
+        'add', help='Share group(s) with a user (or add self-sharing without --user)',
+        formatter_class=argparse.RawTextHelpFormatter)
+    gs_add_parser.add_argument('--groups', type=str, required=True,
+                               metavar='<group_ids>',
+                               help='Comma separated group ids (max 10)')
+    gs_add_parser.add_argument('--user', type=str, metavar='<user_name>',
+                               help='User name (email) to share with. Optional.')
+    gs_add_parser.add_argument('--primary', action='store_true',
+                               help='Share with primary access (default: secondary)')
+    gs_add_parser.add_argument('--sub-role', type=int, choices=range(1, 5),
+                               metavar='<1-4>',
+                               help='Custom sub role (1-4)')
+    gs_add_parser.add_argument('--metadata', type=str, metavar='<json>',
+                               help='Custom metadata as a JSON string')
+    gs_add_parser.add_argument('--transfer', action='store_true',
+                               help='Transfer ownership of the group(s) to the user')
+    gs_add_parser.add_argument('--new-role', type=str, choices=['secondary'],
+                               help='Role to assign to self after transfer '
+                                    '(only valid with --transfer)')
+    gs_add_parser.add_argument('--raw', action='store_true',
+                               help='Print the raw JSON response instead of parsed output')
+    add_profile_argument(gs_add_parser)
+    gs_add_parser.set_defaults(func=group_sharing_add)
+
+    # group sharing remove
+    gs_remove_parser = group_sharing_subparsers.add_parser(
+        'remove', help='Remove group sharing with a user',
+        formatter_class=argparse.RawTextHelpFormatter)
+    gs_remove_parser.add_argument('--groups', type=str, required=True,
+                                  metavar='<group_ids>',
+                                  help='Comma separated group ids')
+    gs_remove_parser.add_argument('--user', type=str, required=True,
+                                  metavar='<user_name>',
+                                  help='User name (email) to unshare with')
+    gs_remove_parser.add_argument('--raw', action='store_true',
+                                  help='Print the raw JSON response instead of parsed output')
+    add_profile_argument(gs_remove_parser)
+    gs_remove_parser.set_defaults(func=group_sharing_remove)
+
+    # group sharing list
+    gs_list_parser = group_sharing_subparsers.add_parser(
+        'list', help='Show sharing details for groups / matter fabrics',
+        formatter_class=argparse.RawTextHelpFormatter)
+    gs_list_parser.add_argument('--group-id', type=str, metavar='<group_id>',
+                                help='Fetch sharing details for a single group')
+    gs_list_parser.add_argument('--sub-groups', action='store_true',
+                                help='Include sharing details of sub-groups')
+    gs_list_parser.add_argument('--parent-groups', action='store_true',
+                                help='Include sharing details of parent groups')
+    gs_list_parser.add_argument('--metadata', action='store_true',
+                                help='Include metadata set during sharing')
+    gs_list_parser.add_argument('--raw', action='store_true',
+                                help='Print the raw JSON response instead of parsed output')
+    add_profile_argument(gs_list_parser)
+    gs_list_parser.set_defaults(func=group_sharing_list)
+
+    # group sharing list-requests
+    gs_list_req_parser = group_sharing_subparsers.add_parser(
+        'list-requests', help='List pending group sharing requests',
+        formatter_class=argparse.RawTextHelpFormatter,
+        description='List pending group sharing requests.\n'
+                    'Use --primary-user to list requests raised by you.\n'
+                    'Without the flag, lists requests you have received.')
+    gs_list_req_parser.add_argument('--id', type=str, metavar='<request_id>',
+                                    help='Fetch a specific request by id')
+    gs_list_req_parser.add_argument('--primary-user', action='store_true',
+                                    help='List requests raised by current user '
+                                         '(default: requests received)')
+    gs_list_req_parser.add_argument('--raw', action='store_true',
+                                    help='Print the raw JSON response instead of parsed output')
+    add_profile_argument(gs_list_req_parser)
+    gs_list_req_parser.set_defaults(func=group_sharing_list_requests)
+
+    # group sharing accept
+    gs_accept_parser = group_sharing_subparsers.add_parser(
+        'accept', help='Accept a pending group sharing request')
+    gs_accept_parser.add_argument('--id', type=str, required=True,
+                                  metavar='<request_id>',
+                                  help='Id of the sharing request')
+    gs_accept_parser.add_argument('--raw', action='store_true',
+                                  help='Print the raw JSON response instead of parsed output')
+    add_profile_argument(gs_accept_parser)
+    gs_accept_parser.set_defaults(func=group_sharing_accept)
+
+    # group sharing decline
+    gs_decline_parser = group_sharing_subparsers.add_parser(
+        'decline', help='Decline a pending group sharing request')
+    gs_decline_parser.add_argument('--id', type=str, required=True,
+                                   metavar='<request_id>',
+                                   help='Id of the sharing request')
+    gs_decline_parser.add_argument('--raw', action='store_true',
+                                   help='Print the raw JSON response instead of parsed output')
+    add_profile_argument(gs_decline_parser)
+    gs_decline_parser.set_defaults(func=group_sharing_decline)
+
+    # group sharing cancel
+    gs_cancel_parser = group_sharing_subparsers.add_parser(
+        'cancel', help='Cancel a pending group sharing request (primary side)')
+    gs_cancel_parser.add_argument('--id', type=str, required=True,
+                                  metavar='<request_id>',
+                                  help='Id of the sharing request')
+    gs_cancel_parser.add_argument('--raw', action='store_true',
+                                  help='Print the raw JSON response instead of parsed output')
+    add_profile_argument(gs_cancel_parser)
+    gs_cancel_parser.set_defaults(func=group_sharing_cancel)
+
     # Automation Management
     automation_parser = subparsers.add_parser('automations',
                                               help='Manage automation triggers')

{esp_rainmaker_cli-1.13.1 → esp_rainmaker_cli-1.14.0}/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.13.1"
+VERSION = "1.14.0"

{esp_rainmaker_cli-1.13.1 → esp_rainmaker_cli-1.14.0}/rmaker_cmd/group.py

@@ -3,8 +3,17 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from rmaker_lib.profile_utils import get_session_with_profile
+import datetime
 import json
-from rmaker_cmd.node import _print_node_details
+import sys
+from rmaker_cmd.node import (
+    _get_description,
+    _get_request_expiration,
+    _get_request_id,
+    _get_status,
+    _print_api_error,
+    _print_node_details,
+)
 
 
 def _handle_error(e, operation):
@@ -249,4 +258,211 @@ def group_list_nodes(vars=None):
                     else:
                         print(f"{idx}. {name} (ID: {group_id})")
     except Exception as e:
-        _handle_error(e, "list nodes in group")
+        _handle_error(e, "list nodes in group")
+
+
+def _split_groups(groups_arg):
+    return [g.strip() for g in groups_arg.split(',') if g.strip()]
+
+
+def _print_group_sharing_request_details(resp, is_primary_user=False):
+    requests_in_resp = resp.get('sharing_requests') or []
+    if not requests_in_resp:
+        print("No pending requests")
+        return
+    request_exists = False
+    for request in requests_in_resp:
+        if request.get('request_status', '').lower() == 'declined':
+            continue
+        request_exists = True
+        print("\n{:<15}: {}".format('Request Id', request['request_id']))
+        print("{:<15}: {}".format('Group Id(s)', ','.join(request.get('group_ids', []))))
+        group_names = request.get('group_names') or []
+        if group_names:
+            print("{:<15}: {}".format('Group Name(s)', ','.join(group_names)))
+        if is_primary_user:
+            if 'user_name' in request and request['user_name']:
+                print("{:<15}: {}".format('Shared with', request['user_name']))
+        else:
+            if 'primary_user_name' in request and request['primary_user_name']:
+                print("{:<15}: {}".format('Shared by', request['primary_user_name']))
+        if 'user_role' in request and request['user_role']:
+            print("{:<15}: {}".format('Role', request['user_role']))
+        print(_get_request_expiration(request))
+
+    if not request_exists:
+        print("No pending requests")
+
+
+def _print_group_sharing_details(resp):
+    try:
+        groups_in_resp = resp.get('group_sharing') or []
+        if not groups_in_resp:
+            print("No shared groups")
+            return
+        for group in groups_in_resp:
+            print("\nGroup Id: {}".format(group.get('group_id', '')))
+            users = group.get('users') or {}
+            primary_users = ','.join(users.get('primary') or [])
+            secondary_users = ','.join(users.get('secondary') or [])
+            print("{:<7}: {:<9}: {}".format('Users', 'Primary', primary_users), end='')
+            if secondary_users:
+                print("\n{:>18}: {}".format('Secondary', secondary_users), end='')
+            print()
+    except KeyError:
+        print("Error in displaying details...Please check API Json...Exiting...")
+        sys.exit(0)
+
+
+def _emit(resp, raw, render):
+    if raw:
+        print(json.dumps(resp, indent=2))
+        return
+    if isinstance(resp, dict) and resp.get('status', '').lower() != 'success' and 'error_code' in resp:
+        _print_api_error(resp)
+        return
+    render(resp)
+
+
+def group_sharing_add(vars=None):
+    try:
+        s = get_session_with_profile(vars or {})
+        groups = _split_groups(vars['groups'])
+        if not groups:
+            print("At least one group id must be provided in --groups")
+            return
+        user = vars.get('user')
+        primary = vars.get('primary') if vars.get('primary') else None
+        sub_role = vars.get('sub_role')
+        transfer = vars.get('transfer') if vars.get('transfer') else None
+        new_role = vars.get('new_role')
+        metadata = None
+        metadata_arg = vars.get('metadata')
+        if metadata_arg:
+            try:
+                metadata = json.loads(metadata_arg)
+            except Exception as e:
+                print("Invalid JSON for --metadata:", e)
+                return
+        print("Sharing group(s) with user")
+        resp = s.add_user_group_sharing(
+            groups=groups,
+            user_name=user,
+            primary=primary,
+            sub_role=sub_role,
+            metadata=metadata,
+            transfer=transfer,
+            new_role=new_role,
+        )
+
+        def render(r):
+            if r.get('status', '').lower() == 'success':
+                print("{:<11}: {}".format('Status', _get_status(r)))
+                print("{:<11}: {}".format('Description', _get_description(r)))
+                if 'request_id' in r:
+                    print("{:<11}: {}".format('Request Id', _get_request_id(r)))
+
+        _emit(resp, vars.get('raw', False), render)
+    except Exception as e:
+        _handle_error(e, "add group sharing")
+
+
+def group_sharing_remove(vars=None):
+    try:
+        s = get_session_with_profile(vars or {})
+        groups = _split_groups(vars['groups'])
+        if not groups:
+            print("At least one group id must be provided in --groups")
+            return
+        print("Removing group sharing")
+        resp = s.remove_user_group_sharing(
+            groups=','.join(groups),
+            user_name=vars['user'],
+        )
+
+        def render(r):
+            if r.get('status', '').lower() == 'success':
+                print("{}: {}".format(_get_status(r), _get_description(r)))
+
+        _emit(resp, vars.get('raw', False), render)
+    except Exception as e:
+        _handle_error(e, "remove group sharing")
+
+
+def group_sharing_list(vars=None):
+    try:
+        s = get_session_with_profile(vars or {})
+        resp = s.get_user_group_sharing(
+            group_id=vars.get('group_id'),
+            sub_groups=vars.get('sub_groups', False),
+            parent_groups=vars.get('parent_groups', False),
+            metadata=vars.get('metadata', False),
+        )
+
+        def render(r):
+            print("Displaying group sharing details")
+            _print_group_sharing_details(r)
+
+        _emit(resp, vars.get('raw', False), render)
+    except Exception as e:
+        _handle_error(e, "list group sharing")
+
+
+def group_sharing_list_requests(vars=None):
+    try:
+        s = get_session_with_profile(vars or {})
+        is_primary = vars.get('primary_user', False)
+        resp = s.get_user_group_sharing_requests(
+            request_id=vars.get('id'),
+            primary_user=is_primary,
+        )
+
+        def render(r):
+            print("Displaying pending group sharing requests")
+            print("Current (logged-in) user is set as {} user".format(
+                'Primary' if is_primary else 'Secondary'))
+            _print_group_sharing_request_details(r, is_primary_user=is_primary)
+
+        _emit(resp, vars.get('raw', False), render)
+    except Exception as e:
+        _handle_error(e, "list group sharing requests")
+
+
+def _respond_group_sharing(vars, accept):
+    action = 'accept' if accept else 'decline'
+    try:
+        s = get_session_with_profile(vars or {})
+        resp = s.respond_user_group_sharing_request(
+            request_id=vars['id'], accept=accept)
+
+        def render(r):
+            if r.get('status', '').lower() == 'success':
+                print("{:<11}: {}".format('Status', _get_status(r)))
+                print("{:<11}: {}".format('Description', _get_description(r)))
+
+        _emit(resp, vars.get('raw', False), render)
+    except Exception as e:
+        _handle_error(e, "{} group sharing request".format(action))
+
+
+def group_sharing_accept(vars=None):
+    _respond_group_sharing(vars, accept=True)
+
+
+def group_sharing_decline(vars=None):
+    _respond_group_sharing(vars, accept=False)
+
+
+def group_sharing_cancel(vars=None):
+    try:
+        s = get_session_with_profile(vars or {})
+        print("Cancelling request")
+        resp = s.remove_user_group_sharing_request(request_id=vars['id'])
+
+        def render(r):
+            if r.get('status', '').lower() == 'success':
+                print("{}: {}".format(_get_status(r), _get_description(r)))
+
+        _emit(resp, vars.get('raw', False), render)
+    except Exception as e:
+        _handle_error(e, "cancel group sharing request")

{esp_rainmaker_cli-1.13.1 → esp_rainmaker_cli-1.14.0}/rmaker_lib/session.py

@@ -599,6 +599,154 @@ class Session:
             log.error(f'Failed to list nodes in group: {e}')
             raise
 
+    # Group Sharing API methods
+
+    def add_user_group_sharing(self, groups, user_name=None, primary=None,
+                               sub_role=None, metadata=None, transfer=None,
+                               new_role=None):
+        """Share one or more groups/matter fabrics with another user."""
+        path = 'user/node_group/sharing'
+        payload = {'groups': groups}
+        if user_name:
+            payload['user_name'] = user_name
+        if primary is not None:
+            payload['primary'] = primary
+        if sub_role is not None:
+            payload['sub_role'] = sub_role
+        if metadata is not None:
+            payload['metadata'] = metadata
+        if transfer is not None:
+            payload['transfer'] = transfer
+        if new_role:
+            payload['new_role'] = new_role
+        url = self.config.get_host() + path
+        log.debug(f"Add group sharing request url : {url}")
+        log.debug(f"Add group sharing request payload : {json.dumps(payload)}")
+        try:
+            response = requests.put(url=url, headers=self.request_header,
+                                    json=payload, verify=configmanager.CERT_FILE)
+            log.debug(f"Add group sharing response : {response.text}")
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            log.error(f'Failed to add group sharing: {e}')
+            raise
+
+    def remove_user_group_sharing(self, groups, user_name):
+        """Remove sharing of one or more groups/matter fabrics with a user."""
+        path = 'user/node_group/sharing'
+        params = {'groups': groups, 'user_name': user_name}
+        url = self.config.get_host() + path
+        log.debug(f"Remove group sharing request url : {url}")
+        log.debug(f"Remove group sharing request params : {params}")
+        try:
+            response = requests.delete(url=url, headers=self.request_header,
+                                       params=params, verify=configmanager.CERT_FILE)
+            log.debug(f"Remove group sharing response : {response.text}")
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            log.error(f'Failed to remove group sharing: {e}')
+            raise
+
+    def get_user_group_sharing(self, group_id=None, sub_groups=False,
+                               parent_groups=False, metadata=False):
+        """Fetch group/fabric sharing details for the current user."""
+        path = 'user/node_group/sharing'
+        params = {}
+        if group_id:
+            params['group_id'] = group_id
+        if sub_groups:
+            params['sub_groups'] = 'true'
+        if parent_groups:
+            params['parent_groups'] = 'true'
+        if metadata:
+            params['metadata'] = 'true'
+        url = self.config.get_host() + path
+        log.debug(f"Get group sharing request url : {url}")
+        log.debug(f"Get group sharing request params : {params}")
+        try:
+            response = requests.get(url=url, headers=self.request_header,
+                                    params=params, verify=configmanager.CERT_FILE)
+            log.debug(f"Get group sharing response : {response.text}")
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            log.error(f'Failed to get group sharing: {e}')
+            raise
+
+    def get_user_group_sharing_requests(self, request_id=None, primary_user=None):
+        """Fetch pending group sharing requests (sent or received).
+
+        Pagination is handled internally: the server returns at most 10
+        records per call along with `next_request_id`/`next_user_name`
+        cursors, which are echoed back until the server stops returning
+        them. The consolidated list is returned to the caller.
+        """
+        path = 'user/node_group/sharing/requests'
+        params = {}
+        if request_id:
+            params['request_id'] = request_id
+        if primary_user is not None:
+            params['primary_user'] = 'true' if primary_user else 'false'
+        url = self.config.get_host() + path
+
+        all_requests = []
+        try:
+            while True:
+                log.debug(f"Get group sharing requests url : {url}")
+                log.debug(f"Get group sharing requests params : {params}")
+                response = requests.get(url=url, headers=self.request_header,
+                                        params=params, verify=configmanager.CERT_FILE)
+                log.debug(f"Get group sharing requests response : {response.text}")
+                response.raise_for_status()
+                data = response.json()
+                all_requests.extend(data.get('sharing_requests', []))
+                next_req = data.get('next_request_id')
+                if not next_req:
+                    break
+                params['start_request_id'] = next_req
+                next_user = data.get('next_user_name')
+                if next_user:
+                    params['start_user_name'] = next_user
+            return {'sharing_requests': all_requests, 'total': len(all_requests)}
+        except Exception as e:
+            log.error(f'Failed to get group sharing requests: {e}')
+            raise
+
+    def remove_user_group_sharing_request(self, request_id):
+        """Cancel a pending group sharing request (primary side)."""
+        path = 'user/node_group/sharing/requests'
+        params = {'request_id': request_id}
+        url = self.config.get_host() + path
+        log.debug(f"Cancel group sharing request url : {url}")
+        try:
+            response = requests.delete(url=url, headers=self.request_header,
+                                       params=params, verify=configmanager.CERT_FILE)
+            log.debug(f"Cancel group sharing request response : {response.text}")
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            log.error(f'Failed to cancel group sharing request: {e}')
+            raise
+
+    def respond_user_group_sharing_request(self, request_id, accept):
+        """Accept or decline a group sharing request."""
+        path = 'user/node_group/sharing/requests'
+        payload = {'accept': accept, 'request_id': request_id}
+        url = self.config.get_host() + path
+        log.debug(f"Respond group sharing request url : {url}")
+        log.debug(f"Respond group sharing request payload : {json.dumps(payload)}")
+        try:
+            response = requests.put(url=url, headers=self.request_header,
+                                    json=payload, verify=configmanager.CERT_FILE)
+            log.debug(f"Respond group sharing response : {response.text}")
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            log.error(f'Failed to respond to group sharing request: {e}')
+            raise
+
     # Automation Trigger API methods
 
     def create_automation(self, payload):