> 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/roles.md).

# roles

Manage end-user roles — named, reusable sets of MCP-server grants, assigned to groups (via `_roleIds`) or directly to end users. A grant names one MCP server, or omits `_resourceId` for a wildcard across all, plus a capability list. Standard CRUD only; the API defines no other operations.

**REST API**: [Roles](https://developer.celigo.com/api/api-reference/account-and-admin/roles)

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

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

***

## Subcommands

| Subcommand             | Purpose                                                                      |
| ---------------------- | ---------------------------------------------------------------------------- |
| `list`                 | List all roles.                                                              |
| `get <id>`             | Fetch one role by ID.                                                        |
| `create`               | Create a role 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 role.                                                               |

***

## `celigo roles list`

List all roles. 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 roles 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`, `lastModified`.

**Example**

```bash
celigo roles list --format table
```

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

***

## `celigo roles get <id>`

Fetch one role by ID, including its `resourceGrants`.

**Signature**

```bash
celigo roles get <id>
```

**Arguments**

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

**Example**

```bash
celigo roles get 6b2c3d4e5f6a7b8c9d0e1f2a
```

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

***

## `celigo roles create`

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

**Signature**

```bash
celigo roles create --file <path>
celigo roles create < role.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/roles` request schema: `name` (required, unique per account), optional `description`, and `resourceGrants[]`. Each grant is `{"resourceType": "mcpServer", "_resourceId": "<mcpServerId>", "capabilities": [...]}` — omit `_resourceId` for a wildcard across every MCP server. Capabilities: `tool:all`, `tool:<id>`, `api:all`, `api:<id>`, or `pset:<permissionSetId>`.

```json
{
  "name": "Read-only order tools",
  "description": "Order lookup tools on the sales MCP server",
  "resourceGrants": [
    {
      "resourceType": "mcpServer",
      "_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
      "capabilities": ["tool:62abc1234e5f6a7b8c9d0e1f", "pset:6c2d3e4f5a6b7c8d9e0f1a2b"]
    }
  ]
}
```

**Example**

```bash
celigo roles create --file ./order-tools-role.json
```

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

***

## `celigo roles update <id>`

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

> ⚠️ **`update` replaces the entire role.** `PUT` erases any field you omit — `description`, `resourceGrants`. `GET` the role first, edit it, then send the complete object back, or use `set` for targeted edits. A rename that collides with another role's name is rejected with `409 Conflict`, case-insensitively.

**Signature**

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

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Role 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 roles get 6b2c3d4e5f6a7b8c9d0e1f2a --format json \
  | jq '.resourceGrants[0].capabilities += ["api:64def1234e5f6a7b8c9d0e1f"]' \
  | celigo roles update 6b2c3d4e5f6a7b8c9d0e1f2a
```

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

***

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

Edit one or more fields on a role 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 roles set <id> key=value [key2=value2 ...]
```

**Arguments**

| Argument           | Type              | Required | Description                                                                                                              |
| ------------------ | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `<id>`             | string            | Yes      | Role ID.                                                                                                                 |
| `[assignments...]` | `key=value` pairs | Yes (≥1) | Field assignments, e.g. `description="Order tools"` or `resourceGrants[0].capabilities[1]=null`. Values are JSON-parsed. |

**Example**

```bash
celigo roles set 6b2c3d4e5f6a7b8c9d0e1f2a 'description=Order lookup tools (read-only)'
```

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

***

## `celigo roles delete <id>`

Delete a role by ID. Prompts for confirmation unless `-y` is passed. Groups and end users that held the role lose the grants it carried; their other roles and direct grants are untouched.

**Signature**

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

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo roles delete 6b2c3d4e5f6a7b8c9d0e1f2a -y
```

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

***

## Gotchas

* **Role names are unique per account, case-insensitively.** `create` and a rename via `update`/`set` are both rejected with `409 Conflict` on a duplicate — `Order Tools` and `order tools` collide.
* **`update` is a full PUT.** A body that omits `description` or `resourceGrants` erases them. Prefer `set` for single-field changes.
* **A wildcard grant omits `_resourceId`.** A `resourceGrants[]` entry without `_resourceId` applies its capabilities across every MCP server on the account.
* **`pset:` capabilities reference a capability set's `_id`.** Capability sets live embedded on the MCP server document as `permissionSets[]` — read the `_id` from [`mcp-servers get`](/cli/commands/mcp-servers.md). A PUT to the server that drops its `permissionSets` orphans every `pset:` grant pointing at one.
* **Structural changes require `full` mode.** `create`, `update`, `set`, and `delete` change what access the role conveys. `list` and `get` work in `read` mode. See [Profiles & regions](/cli/getting-started/profiles.md#permission-modes).

## Related

* [groups](/cli/commands/groups.md) — bundle roles for members via `_roleIds`.
* [end-users](/cli/commands/end-users.md) — the people roles are ultimately granted to; `effective-access` shows each grant's source.
* [mcp-servers](/cli/commands/mcp-servers.md) — the granted resources, and home of the `permissionSets[]` that `pset:` capabilities reference.