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

# iclients

Shared OAuth2 credential stores (app registrations) that multiple connections can reference — rotate a client secret in one place instead of per connection.

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

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

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

***

## Subcommands

| Subcommand             | Purpose                                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| `list`                 | List all iClients.                                                                                          |
| `get <id>`             | Fetch one iClient (secrets are masked as `******`).                                                         |
| `create`               | Create an iClient from a JSON body (`--file <path>` or stdin).                                              |
| `update <id>`          | Full-replace PUT from a JSON body (`--file <path>` or stdin). Refuses masked placeholders unless `--force`. |
| `set <id> key=value …` | Edit whitelisted fields (e.g. `name`) via atomic `PATCH`. Credential fields cannot be set; use `update`.    |
| `delete <id>`          | Delete an iClient by ID.                                                                                    |
| `dependencies <id>`    | List resources that depend on this iClient (alias `used-by`).                                               |
| `audit <id>`           | Show the audit log (change history) for one iClient.                                                        |

> **`set` is limited on iClients.** Because iClients are credential-masked, `set` may only touch the PATCH-whitelisted fields (e.g. `name`, `disabled`). To change the OAuth client secret or other encrypted fields, use `update` with a hand-built payload that contains the actual secret, or `delete` + `create` to re-enter credentials from scratch. A GET, modify, PUT round-trip would otherwise write the masked placeholder back over the real value.

***

## `celigo iclients list`

List every iClient in the current account.

**Signature**

```bash
celigo iclients list
```

**Arguments**

None.

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md). Default table columns: `_id`, `name`, `lastModified`.

**Example**

```bash
celigo iclients list --format table
```

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

***

## `celigo iclients get <id>`

Fetch a single iClient by ID. Encrypted fields (e.g. `clientSecret`) are returned as `******`.

**Signature**

```bash
celigo iclients get <id>
```

**Arguments**

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

**Flags**

None beyond [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo iclients get 5f83a9b2c7d3e8f1a2b3c4d5
```

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

***

## `celigo iclients create`

Create an iClient from a JSON payload. Read the body from a file with `-f, --file` or pipe it on stdin.

**Signature**

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

**Arguments**

None.

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

**Request body**

Reads JSON on stdin (or from `--file`). See the `POST /v1/iClients` request schema in `dist/iclient.yml` for the full payload shape (`application`, `oauth2.clientId`, `oauth2.clientSecret`, `oauth2.authorizeURI`, `oauth2.tokenURI`, and provider-specific fields).

**Example**

```bash
celigo iclients create < salesforce-iclient.json
```

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

***

## `celigo iclients update <id>`

Full-replace an iClient with a JSON payload. Read the body from a file with `-f, --file` or pipe it on stdin. Refuses to submit a payload containing masked placeholders (all-asterisk strings) unless `--force` is passed.

> ⚠️ **`PUT` fully replaces the iClient.** Any omitted field is erased. Supply the real `clientSecret` in the body — submitting the masked `******` value (with `--force`) overwrites the stored secret.

**Signature**

```bash
celigo iclients update <id> --file <path>
celigo iclients update <id> [--force] < iclient.json     # or pipe on stdin
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | iClient 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. Without it, masked fields cause the command to abort with the list of offending paths. |

**Request body**

Reads JSON on stdin (or from `--file`). Payload must be the complete iClient object — `PUT` is a full replace. See `PUT /v1/iClients/{_id}` in `dist/iclient.yml`.

**Example**

```bash
celigo iclients get 5f83... --format json \
  | jq '.name = "Renamed" | .oauth2.clientSecret = "real-secret"' \
  | celigo iclients update 5f83...
```

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

***

## `celigo iclients set <id>`

Edit one or more fields on an iClient. Because iClients are credential-masked, only PATCH-whitelisted fields (e.g. `name`, `disabled`) can be set via an atomic `PATCH`; other fields must go through `update`. This avoids the GET → modify → PUT round-trip writing a masked `******` placeholder back over the real client secret.

**Signature**

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

**Arguments**

| Argument           | Type              | Required | Description                                                                                                                                              |
| ------------------ | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<id>`             | string            | Yes      | iClient ID.                                                                                                                                              |
| `[assignments...]` | `key=value` pairs | Yes      | At least one assignment. Values are auto-parsed (`disabled=false` → boolean, `debugUntil=null` → removes field). Dot and array-index notation supported. |

**Example**

```bash
celigo iclients set 5f83a9b2c7d3e8f1a2b3c4d5 name="Salesforce prod app"
```

**Corresponds to**: `PATCH /v1/iClients/{_id}`

***

## `celigo iclients delete <id>`

Delete an iClient. Prompts for confirmation unless `-y` is passed.

> ⚠️ **Deleting an iClient is destructive.** Connections that reference it via `_iClientId` lose their credential store and stop authenticating. Run `dependencies` first to confirm nothing uses it.

**Signature**

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

**Arguments**

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

**Flags**

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

**Example**

```bash
celigo iclients delete 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

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

***

## `celigo iclients dependencies <id>`

List the resources (typically connections) that depend on this iClient. Use it to check whether the iClient is safe to delete; an empty result means no dependents. Aliased as `used-by`.

**Signature**

```bash
celigo iclients dependencies <id>
celigo iclients used-by <id>
```

**Arguments**

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

**Example**

```bash
celigo iclients dependencies 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/iClients/{_id}/dependencies`

***

## `celigo iclients audit <id>`

Show the audit log (change history) for one iClient.

**Signature**

```bash
celigo iclients audit <id>
```

**Arguments**

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

**Example**

```bash
celigo iclients audit 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: `GET /v1/iClients/{_id}/audit`

***

## Gotchas

* **`set` only touches non-credential fields.** iClients hold OAuth client secrets, and the API masks those fields as `******` on every GET. So `set` is limited to PATCH-whitelisted fields (e.g. `name`, `disabled`) that are written via an atomic `PATCH`; it cannot change the client secret. To rotate a secret, use `update` with a hand-built payload that includes the real value, or `delete` + `create` to re-enter the credentials.
* **`update` refuses masked payloads by default.** Pipe `get | update` without replacing the masked fields and the command aborts, listing each offending path (e.g. `oauth2.clientSecret`). Fill them in with the real values (or `""` to clear) before re-running, or pass `--force` to submit the masked payload anyway — which will write `******` back to the server.
* **iClients are shared.** One iClient can back many connections via `_iClientId`. Rotating a secret on the iClient flows to every connection pointing at it.

## Related

* [connections](/cli/commands/connections.md) — OAuth connections reference an iClient via `_iClientId`.
* [workspace-users](/cli/commands/workspace-users.md) — the other half of the former `users-iclients` page.


---

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