# uip tm customfield

> Syntax and options for `uip tm customfield`, which manages custom field definitions, display labels, and allowed values on a Test Manager tenant.

`uip tm customfield` manages custom field definitions on a Test Manager tenant. Custom fields extend test case and requirement entities with project-specific metadata. This command group has three sub-groups:

- `customfield` — manage the field definition itself (list, get, create, update, delete)
- `customfield label` — manage the label assignments applied to objects
- `customfield value` — manage the allowed values for a field

:::important
The primary identifier for field definitions is `--field-id`. Label and value commands scope by `--object-type` combined with `--object-id`, `--label-id`, or `--value-id`. The flag `--customfield-id` does not exist in v1.196.
:::

## Synopsis

```text
# Field definitions
uip tm customfield list --project-key <key> [--object-types <types...>] [--data-types <types...>] [--name <name>] [--filter <text>] [--sort-by <expr>] [--limit <n>] [--offset <n>]
uip tm customfield get --object-type <type> (--field-id <uuid> | --name <name>)
uip tm customfield create --project-key <key> --name <name> --object-type <type> --data-type <type> [--scope-list <list>] [--description <text>] [--default-value <value>] [--value-hints <hints>]
uip tm customfield update --object-type <type> (--field-id <uuid> | --name <name>) [--rename-to <name>] [--description <text>] [--default-value <value>] [--value-hints <hints>] [--scope-list <list>]
uip tm customfield delete --object-type <type> (--field-ids <uuid...> | --name <name>) [-y]

# Labels
uip tm customfield label get --object-type <type> --label-id <uuid>
uip tm customfield label list --object-type <type> [--object-id <uuid>] [--limit <n>] [--offset <n>]
uip tm customfield label create --object-type <type> --object-id <uuid> --values <json>
uip tm customfield label add --object-type <type> --custom-field-name <name> --object-ids <uuid...> --values <values...>
uip tm customfield label remove --object-type <type> --custom-field-name <name> --object-ids <uuid...> (--values <values...> | --remove-all-values)

# Values
uip tm customfield value list --object-type <type> [--object-id <uuid>] [--limit <n>] [--offset <n>]
uip tm customfield value get --object-type <type> (--value-id <uuid> | --name <name> --object-id <uuid>)
uip tm customfield value create --object-type <type> --name <name> --object-id <uuid> --data-type <type> --value <value>
uip tm customfield value update --object-type <type> (--value-id <uuid> | --name <name> --object-id <uuid>) --value <value> [--clear]
uip tm customfield value delete --object-type <type> (--value-id <uuid> | --name <name> --object-id <uuid>) [-y]
```

All verbs honor the [global options](./global-options.md) and the standard [exit codes](./exit-codes.md). Every verb accepts `-t, --tenant <name>` and `--log-level <level>` (default `Information`).

---

## Field definition commands

### uip tm customfield list

List custom field definitions in a project. `--project-key` is **required**.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-types <types...>` — space-separated object types to filter by.
- `--data-types <types...>` — space-separated data types to filter by.
- `--name <name>` — filter by exact field name.
- `--filter <text>` — free-text search.
- `--sort-by <expr>` — sort expression.
- `--limit <n>` — page size. Defaults to `50`.
- `--offset <n>` — results to skip. Defaults to `0`.

#### Example

```bash
uip tm customfield list \
  --project-key DEMO \
  --object-types TestCase
```

#### Data shape

```json
{
  "Code": "CustomFieldList",
  "Data": [
    {
      "FieldId": "c1b2c3d4-0000-0000-0000-000000000001",
      "Name": "Priority",
      "ObjectType": "TestCase",
      "DataType": "String"
    }
  ]
}
```

---

### uip tm customfield get

Get a single custom field definition.

#### Options

- `--object-type <type>` *(required)* — object type the field belongs to.
- `--field-id <uuid>` — field UUID. Mutually exclusive with `--name`.
- `--name <name>` — field name. Mutually exclusive with `--field-id`.

#### Example

```bash
uip tm customfield get \
  --object-type TestCase \
  --field-id c1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldGet",
  "Data": {
    "FieldId": "c1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Priority",
    "ObjectType": "TestCase",
    "DataType": "String"
  }
}
```

---

### uip tm customfield create

Create a new custom field definition.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--name <name>` *(required)* — field name.
- `--object-type <type>` *(required)* — object type to attach the field to (for example, `TestCase`, `TestSet`).
- `--data-type <type>` *(required)* — data type of the field (for example, `String`, `Integer`, `Boolean`).
- `--scope-list <list>` — scope restrictions for the field.
- `--description <text>` — field description.
- `--default-value <value>` — default value for new objects.
- `--value-hints <hints>` — allowed value hints or enumeration for the field.

