Skip to main content

Groups

Magistrala CLI provides an efficient way to manage groups within your system. This guide covers the key commands for creating, retrieving, updating, and managing groups.

Group Management​

Create Group​

To create a new group, run the following command:

magistrala-cli groups create '{"name":"<group_name>","description":"<description>","metadata":"<metadata>"}' <domain_id> <user_token>

This command registers a new group with the provided details.

Example usage:

magistrala-cli groups create '{"name":"group 1"}' 9879f314-8b0a-4a11-b157-8523491ffa81 token

Expected response:

{
  "created_at": "2025-02-12T09:48:21.886997Z",
  "domain_id": "9879f314-8b0a-4a11-b157-8523491ffa81",
  "id": "a90eced3-daaa-4f51-a031-0103ff00e746",
  "level": 1,
  "name": "group 1",
  "path": "a90eced3-daaa-4f51-a031-0103ff00e746",
  "status": "enabled",
  "updated_at": "0001-01-01T00:00:00Z"
}

Retrieve a Specific Group​

To get the details of group:

magistrala-cli groups get <group_id> <user_token>

Example usage:

Expected response:

Retrieve all Groups​

To list all groups:

magistrala-cli groups get all <user_token>

Example usage:

Expected response:

Update Group Information​

To update a group's details:

magistrala-cli groups update '{"id":"<group_id>","name":"<group_name>","description":"<description>","metadata":"<metadata>"}' <domain_id>  <user_token>

This command allows you to modify the group name, description, and metadata.

Example usage:

magistrala-cli groups update '{"id":"497b188c-d439-43bb-bbd6-d728a736d4ce","name":"Group duo"}' 9879f314-8b0a-4a11-b157-8523491ffa81 token

Expected response:

{
  "created_at": "2025-02-12T09:57:57.05256Z",
  "domain_id": "9879f314-8b0a-4a11-b157-8523491ffa81",
  "id": "497b188c-d439-43bb-bbd6-d728a736d4ce",
  "name": "Group duo",
  "status": "enabled",
  "updated_at": "2025-02-12T09:59:44.829208Z",
  "updated_by": "6ccaf13c-ef88-4cf2-8e3a-c7c04c5eaf9b"
}

Enable Group​

To change group status to enabled:

magistrala-cli groups enable <group_id> <domain_id> <user_token>

Example usage:

magistrala-cli groups enable a90eced3-daaa-4f51-a031-0103ff00e746 9879f314-8b0a-4a11-b157-8523491ffa81 token

Expected response:

{
  "created_at": "2025-02-12T09:48:21.886997Z",
  "domain_id": "9879f314-8b0a-4a11-b157-8523491ffa81",
  "id": "a90eced3-daaa-4f51-a031-0103ff00e746",
  "name": "group 1",
  "status": "enabled",
  "updated_at": "2025-02-12T10:08:37.864362Z",
  "updated_by": "6ccaf13c-ef88-4cf2-8e3a-c7c04c5eaf9b"
}

Disable Group​

To change group status to disabled:

magistrala-cli groups disable <group_id> <domain_id> <user_token>

Example usage:

magistrala-cli groups disable a90eced3-daaa-4f51-a031-0103ff00e746 9879f314-8b0a-4a11-b157-8523491ffa81 token

Expected response:

{
  "created_at": "2025-02-12T09:48:21.886997Z",
  "domain_id": "9879f314-8b0a-4a11-b157-8523491ffa81",
  "id": "a90eced3-daaa-4f51-a031-0103ff00e746",
  "name": "group 1",
  "status": "disabled",
  "updated_at": "2025-02-12T10:07:04.741721Z",
  "updated_by": "6ccaf13c-ef88-4cf2-8e3a-c7c04c5eaf9b"
}

Delete Group​

To delete a group from the system:

magistrala-cli groups delete <group_id> <domain_id> <user_token>

Get Group Members​

magistrala-cli groups members <group_id> <user_token>

Get Memberships​

magistrala-cli groups membership <member_id> <user_token>

Assign Members to Group​

magistrala-cli groups assign <member_ids> <member_type> <group_id> <user_token>

Unassign Members to Group​

magistrala-cli groups unassign <member_ids> <group_id>  <user_token>