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

# workspace-users

Manage the humans on your Celigo account — invite teammates, adjust their access levels, and remove access when people move on. Workspace users are your team's account collaborators (the `/v1/ashares` access records) with access levels like `administrator`, `manage`, and `monitor`. External people who only sign in to use your MCP servers are a different resource — see [end-users](/cli/commands/end-users.md).

> **The group was renamed in celigo-cli 2026.8.7.** It was previously `users`; with external end users joining the CLI, the unqualified name stopped saying which kind of user it manages. `users` remains a working hidden alias — `celigo users list` and `celigo workspace-users list` are the same command, and aliased invocations hit the same permission gates. Only the primary name in `--help` and the documentation changed.

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

```
celigo workspace-users <subcommand> [args] [flags]
```

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

***

## Subcommands

| Subcommand             | Purpose                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `list`                 | List every workspace user (ashare) on the account.                                    |
| `get <id>`             | Fetch one workspace user by ashare ID.                                                |
| `update <id>`          | Replace a user record from a JSON body (`--file <path>` or stdin); destructive `PUT`. |
| `set <id> key=value …` | Safe field edit via PATCH (whitelisted fields) or GET → modify → PUT.                 |
| `delete <id>`          | Remove a workspace user from the account.                                             |
| `invite`               | Invite one or more users by email (no `create` — use `invite`).                       |
| `reinvite <id>`        | Re-send an invite to a user who dismissed it.                                         |
| `disable <userId>`     | Disable a user's account access (non-destructive).                                    |
| `enable <userId>`      | Re-enable a disabled user's account access.                                           |

> There is no `celigo workspace-users create`. Users are added by emailing an invitation; use `invite`. To temporarily revoke access without losing history, use `disable` (and `enable` to restore it); use `delete` to remove access entirely.

***

## `celigo workspace-users list`

List all ashares on the account — i.e. every person with workspace access, plus any pending invites.

**Signature**

```bash
celigo workspace-users list
```

**Flags**

| Flag                 | Type   | Default | Description                                    |
| -------------------- | ------ | ------- | ---------------------------------------------- |
| `--integration <id>` | string | —       | List only users belonging to this integration. |

Plus the [global flags](/cli/getting-started/global-flags.md). The default table columns are `_id`, `accessLevel`, `accepted`, `lastModified`.

**Example**

```bash
# Find every account administrator
celigo workspace-users list --format json --jq '.[] | select(.accessLevel == "administrator") | .sharedWithUser.email'
```

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

***

## `celigo workspace-users get <id>`

Fetch a single workspace user (ashare) record.

**Signature**

```bash
celigo workspace-users get <id>
```

**Arguments**

| Argument | Type   | Required | Description                                                                      |
| -------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `<id>`   | string | Yes      | Ashare ID (the `_id` from `workspace-users list`, not the underlying `_userId`). |

**Example**

```bash
celigo workspace-users get 5f83a9b2c7d3e8f1a2b3c4d5
```

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

***

## `celigo workspace-users update <id>`

Full replace of a user record from a JSON body. Read the body from a file with `-f, --file` or pipe it on stdin. This is a destructive `PUT` — every omitted field is erased. Prefer `set` for targeted edits.

> ⚠️ **`update` replaces the entire user record.** `PUT` erases any field you omit — `accessLevel`, `integrationAccessLevel[]`, MFA and SSO flags. `GET` the record first, edit it, then send the complete object back, or use `set` for targeted edits.

**Signature**

```bash
celigo workspace-users update <id> --file <path>
celigo workspace-users update <id> < body.json     # or pipe on stdin
```

**Arguments**

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

**Flags**

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

**Request body**

Reads JSON on stdin (or from `--file`). See the `PUT /v1/ashares/{_id}` request schema for the full payload shape (`accessLevel`, `integrationAccessLevel[]`, `accountSSORequired`, `accountMFARequired`, `allowAccessToAPIM`, `allowToEditRetryData`, `disabled`).

**Example**

```bash
celigo workspace-users get 5f83a9b2c7d3e8f1a2b3c4d5 --format json \
  | jq '.accessLevel = "manage"' \
  | celigo workspace-users update 5f83a9b2c7d3e8f1a2b3c4d5
```

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

***

## `celigo workspace-users set <id> [assignments...]`

Edit one or more fields on a workspace user. Whitelisted fields (e.g. `name`, `disabled`) are applied via an atomic `PATCH`; other fields go through GET → modify → PUT. Safer than `update` because omitted fields are preserved.

**Signature**

