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

celigo roles <subcommand> [args] [flags]

Supports all global flags.

---

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

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.

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

Example

celigo roles list --format table

Corresponds to: GET /v1/roles

---

celigo roles get <id>

Fetch one role by ID, including its resourceGrants.

Signature

celigo roles get <id>

Arguments

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

Example

celigo roles get 6b2c3d4e5f6a7b8c9d0e1f2a

Corresponds to: GET /v1/roles/{_id}

---

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

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>.

{
  "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

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

Corresponds to: POST /v1/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

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

celigo roles get 6b2c3d4e5f6a7b8c9d0e1f2a --format json \
  | jq '.resourceGrants[0].capabilities += ["api:64def1234e5f6a7b8c9d0e1f"]' \
  | celigo roles update 6b2c3d4e5f6a7b8c9d0e1f2a

Corresponds to: PUT /v1/roles/{_id}

---

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

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

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

Corresponds to: GET /v1/roles/{_id} then PUT /v1/roles/{_id}

---

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

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

celigo roles delete 6b2c3d4e5f6a7b8c9d0e1f2a -y

Corresponds to: DELETE /v1/roles/{_id}

---

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. 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.

Related

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