# Permission groups (/cli/permission-groups)

Manage organization permission groups, their configuration, and member assignments.

Use the linked API request schema for the supported `--config` keys. Supplied arrays replace their entire lists; omitted settings remain unchanged on update.

`sim permission-groups` is also spelled `sim permission-group`.

These commands accept the [global options](/cli/commands#global-options).

## Group configuration \[#group-configuration]

### List permission groups \[#list-permission-groups]

OAuth login or personal API key required.

```bash
sim permission-groups list [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--organization <value>` | Yes | Organization identifier. |
| `--search <value>` | No | Case-insensitive substring match against the group name. |
| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |

API request and response schemas: [listPermissionGroups](/api-reference/permission-groups/listPermissionGroups).

### Get permission group \[#get-permission-group]

OAuth login or personal API key required.

```bash
sim permission-groups get <groupId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `groupId` | Yes | Permission group identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--organization <value>` | Yes | Organization identifier. |

API request and response schemas: [getPermissionGroup](/api-reference/permission-groups/getPermissionGroup).

### Create permission group \[#create-permission-group]

OAuth login or personal API key required.

```bash
sim permission-groups create [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--organization <value>` | Yes | Organization identifier. |
| `--name <value>` | Yes | Group name, unique within the organization. |
| `--description <value>` | No | Optional group description. |
| `--config <json\|@file>` | No | Group settings to set. Omitted keys use the default permission configuration. (JSON, or @path / @- to read a file or stdin). |
| `--default` | No | Whether the group is the organization default. Only one group can be the default. |
| `--no-default` | No | Send --default as false. |
| `--workspace-ids <json\|@file>` | Conditional | Workspace IDs targeted by a non-default group. Required when creating a non-default group; omit for a default group. (JSON, or @path / @- to read a file or stdin). |

API request and response schemas: [createPermissionGroup](/api-reference/permission-groups/createPermissionGroup).

### Update permission group \[#update-permission-group]

OAuth login or personal API key required.

```bash
sim permission-groups update <groupId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `groupId` | Yes | Permission group identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--organization <value>` | Yes | Organization identifier. |
| `--name <value>` | No | Group name, unique within the organization. |
| `--description <value>` | No | Group description. Null or an empty string clears it; omission leaves it unchanged. (--description null sends the word, not JSON null). |
| `--config <json\|@file>` | No | Patch of group settings. Omitted keys remain unchanged; each supplied array replaces that entire list. (JSON, or @path / @- to read a file or stdin). |
| `--default` | No | Whether the group is the organization default. Only one group can be the default. |
| `--no-default` | No | Send --default as false. |
| `--workspace-ids <json\|@file>` | No | Workspace identifiers for a non-default group. Required on creation; an empty update makes the group inactive. (JSON, or @path / @- to read a file or stdin). |

API request and response schemas: [updatePermissionGroup](/api-reference/permission-groups/updatePermissionGroup).

## Member assignments \[#member-assignments]

### List permission group members \[#list-permission-group-members]

OAuth login or personal API key required.

```bash
sim permission-groups members list [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--organization <value>` | Yes | Organization identifier. |
| `--group <value>` | Yes | Permission group identifier. |
| `--sort-by <value>` | No | Field used to sort the result. Defaults to "assignedAt". Accepted values: `assignedAt`, `userId`. |
| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |

API request and response schemas: [listPermissionGroupMembers](/api-reference/permission-groups/listPermissionGroupMembers).

### Add permission group member \[#add-permission-group-member]

OAuth login or personal API key required.

```bash
sim permission-groups members add [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--organization <value>` | Yes | Organization identifier. |
| `--group <value>` | Yes | Permission group identifier. |
| `--user <value>` | Yes | Existing organization member to add. |

API request and response schemas: [addPermissionGroupMember](/api-reference/permission-groups/addPermissionGroupMember).

### Remove permission group member \[#remove-permission-group-member]

OAuth login or personal API key required.

This removes the member assignment and changes which permission groups apply to the user.

```bash
sim permission-groups members remove <userId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `userId` | Yes | User identifier of the member to remove. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--organization <value>` | Yes | Organization identifier. |
| `--group <value>` | Yes | Permission group identifier. |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [removePermissionGroupMember](/api-reference/permission-groups/removePermissionGroupMember).

### Bulk add permission group members \[#bulk-add-permission-group-members]

OAuth login or personal API key required.

```bash
sim permission-groups members batch-add [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--organization <value>` | Yes | Organization identifier. |
| `--group <value>` | Yes | Permission group identifier. |
| `--user <value...>` | No | User IDs to add; cannot be combined with --all-members (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
| `--all-members` | No | Add every current organization member; cannot be combined with --user. |

API request and response schemas: [bulkAddPermissionGroupMembers](/api-reference/permission-groups/bulkAddPermissionGroupMembers).

## Delete groups \[#delete-groups]

### Delete permission group \[#delete-permission-group]

OAuth login or personal API key required.

This permanently deletes the permission group and its member assignments.

```bash
sim permission-groups delete <groupId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `groupId` | Yes | Permission group identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--organization <value>` | Yes | Organization identifier. |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [deletePermissionGroup](/api-reference/permission-groups/deletePermissionGroup).

## Related docs \[#related-docs]

- [Permission groups](/platform/permissions)