# uip df choice-sets

> Syntax and options for `uip df choice-sets` and `uip df choice-set-values`, which manage Data Fabric's enumerated value lists.

`uip df choice-sets` and `uip df choice-set-values` manage Data Fabric choice sets — the enumerated value lists referenced by `CHOICE_SET_SINGLE`/`CHOICE_SET_MULTIPLE` fields on an [entity](./uip-df-entities.md). `choice-sets` manages the set itself (its metadata and the list of allowed values); `choice-set-values` manages the individual values within a set.

## Synopsis

```
uip df choice-sets list [--folder-key <key> | --include-folders]
uip df choice-sets list-values <choice-set-id> [-l <n>] [-o <n> | --cursor <cursor>] [--folder-key <key>]
uip df choice-sets create <name> [--display-name <name>] [--description <text>] [--folder-key <key>]
uip df choice-sets update <choice-set-id> --display-name <name> --description <text> [--folder-key <key>]
uip df choice-sets delete <choice-set-id> -y --reason <text> [--folder-key <key>]

uip df choice-set-values create <choice-set-id> <name> [--display-name <name>] [--folder-key <key>]
uip df choice-set-values update <choice-set-id> <value-id> <display-name> [--folder-key <key>]
uip df choice-set-values delete <choice-set-id> --ids <id,id,...> -y --reason <text> [--folder-key <key>]
```

Every verb also accepts `--folder-key <key>` (a folder GUID, for a folder-scoped choice set).

## uip df choice-sets

### uip df choice-sets list

List choice sets. Defaults to tenant-level choice sets; `--folder-key` scopes to one folder, `--include-folders` includes every folder's choice sets alongside tenant-level ones.

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--folder-key` | key | — | Folder key (GUID) to scope the listing to a specific folder. Mutually exclusive with `--include-folders`. |
| — | `--include-folders` | flag | off | List tenant-level choice sets together with choice sets from every folder you can see. Mutually exclusive with `--folder-key`. |

#### Example

```bash
uip df choice-sets list
```

#### Data shape (--output json)

```json
{
  "Code": "ChoiceSetList",
  "Data": [
    {
      "id": "c1d2e3f4-0000-0000-0000-000000000001",
      "name": "ExpenseTypes",
      "displayName": "Expense Types",
      "description": "Categories of expenses",
      "folderId": "f1000000-0000-0000-0000-000000000001",
      "createdBy": "u1000000-0000-0000-0000-000000000001",
      "updatedBy": "u1000000-0000-0000-0000-000000000001",
      "createdTime": "2026-01-01T00:00:00Z",
      "updatedTime": "2026-01-02T00:00:00Z"
    }
  ]
}
```

`Data` rows are raw, camelCase SDK objects. Each row's `id` is the value to pass as `choiceSetId` on a `CHOICE_SET_SINGLE`/`CHOICE_SET_MULTIPLE` [entity field](./uip-df-entities.md#uip-df-entities-create), or to `list-values` below.

### uip df choice-sets list-values

List the values of a choice set. Supports cursor-based pagination.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<choice-set-id>` | yes | Choice set ID (UUID). |

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-l` | `--limit` | number | `50` | Number of values to return per page. |
| `-o` | `--offset` | number | — | Start from the page containing this record index (rounded down to a page boundary). Mutually exclusive with `--cursor`. |
| — | `--cursor` | cursor | — | Pagination cursor value from a previous response's `nextCursor.value`. |
| — | `--folder-key` | key | — | Folder key (GUID) of the folder containing the choice set, for folder-scoped choice sets. |

#### Example

```bash
uip df choice-sets list-values c1d2e3f4-0000-0000-0000-000000000001 --limit 2
```

#### Data shape (--output json)

```json
{
  "Code": "ChoiceSetValues",
  "Data": {
    "items": [
      { "id": "v1000000-0000-0000-0000-000000000001", "name": "travel", "displayName": "Travel", "numberId": 0 },
      { "id": "v1000000-0000-0000-0000-000000000002", "name": "meals", "displayName": "Meals", "numberId": 1 }
    ],
    "totalCount": 2,
    "hasNextPage": false
  }
}
```

`numberId` is the integer to pass when inserting or updating a [record](./uip-df-records.md) into a `CHOICE_SET_SINGLE` field — or in an array, for `CHOICE_SET_MULTIPLE`.

### uip df choice-sets create

Create a new choice set.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<name>` | yes | Choice set name (starts with a letter; letters, numbers, and underscores only). |

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--display-name` | text | — | Human-readable display name. |
| — | `--description` | text | — | Choice set description. |
| — | `--folder-key` | uuid | — | Folder to place the choice set in. Defaults to the tenant-level folder. |

#### Example

```bash
uip df choice-sets create ExpenseTypes \
    --display-name "Expense Types" \
    --description "Categories of expenses"
