> 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/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/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/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/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/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/roles) then [`PUT /v1/roles/{_id}`](https://developer.celigo.com/api/api-reference/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/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.


---

# 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/roles.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.