#### Example

```bash
uip tm customfield create \
  --project-key DEMO \
  --name "Priority" \
  --object-type TestCase \
  --data-type String \
  --value-hints "Low,Medium,High"
```

#### Data shape

```json
{
  "Code": "CustomFieldCreate",
  "Data": {
    "FieldId": "c1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Priority",
    "ObjectType": "TestCase",
    "DataType": "String"
  }
}
```

---

### uip tm customfield update

Update an existing custom field definition.

#### Options

- `--object-type <type>` *(required)* — object type the field belongs to.
- `--field-id <uuid>` — field UUID. Mutually exclusive with `--name`.
- `--name <name>` — field name (for lookup). Mutually exclusive with `--field-id`.
- `--rename-to <name>` — new name for the field.
- `--description <text>` — new description.
- `--default-value <value>` — new default value.
- `--value-hints <hints>` — new allowed value hints.
- `--scope-list <list>` — new scope restrictions.

#### Example

```bash
uip tm customfield update \
  --object-type TestCase \
  --field-id c1b2c3d4-0000-0000-0000-000000000001 \
  --rename-to "Severity"
```

#### Data shape

```json
{
  "Code": "CustomFieldUpdate",
  "Data": {
    "FieldId": "c1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Severity",
    "Result": "Updated"
  }
}
```

---

### uip tm customfield delete

Delete one or more custom field definitions.

#### Options

- `--object-type <type>` *(required)* — object type the fields belong to.
- `--field-ids <uuid...>` — space-separated field UUIDs to delete. Mutually exclusive with `--name`.
- `--name <name>` — field name to delete. Mutually exclusive with `--field-ids`.
- `-y, --yes` — skip the confirmation prompt.

#### Example

```bash
uip tm customfield delete \
  --object-type TestCase \
  --field-ids c1b2c3d4-0000-0000-0000-000000000001 \
  --yes
```

#### Data shape

```json
{
  "Code": "CustomFieldDelete",
  "Data": {
    "FieldId": "c1b2c3d4-0000-0000-0000-000000000001",
    "Result": "Deleted"
  }
}
```

---

## Label commands

### uip tm customfield label get

Get a single label assignment by its UUID.

#### Options

- `--object-type <type>` *(required)* — object type the label belongs to.
- `--label-id <uuid>` *(required)* — UUID of the label assignment (not the label name).

#### Example

```bash
uip tm customfield label get \
  --object-type TestCase \
  --label-id l1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelGet",
  "Data": {
    "LabelId": "l1b2c3d4-0000-0000-0000-000000000001",
    "ObjectType": "TestCase",
    "Label": "Priority"
  }
}
```

---

### uip tm customfield label list

List label assignments for an object type, optionally narrowed to a specific object.

#### Options

- `--object-type <type>` *(required)* — object type to list labels for.
- `--object-id <uuid>` — filter to a specific object UUID.
- `--limit <n>` — page size. Defaults to `50`.
- `--offset <n>` — results to skip. Defaults to `0`.

#### Example

```bash
uip tm customfield label list \
  --object-type TestCase \
  --object-id a1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelList",
  "Data": [
    {
      "LabelId": "l1b2c3d4-0000-0000-0000-000000000001",
      "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
      "Label": "Priority"
    }
  ]
}
```

---

### uip tm customfield label create

Create a new label on an object.

#### Options

- `--object-type <type>` *(required)* — object type to attach the label to.
- `--object-id <uuid>` *(required)* — UUID of the object to label.
- `--values <json>` *(required)* — JSON array of label values to apply.

#### Example

```bash
uip tm customfield label create \
  --object-type TestCase \
  --object-id a1b2c3d4-0000-0000-0000-000000000001 \
  --values '[{"name":"Priority","value":"High"}]'
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelCreate",
  "Data": {
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Result": "Created"
  }
}
```

---

### uip tm customfield label add

Add label values to one or more objects for a named custom field.

#### Options

- `--object-type <type>` *(required)* — object type.
- `--custom-field-name <name>` *(required)* — name of the custom field.
- `--object-ids <uuid...>` *(required)* — space-separated object UUIDs to apply the label to.
- `--values <values...>` *(required)* — space-separated label values to add.

#### Example

```bash
uip tm customfield label add \
  --object-type TestCase \
  --custom-field-name Priority \
  --object-ids a1b2c3d4-0000-0000-0000-000000000001 \
  --values High
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelAdd",
  "Data": {
    "Result": "Added"
  }
}
```

---

### uip tm customfield label remove

