> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/groups.md).

# groups

Manage end-user access groups. A group bundles roles (`_roleIds`) and direct MCP-server grants (`resourceGrants`); member end users receive the union. Memberships are edited from the group side with `add-members`/`remove-members`, taking access-record ids (ashareIds) from [`end-users list`](/cli/commands/end-users.md#celigo-end-users-list).

**REST API**: [Groups](https://developer.celigo.com/api/api-reference/groups)

```
celigo groups <subcommand> [args] [flags]
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## Subcommands

| Subcommand                                | Purpose                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| `list`                                    | List all groups.                                                             |
| `get <id>`                                | Fetch one group by ID.                                                       |
| `create`                                  | Create a group from a JSON body (`--file <path>` or stdin).                  |
| `update <id>`                             | Full replace from a JSON body (`--file <path>` or stdin); destructive `PUT`. |
| `set <id> key=value …`                    | Safe field edit (GET → modify → PUT). Supports `key=file://<path>`.          |
| `delete <id>`                             | Delete a group.                                                              |
| `add-members <groupId> <ashareIds...>`    | Add end users to the group as manual memberships.                            |
| `remove-members <groupId> <ashareIds...>` | Remove manual memberships from the group.                                    |

***

## `celigo groups list`

List all groups. Rows are trimmed to `_id`, `name`, and the table columns client-side (the endpoint rejects server-side field projection); use `--fields all` for complete documents.

**Signature**

```bash
celigo groups list
```

**Arguments**

None.

**Flags**

| Flag              | Type   | Default   | Description                                                                                                                                                                                                                                              |
| ----------------- | ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--fields <spec>` | string | `default` | Fields to return per row. `default` returns `_id`, `name`, and the table columns; `all` returns complete documents; a comma-separated list requests specific fields. Applied client-side — see [field projection](/cli/getting-started/global-flags.md). |

Default table columns: `_id`, `name`, `description`, `hasIdpSyncedMembers`, `lastModified`.

**Example**

```bash
celigo groups list --format table
```

**Corresponds to**: [`GET /v1/groups`](https://developer.celigo.com/api/api-reference/groups)

***

## `celigo groups get <id>`

Fetch one group by ID, including its `_roleIds`, `resourceGrants`, and membership metadata.

**Signature**

```bash
celigo groups get <id>
```

**Arguments**

| Argument | Type   | Required | Description                              |
| -------- | ------ | -------- | ---------------------------------------- |
| `<id>`   | string | Yes      | Group ID (the `_id` from `groups list`). |

**Example**

```bash
celigo groups get 68a1b2c3d4e5f6a7b8c9d0e1
```

**Corresponds to**: [`GET /v1/groups/{_id}`](https://developer.celigo.com/api/api-reference/groups)

***

## `celigo groups create`

Create a group from a JSON body. Read the body from a file with `-f, --file` (recommended), or pipe it on stdin. Group names are unique per account — a duplicate is rejected with `409 Conflict`.

**Signature**

```bash
celigo groups create --file <path>
celigo groups create < group.json     # or pipe on stdin
```

**Flags**

| Flag                | Type   | Default | Description                                                                    |
| ------------------- | ------ | ------- | ------------------------------------------------------------------------------ |
| `-f, --file <path>` | string | —       | Read the JSON body from a file instead of stdin (`--file -` also means stdin). |

**Request body**

A JSON object matching the `POST /v1/groups` request schema: `name` (required, unique per account), optional `description`, `_roleIds[]` (roles every member receives), and `resourceGrants[]` (direct MCP-server grants — each entry names one server via `_resourceId`, or omits it for a wildcard across all, plus a `capabilities[]` list of `tool:all`, `tool:<id>`, `api:all`, `api:<id>`, or `pset:<permissionSetId>` values).

**Example**

```bash
celigo groups create --file ./support-team.json
```

**Corresponds to**: [`POST /v1/groups`](https://developer.celigo.com/api/api-reference/groups)

***

## `celigo groups update <id>`

Full replace of a group from a JSON body (`--file <path>` or stdin).

> ⚠️ **`update` replaces the entire group.** `PUT` erases any field you omit — `description`, `_roleIds`, `resourceGrants`. `GET` the group first, edit it, then send the complete object back, or use `set` for targeted edits.

**Signature**

```bash
celigo groups update <id> --file <path>
celigo groups update <id> < group.json     # or pipe on stdin
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Group ID.   |

**Flags**

| Flag                | Type    | Default | Description                                                                          |
| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------ |
| `-f, --file <path>` | string  | —       | Read the JSON body from a file instead of stdin (`--file -` also means stdin).       |
| `--force`           | boolean | `false` | Submit even if the body contains masked credential values (`***`) copied from a GET. |

**Example**

```bash
celigo groups get 68a1b2c3d4e5f6a7b8c9d0e1 --format json \
  | jq '.description = "EU support engineers"' \
  | celigo groups update 68a1b2c3d4e5f6a7b8c9d0e1
```

**Corresponds to**: [`PUT /v1/groups/{_id}`](https://developer.celigo.com/api/api-reference/groups)

***

## `celigo groups set <id> [assignments...]`

Edit one or more fields on a group without rewriting the whole document. Performs GET → apply assignments → PUT, so omitted fields survive. Dot and array-index notation are supported; `key=null` removes a field; `key=file://<path>` loads a value from a file.

**Signature**

```bash
celigo groups set <id> key=value [key2=value2 ...]
```

**Arguments**

| Argument           | Type              | Required | Description                                                                                       |
| ------------------ | ----------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `<id>`             | string            | Yes      | Group ID.                                                                                         |
| `[assignments...]` | `key=value` pairs | Yes (≥1) | Field assignments, e.g. `description="EU support"` or `_roleIds[1]=null`. Values are JSON-parsed. |

**Example**

```bash
celigo groups set 68a1b2c3d4e5f6a7b8c9d0e1 'description=EU support engineers'
```

**Corresponds to**: [`GET /v1/groups/{_id}`](https://developer.celigo.com/api/api-reference/groups) then [`PUT /v1/groups/{_id}`](https://developer.celigo.com/api/api-reference/groups)

***

## `celigo groups delete <id>`

Delete a group by ID. Prompts for confirmation unless `-y` is passed. Members lose whatever access they received through this group; their other groups, roles, and direct grants are untouched.

**Signature**

```bash
celigo groups delete <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Group ID.   |

**Flags**

| Flag        | Type    | Default | Description                   |
| ----------- | ------- | ------- | ----------------------------- |
| `-y, --yes` | boolean | `false` | Skip the confirmation prompt. |

**Example**

```bash
celigo groups delete 68a1b2c3d4e5f6a7b8c9d0e1 -y
```

**Corresponds to**: [`DELETE /v1/groups/{_id}`](https://developer.celigo.com/api/api-reference/groups)

***

## `celigo groups add-members <groupId> <ashareIds...>`

Add end users to the group as manual memberships. Takes up to 100 access-record ids per call. Requires `full` mode — membership changes rewrite who can access your MCP servers.

**Signature**

```bash
celigo groups add-members <groupId> <ashareIds...>
```

**Arguments**

| Argument         | Type              | Required | Description                                                   |
| ---------------- | ----------------- | -------- | ------------------------------------------------------------- |
| `<groupId>`      | string            | Yes      | Group ID.                                                     |
| `<ashareIds...>` | string (variadic) | Yes      | End-user access-record ids from `end-users list` (up to 100). |

**Example**

```bash
celigo groups add-members 68a1b2c3d4e5f6a7b8c9d0e1 68f0a9b2c7d3e8f1a2b3c4d5 68f0a9b2c7d3e8f1a2b3c4d6
```

**Corresponds to**: [`POST /v1/groups/{groupId}/members`](https://developer.celigo.com/api/api-reference/groups)

***

## `celigo groups remove-members <groupId> <ashareIds...>`

Remove manual memberships from the group. IdP-synced memberships (`source: idp`) cannot be removed here — change the IdP group mapping instead. Requires `full` mode.

**Signature**

```bash
celigo groups remove-members <groupId> <ashareIds...>
```

**Arguments**

| Argument         | Type              | Required | Description                                       |
| ---------------- | ----------------- | -------- | ------------------------------------------------- |
| `<groupId>`      | string            | Yes      | Group ID.                                         |
| `<ashareIds...>` | string (variadic) | Yes      | End-user access-record ids to remove (up to 100). |

**Example**

```bash
celigo groups remove-members 68a1b2c3d4e5f6a7b8c9d0e1 68f0a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`POST /v1/groups/{groupId}/members/remove`](https://developer.celigo.com/api/api-reference/groups)

***

## Gotchas

* **Group names are unique per account.** Both `create` and a rename via `update`/`set` are rejected with `409 Conflict` on a duplicate.
* **`update` is a full PUT.** A body that omits `description`, `_roleIds`, or `resourceGrants` erases them. Prefer `set` for single-field changes.
* **Memberships are edited from the group side.** There is no per-end-user membership command — pass ashareIds from `end-users list` to `add-members`/`remove-members`.
* **IdP-synced memberships are read-only here.** Memberships with `source: idp` come from your IdP's group mapping and can only be changed there; `remove-members` only removes manual memberships. `hasIdpSyncedMembers` on the list output tells you which groups have them.
* **A wildcard grant omits `_resourceId`.** A `resourceGrants[]` entry without `_resourceId` applies its capabilities across every MCP server on the account.
* **Membership and structural changes require `full` mode.** `add-members`, `remove-members`, `create`, `update`, `set`, and `delete` all change end-user access. `list` and `get` work in `read` mode. See [Profiles & regions](/cli/getting-started/profiles.md#permission-modes).

## Related

* [end-users](/cli/commands/end-users.md) — the members; `list` supplies the ashareIds these commands take.
* [roles](/cli/commands/roles.md) — the reusable grant sets a group bundles via `_roleIds`.
* [mcp-servers](/cli/commands/mcp-servers.md) — `assign-groups` replaces a group's grant for one server from the server side.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/groups.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.