# uip df entities

> Syntax and options for `uip df entities`, which browses and mutates Data Fabric entity schemas.

`uip df entities` browses and mutates Data Fabric entity schemas. An entity is a typed data model — a row shape with named fields and types. The verbs cover discovery (`list`, `get`) and authoring (`create`, `update`); record-level operations live on [`uip df records`](./uip-df-records.md). Field removal is intentionally not supported through `update`.

## Synopsis

```
uip df entities <verb> [options]
```

## Verbs

| Verb | Purpose |
|---|---|
| `list` | List all entities in the tenant; optionally exclude federated ones. |
| `get` | Return the schema (including all fields) of a single entity. |
| `create` | Create a new entity from a JSON definition. |
| `update` | Update an entity's metadata or schema (add or update fields; `removeFields` is rejected). |

## uip df entities list

List all entities in the tenant.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--native-only` | flag | off | Show only native entities; exclude federated entities backed by an external connector connection. |

### Examples

```bash
uip df entities list

uip df entities list --native-only

uip df entities list \
    --output-filter 'Data[].{name:Name, id:ID, fields:FieldCount}'
```

### Data shape (--output json)

```json
{
  "Code": "EntityList",
  "Data": [
    {
      "Name": "Invoice",
      "DisplayName": "Invoice",
      "ID": "a1b2c3d4-0000-0000-0000-000000000001",
      "Type": "Standard",
      "Source": "Native",
      "Description": "Invoice records",
      "FieldCount": 8
    }
  ]
}
```

Federated entities report `Source` as `Federated` or `Federated (<connector>)`.

## uip df entities get

Return the schema of a single entity, including all fields.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<id>` | yes | Entity ID (UUID). Find it with `entities list`. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip df entities get a1b2c3d4-0000-0000-0000-000000000001

# Just the field list
uip df entities get a1b2c3d4-0000-0000-0000-000000000001 \
    --output-filter 'Data.Fields[].{name:Name, type:Type}'
```

### Data shape (--output json)

```json
{
  "Code": "EntitySchema",
  "Data": {
    "Name": "Invoice",
    "DisplayName": "Invoice",
    "ID": "a1b2c3d4-0000-0000-0000-000000000001",
    "Type": "Standard",
    "Description": "Invoice records",
    "Fields": [
      {
        "ID": "f1000000-0000-0000-0000-000000000001",
        "Name": "id",
        "DisplayName": "ID",
        "Type": "Guid",
        "Required": true,
        "PrimaryKey": true,
        "System": true
      }
    ]
  }
}
```

## uip df entities create

Create a new entity. The entity name must start with a letter and contain only letters, numbers, and underscores. Pass the definition either inline (`--body`) or from a file (`--file`); the two are mutually exclusive.

### Arguments

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

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| `-f` | `--file` | path | — | Path to JSON file with the entity definition (`fields` array required). |
| — | `--body` | JSON | — | Inline JSON entity definition. |

Entity definition object:

```json
{
  "displayName": "Invoice",
  "description": "Invoice records",
  "isRbacEnabled": false,
  "fields": [
    { "fieldName": "title", "type": "STRING" }
  ]
}
```

Each field must include `fieldName` as a string. Valid `type` values are taken from the SDK's `EntityFieldDataType` enum (for example, `STRING`, `DECIMAL`, `GUID`, `BOOLEAN`, `DATE`, `DATETIME`). Invalid types fail with `ValidationError` listing the allowed set.

### Examples

```bash
uip df entities create Invoice --file ./invoice.entity.json

uip df entities create Invoice \
    --body '{"displayName":"Invoice","fields":[{"fieldName":"amount","type":"DECIMAL"}]}'
```

### Data shape (--output json)

```json
{
  "Code": "EntityCreated",
  "Data": { "ID": "a1b2c3d4-0000-0000-0000-000000000001" }
}
```

## uip df entities update

Update an entity's metadata or schema. The body accepts `addFields`, `updateFields`, `displayName`, `description`, and `isRbacEnabled`. `removeFields` is intentionally rejected — field removal is not supported. Each `addFields` entry requires `fieldName`; each `updateFields` entry requires `id` (discover field IDs with `entities get`).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<id>` | yes | Entity ID (UUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| `-f` | `--file` | path | — | Path to JSON file with update options. |
| — | `--body` | JSON | — | Inline JSON update options. |

### Examples

```bash
# Add a field
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"addFields":[{"fieldName":"status","type":"STRING"}]}'

# Rename an existing field
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"updateFields":[{"id":"f1000000-0000-0000-0000-000000000002","displayName":"Total"}]}'
```

### Data shape (--output json)

```json
{
  "Code": "EntityUpdated",
  "Data": { "ID": "a1b2c3d4-0000-0000-0000-000000000001" }
}
```

## Related

- [`uip df records`](./uip-df-records.md) — manage the rows held by these entities.
- [`uip df files`](./uip-df-files.md) — file attachments on records.
- [`uip vss generate`](./uip-vss-generate.md) — generate TypeScript types from a Data Fabric schema export.

## See also

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