Remove label values from one or more objects for a named custom field.

#### Options

- `--object-type <type>` *(required)* — object type.
- `--custom-field-name <name>` *(required)* — name of the custom field.
- `--object-ids <uuid...>` *(required)* — space-separated object UUIDs.
- `--values <values...>` — space-separated label values to remove.
- `--remove-all-values` — remove all label values for this field from the specified objects. Mutually exclusive with `--values`.

#### Example

```bash
uip tm customfield label remove \
  --object-type TestCase \
  --custom-field-name Priority \
  --object-ids a1b2c3d4-0000-0000-0000-000000000001 \
  --values High
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelRemove",
  "Data": {
    "Result": "Removed"
  }
}
```

---

## Value commands

### uip tm customfield value list

List custom field values for an object type, optionally narrowed to a specific object.

#### Options

- `--object-type <type>` *(required)* — object type.
- `--object-id <uuid>` — filter to a specific object UUID.
- `--limit <n>` — page size. Defaults to `50`.
- `--offset <n>` — results to skip. Defaults to `0`.

#### Example

```bash
uip tm customfield value list \
  --object-type TestCase \
  --object-id a1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldValueList",
  "Data": [
    {
      "ValueId": "v1b2c3d4-0000-0000-0000-000000000001",
      "Name": "Priority",
      "Value": "High"
    }
  ]
}
```

---

### uip tm customfield value get

Get a single custom field value.

#### Options

- `--object-type <type>` *(required)* — object type.
- `--value-id <uuid>` — value UUID. Mutually exclusive with `--name` + `--object-id`.
- `--name <name>` — field name. Used together with `--object-id`.
- `--object-id <uuid>` — object UUID. Used together with `--name`.

#### Example

```bash
uip tm customfield value get \
  --object-type TestCase \
  --value-id v1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldValueGet",
  "Data": {
    "ValueId": "v1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Priority",
    "Value": "High"
  }
}
```

---

### uip tm customfield value create

Set a custom field value on an object.

#### Options

- `--object-type <type>` *(required)* — object type.
- `--name <name>` *(required)* — custom field name.
- `--object-id <uuid>` *(required)* — object UUID.
- `--data-type <type>` *(required)* — data type of the value (for example, `String`, `Integer`).
- `--value <value>` *(required)* — the value to set.

#### Example

```bash
uip tm customfield value create \
  --object-type TestCase \
  --name Priority \
  --object-id a1b2c3d4-0000-0000-0000-000000000001 \
  --data-type String \
  --value High
```

#### Data shape

```json
{
  "Code": "CustomFieldValueCreate",
  "Data": {
    "ValueId": "v1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Priority",
    "Value": "High"
  }
}
```

---

### uip tm customfield value update

Update an existing custom field value.

#### Options

- `--object-type <type>` *(required)* — object type.
- `--value-id <uuid>` — value UUID. Mutually exclusive with `--name` + `--object-id`.
- `--name <name>` — field name. Used together with `--object-id`.
- `--object-id <uuid>` — object UUID. Used together with `--name`.
- `--value <value>` *(required)* — the new value.
- `--clear` — clear the value instead of setting it.

#### Example

```bash
uip tm customfield value update \
  --object-type TestCase \
  --value-id v1b2c3d4-0000-0000-0000-000000000001 \
  --value Critical
```

#### Data shape

```json
{
  "Code": "CustomFieldValueUpdate",
  "Data": {
    "ValueId": "v1b2c3d4-0000-0000-0000-000000000001",
    "Value": "Critical",
    "Result": "Updated"
  }
}
```

---

### uip tm customfield value delete

Delete a custom field value.

#### Options

- `--object-type <type>` *(required)* — object type.
- `--value-id <uuid>` — value UUID. Mutually exclusive with `--name` + `--object-id`.
- `--name <name>` — field name. Used together with `--object-id`.
- `--object-id <uuid>` — object UUID. Used together with `--name`.
- `-y, --yes` — skip the confirmation prompt.

#### Example

```bash
uip tm customfield value delete \
  --object-type TestCase \
  --value-id v1b2c3d4-0000-0000-0000-000000000001 \
  --yes
```

#### Data shape

```json
{
  "Code": "CustomFieldValueDelete",
  "Data": {
    "ValueId": "v1b2c3d4-0000-0000-0000-000000000001",
    "Result": "Deleted"
  }
}
```

---

## Related

- [requirements](./uip-test-manager-requirements.md) — requirements can carry custom field values.
- [testcases](./uip-test-manager-testcases.md) — test cases can carry custom field values.

## See also

- [Test Manager overview](./uip-test-manager.md)
- [Authentication](./authentication.md)