```bash
celigo workspace-users set <id> key=value [key2=value2 ...]
```

**Arguments**

| Argument           | Type              | Required | Description                                                                                                                                                                                                                      |
| ------------------ | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<id>`             | string            | Yes      | Ashare ID.                                                                                                                                                                                                                       |
| `[assignments...]` | `key=value` pairs | Yes      | At least one assignment. Values are auto-parsed (`accountMFARequired=true` → boolean, `allowToEditRetryData=null` → removes field). Dot and array-index notation supported. Use `key=file://<path>` to load a value from a file. |

**Example**

```bash
# Promote to administrator and clear any integration-scoped access
celigo workspace-users set 5f83a9b2c7d3e8f1a2b3c4d5 \
  accessLevel=administrator \
  integrationAccessLevel=null
```

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

***

## `celigo workspace-users delete <id>`

Remove a workspace user from the account. Prompts for confirmation unless `--yes` is passed.

> ⚠️ **Deleting a user removes their access record and cannot be undone.** To revoke access while keeping the user's history, use `disable` instead.

**Signature**

```bash
celigo workspace-users delete <id> [-y]
```

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo workspace-users delete 5f83a9b2c7d3e8f1a2b3c4d5 --yes
```

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

***

## `celigo workspace-users invite`

Invite one or more users to the account by email. Use this instead of `create` — users always enter the account through an invitation flow. `--email` is repeatable; the access settings apply uniformly to every email in the batch.

**Signature**

```bash
celigo workspace-users invite --email <email> [--email <email> ...] [flags]
```

**Flags**

| Flag                         | Type                                 | Default | Description                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------- | ------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--email <emails...>`        | string                               | —       | **Required.** Email address(es) to invite. Repeatable; pass once per invitee.                                                                                                                                                                                                                                                                                           |
| `--access-level <level>`     | `monitor \| manage \| administrator` | —       | Account-wide access level. Omit to create integration-only (custom) access (see `--integration`).                                                                                                                                                                                                                                                                       |
| `--integration <mapping...>` | `<integrationId>=<monitor\|manage>`  | —       | Per-integration access grant. Repeatable. Combine with `--access-level monitor` for elevated per-integration access, or omit `--access-level` entirely for integration-only access.                                                                                                                                                                                     |
| `--mcp-server <mapping...>`  | `<mcpServerId>=<scope[,scope...]>`   | —       | MCP server access grant (e.g. `mcp1=mcp:read,mcp:write`). Repeatable. **Deprecated upstream** — the API still accepts and returns `mcpServerAccessLevel`, but do not build on it: for new work use [`end-users invite --grant`](/cli/commands/end-users.md#celigo-end-users-invite) and [`mcp-servers assign-end-users`/`assign-groups`](/cli/commands/mcp-servers.md). |
| `--force-mfa`                | boolean                              | `false` | Require MFA for this user in this account (sets `accountMFARequired: true`).                                                                                                                                                                                                                                                                                            |
| `--force-sso`                | boolean                              | `false` | Require SSO for this user (account must have SSO configured). Sets `accountSSORequired: true`.                                                                                                                                                                                                                                                                          |
| `--allow-edit-retry-data`    | boolean                              | `false` | Allow the user to edit retry data when troubleshooting flow errors. Only meaningful when the user's effective access level is `monitor`. Sets `allowToEditRetryData: true`.                                                                                                                                                                                             |

**Request body**

The flags map onto the `POST /v1/invite/multiple` request schema: `email`, `accessLevel`, `integrationAccessLevel[]`, `mcpServerAccessLevel[]`, `accountMFARequired`, `accountSSORequired`, `allowToEditRetryData`. Access settings apply uniformly to every email in the batch.

**Examples**

```bash
# Account-wide monitor with MFA enforced (two invitees)
celigo workspace-users invite --email a@example.com --email c@example.com \
  --access-level monitor --force-mfa

# Integration-only access to two integrations
celigo workspace-users invite --email a@example.com \
  --integration 5f83a9b2c7d3e8f1a2b3c4d5=manage \
  --integration 5fa1e2d3c4b5a69788b9c0d1=monitor \
  --force-mfa --allow-edit-retry-data
```

**Corresponds to**: `POST /v1/invite/multiple` (operationId: `inviteUsers`)

***

## `celigo workspace-users reinvite <id>`

Re-send an invite to a user who dismissed theirs. Only works on users with `dismissed: true`; they return to a pending state afterward.

**Signature**

```bash
celigo workspace-users reinvite <id>
```

**Arguments**

| Argument | Type   | Required | Description                                                        |
| -------- | ------ | -------- | ------------------------------------------------------------------ |
| `<id>`   | string | Yes      | The user's access-record (ashare) id, from `workspace-users list`. |

**Example**

```bash
celigo workspace-users reinvite 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `PUT /v1/ashares/{_id}/reinvite` (operationId: `reinviteUser`)

***

## `celigo workspace-users disable <userId>`

Disable a user's account access without removing them; a non-destructive change that preserves history. No-op if the user is already disabled. Only works on accepted users. Prompts for confirmation unless `-y` is passed.

> ⚠️ **Disabling a user revokes their access immediately.** The user cannot sign in until you re-enable them with `celigo workspace-users enable <userId>`. Their record and history are preserved.

**Signature**

```bash
celigo workspace-users disable <userId> [-y]
```

**Arguments**

| Argument   | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `<userId>` | string | Yes      | Ashare ID.  |

**Flags**

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

**Example**

```bash
celigo workspace-users disable 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: `PUT /v1/ashares/{_id}/disable` (operationId: `toggleUserDisabled`)

***

## `celigo workspace-users enable <userId>`

Re-enable a disabled user's account access. No-op if the user is already enabled. The non-destructive counterpart to `disable`.

**Signature**

```bash
celigo workspace-users enable <userId>
```

**Arguments**

| Argument   | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `<userId>` | string | Yes      | Ashare ID.  |

**Example**

```bash
celigo workspace-users enable 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `PUT /v1/ashares/{_id}/disable` (operationId: `toggleUserDisabled`)

***

## Gotchas

* **Workspace users vs end users.** This group manages account collaborators — people who sign in to integrator.io and hold an access level. External people who only authenticate through MCP OAuth to use your MCP servers are [end-users](/cli/commands/end-users.md), a separate resource with its own commands. Despite the shared word, the two do not overlap.
* **Access-level semantics** (see user.yml schema for the definitive rules):
  * `administrator` — full account administration; can invite/manage users and edit every resource. Cannot transfer ownership.
  * `manage` — can edit every integration and resource, but cannot edit account settings or invite users.
  * `monitor` — read-only plus run/retry/resolve on flows. Cannot modify integrations, flows, connections, or account settings.
  * *Integration-only* — omit `accessLevel` entirely and populate `integrationAccessLevel[]`. The user sees only the integrations you list.
* **`accessLevel` vs `integrationAccessLevel` strategy:**
  * Full account access → set `accessLevel` to `manage` or `administrator`; leave `integrationAccessLevel` empty.
  * Account-wide monitoring + selective management → `accessLevel: monitor` plus per-integration `manage` entries.
  * Integration-only access → omit `accessLevel`; list the integrations in `integrationAccessLevel`.
* **`--mcp-server` on `invite` is deprecated upstream.** The API still accepts and returns `mcpServerAccessLevel`, but new work should grant MCP access through [end-user grants](/cli/commands/end-users.md) (`end-users invite --grant`, `mcp-servers assign-end-users`/`assign-groups`) instead.
* **`allowToEditRetryData` only matters at monitor level.** All monitors can view and retry errant records, but editing the retry payload requires this flag. It is silently ignored for `manage`/`administrator`.
* **`--force-sso` requires the account to have SSO configured.** The invite will be accepted by the API but the user cannot sign in until SSO is live.
* **Ashare ID ≠ user ID.** The `_id` from `workspace-users list` is the ashare (user-in-account) ID; the underlying user's own ID lives at `sharedWithUser._id`. All `/v1/ashares/{_id}` endpoints take the ashare ID.
* **`PUT` is a full replace.** Use `set` or round-trip through `get | jq | update` rather than hand-writing an update body, or you will erase `integrationAccessLevel`, MFA flags, etc.
* **`disable` vs `delete`.** `disable` (and `enable` to restore) is the non-destructive option (`PUT /v1/ashares/{_id}/disable`); it preserves the user's record and history. `delete` removes the ashare entirely. Reach for `disable` when you may need to restore access later. `disable` only works on users who have accepted their invite.
* **`reinvite` only works on dismissed invites.** It targets users with `dismissed: true` and returns them to a pending state. It is a no-op for users who already accepted.

## Related

* [end-users](/cli/commands/end-users.md) — external MCP users; the resource the old `--mcp-server` invite flag is deprecated in favor of.
* [iclients](/cli/commands/iclients.md) — shared OAuth credential stores (kept separate from human users).
* [audit](/cli/commands/audit.md) — track permission and membership changes over time.


---

# 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/workspace-users.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.