```

#### Data shape (--output json)

```json
{
  "Code": "ChoiceSetCreated",
  "Data": { "ID": "c1d2e3f4-0000-0000-0000-000000000001" }
}
```

The returned `ID` is used as `choiceSetId` on `CHOICE_SET_SINGLE`/`CHOICE_SET_MULTIPLE` entity fields. Add values to it with `choice-set-values create`, below.

### uip df choice-sets update

Update a choice set's display name and description.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<choice-set-id>` | yes | Choice set ID (UUID). |

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--display-name` | text | — | **Required.** New display name. |
| — | `--description` | text | — | **Required.** New description. |
| — | `--folder-key` | key | — | Folder key (GUID) of the folder containing the choice set, for folder-scoped choice sets. |

:::important
`--display-name` and `--description` must both be passed together — there is no partial update. The server rejects a description-only update with `DisplayName is required.`, and rejects a display-name-only update with an Internal Server Error. To change just one field, first read the other's current value with `choice-sets list`, then resend both.
:::

#### Example

```bash
uip df choice-sets update c1d2e3f4-0000-0000-0000-000000000001 \
    --display-name "Expense Categories" \
    --description "Categories of expenses"
```

#### Data shape (--output json)

```json
{
  "Code": "ChoiceSetUpdated",
  "Data": { "ID": "c1d2e3f4-0000-0000-0000-000000000001" }
}
```

### uip df choice-sets delete

Delete a choice set outright. This is **irreversible**.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<choice-set-id>` | yes | Choice set ID (UUID). |

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-y` | `--yes` | flag | — | **Required.** Acknowledges this is an irreversible operation. |
| — | `--reason` | text | — | **Required.** Reason for the deletion — echoed back in the response so the caller can log it. |
| — | `--folder-key` | key | — | Folder key (GUID) of the folder containing the choice set, for folder-scoped choice sets. |

#### Example

```bash
uip df choice-sets delete c1d2e3f4-0000-0000-0000-000000000001 \
    --yes --reason "no longer used"
```

#### Data shape (--output json)

```json
{
  "Code": "ChoiceSetDeleted",
  "Data": {
    "ID": "c1d2e3f4-0000-0000-0000-000000000001",
    "Reason": "no longer used"
  }
}
```

## uip df choice-set-values

### uip df choice-set-values create

Add a value to a choice set.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<choice-set-id>` | yes | Choice set ID (UUID). |
| `<name>` | yes | Value name (starts with a letter; letters and numbers only). |

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--display-name` | text | — | Human-readable display name. |
| — | `--folder-key` | key | — | Folder key (GUID) of the folder containing the choice set. Required when the choice set is folder-scoped. |

#### Example

```bash
uip df choice-set-values create c1d2e3f4-0000-0000-0000-000000000001 travel \
    --display-name "Travel"
```

#### Data shape (--output json)

```json
{
  "Code": "ChoiceSetValueCreated",
  "Data": {
    "id": "v1000000-0000-0000-0000-000000000001",
    "name": "travel",
    "displayName": "Travel",
    "numberId": 0
  }
}
```

The returned `numberId` is the integer to pass when inserting or updating records into a `CHOICE_SET_SINGLE` field (or in an array, for `CHOICE_SET_MULTIPLE`).

### uip df choice-set-values update

Update the display name of an existing choice set value.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<choice-set-id>` | yes | Choice set ID (UUID). |
| `<value-id>` | yes | Choice set value ID (UUID). Find it with `choice-sets list-values <choice-set-id>`. |
| `<display-name>` | yes | New display name for the value. |

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--folder-key` | key | — | Folder key (GUID) of the folder containing the choice set. Required when the choice set is folder-scoped. |

#### Example

```bash
uip df choice-set-values update c1d2e3f4-0000-0000-0000-000000000001 \
    v1000000-0000-0000-0000-000000000001 "Business Travel"
```

#### Data shape (--output json)

```json
{
  "Code": "ChoiceSetValueUpdated",
  "Data": {
    "id": "v1000000-0000-0000-0000-000000000001",
    "name": "travel",
    "displayName": "Business Travel",
    "numberId": 0
  }
}
```

### uip df choice-set-values delete

Delete one or more values from a choice set. This is **irreversible**.

#### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<choice-set-id>` | yes | Choice set ID (UUID). |

#### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--ids` | id,id,... | — | **Required.** Comma-separated list of value IDs to delete. |
| `-y` | `--yes` | flag | — | **Required.** Acknowledges this is an irreversible operation. |
| — | `--reason` | text | — | **Required.** Reason for the deletion — echoed back in the response so the caller can log it. |
| — | `--folder-key` | key | — | Folder key (GUID) of the folder containing the choice set. Required when the choice set is folder-scoped. |

#### Example

```bash
uip df choice-set-values delete c1d2e3f4-0000-0000-0000-000000000001 \
    --ids v1000000-0000-0000-0000-000000000001,v1000000-0000-0000-0000-000000000002 \
    --yes --reason "deprecated categories"
```

#### Data shape (--output json)

```json
{
  "Code": "ChoiceSetValuesDeleted",
  "Data": {
    "ChoiceSetId": "c1d2e3f4-0000-0000-0000-000000000001",
    "DeletedIds": [
      "v1000000-0000-0000-0000-000000000001",
      "v1000000-0000-0000-0000-000000000002"
    ],
    "Reason": "deprecated categories"
  }
}
```

## Related

- [`uip df entities`](./uip-df-entities.md) — `CHOICE_SET_SINGLE`/`CHOICE_SET_MULTIPLE` fields reference a choice set by `choiceSetId`.
- [`uip df records`](./uip-df-records.md) — insert/update record values using a choice value's `numberId`.

## See also

- [Data Fabric tool overview](./uip-df.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)