# uip tm customfield

> Syntax and options for `uip tm customfield`, which manages custom field definitions, label rows, and value rows on a Test Manager project.

`uip tm customfield` manages custom field definitions on a Test Manager project. Custom fields extend requirements, test cases, and test sets 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 Label-type field rows (a JSON map of field name to one or more string values, per object)
- `customfield value` — manage Text-type field rows (a single string value, per object)

:::important
The primary identifier for field definitions is `--field-id`. Label and value rows are identified by `--label-id` / `--value-id`, or by the natural key `--object-type` + `--name` + `--object-id`. The flag `--customfield-id` does not exist.
:::

## 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 --project-key <key> (--field-id <uuid> | --name <name> --object-type <type>)
uip tm customfield create --project-key <key> --name <name> --data-type <Text|Label> (--object-type <type> | --scope-list <types...>) [--description <text>] [--default-value <value>] [--value-hints <hints>]
uip tm customfield update --project-key <key> (--field-id <uuid> | --name <name> --object-type <type>) [--rename-to <name>] [--description <text>] [--default-value <value>] [--value-hints <hints>] [--scope-list <types...>]
uip tm customfield delete --project-key <key> (--field-ids <uuid...> | --name <name> --object-type <type>) [-y]

# Labels
uip tm customfield label get --project-key <key> --object-type <type> --label-id <uuid>
uip tm customfield label list --project-key <key> --object-type <type> [--object-id <uuid>] [--filter <text>] [--sort-by <expr>] [--limit <n>] [--offset <n>]
uip tm customfield label create --project-key <key> --object-type <type> --object-id <uuid> --values <json>
uip tm customfield label add --project-key <key> --object-type <type> --custom-field-name <name> --object-ids <uuid...> --values <value...> [--replace-existing-values]
uip tm customfield label remove --project-key <key> --object-type <type> --custom-field-name <name> --object-ids <uuid...> (--values <value...> | --remove-all-values) [-y]

# Values
uip tm customfield value list --project-key <key> --object-type <type> [--object-id <uuid>] [--filter <text>] [--sort-by <expr>] [--limit <n>] [--offset <n>]
uip tm customfield value get --project-key <key> --object-type <type> (--value-id <uuid> | --name <name> --object-id <uuid>)
uip tm customfield value create --project-key <key> --object-type <type> --name <name> --object-id <uuid> --data-type <Text|Label> [--value <text>]
uip tm customfield value update --project-key <key> --object-type <type> (--value-id <uuid> | --name <name> --object-id <uuid>) [--data-type <Text|Label>] (--value <text> | --clear)
uip tm customfield value delete --project-key <key> --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 `--log-level <level>` (default `Information`) and `-t, --tenant <name>` (defaults to the authenticated tenant).

:::note
`-t, --tenant` here is a normal, visible option.
:::

`--object-type` (and `--object-types`/`--scope-list` where variadic) only accepts `Requirement`, `TestCase`, or `TestSet`. `--data-type` (and `--data-types`) only accepts `Text` or `Label` — there is no `String`, `Integer`, or `Boolean` data type.

---

## Field definition commands

### uip tm customfield list

List custom field definitions in a project. `--project-key` is **required**; every other filter is optional.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-types <types...>` — space-separated object types to filter by: `Requirement`, `TestCase`, `TestSet`.
- `--data-types <types...>` — space-separated data types to filter by: `Text`, `Label`.
- `--name <name>` — exact-name match (client-side filter; returns one row per object type the field is defined on).
- `--filter <text>` — server-side substring search across definition fields.
- `--sort-by <expr>` — sort expression, for example `name asc`.
- `--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": "CustomFieldDefinitionsList",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000001",
      "ProjectId": "p1",
      "Name": "Priority",
      "Description": "Test priority",
      "DefaultValue": "Medium",
      "ValueHints": "",
      "ObjectType": "TestCase",
      "DataType": "Text",
      "ScopeList": ["TestCase"]
    }
  ]
}
```

---

### uip tm customfield get

Get a single custom field definition. Identify by `--field-id`, OR by `--name` + `--object-type`.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--field-id <uuid>` — field UUID.
- `--name <name>` — field name. Used together with `--object-type`.
- `--object-type <type>` — object type the field belongs to: `Requirement`, `TestCase`, `TestSet`. Used together with `--name`.

#### Example

```bash
uip tm customfield get \
  --project-key DEMO \
  --field-id a1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldDefinitionGet",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "ProjectId": "p1",
    "Name": "Priority",
    "Description": "Test priority",
    "DefaultValue": "Medium",
    "ValueHints": "",
    "ObjectType": "TestCase",
    "DataType": "Text",
    "ScopeList": ["TestCase"]
  }
}
```

---

### uip tm customfield create

Create a new custom field definition. Provide `--object-type` for a single scope, OR `--scope-list` for multiple — the two are mutually exclusive, and one is required.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--name <name>` *(required)* — field name.
- `--data-type <type>` *(required)* — `Text` or `Label`.
- `--object-type <type>` — single scope: `Requirement`, `TestCase`, `TestSet`. Mutually exclusive with `--scope-list`.
- `--scope-list <types...>` — multi-object scope (space-separated): `Requirement`, `TestCase`, `TestSet`. Mutually exclusive with `--object-type`.
- `--description <text>` — field description.
- `--default-value <text>` — default value seeded onto every existing object of the field's type.
- `--value-hints <text>` — UI hint text shown next to the field.

#### Example

```bash
uip tm customfield create \
  --project-key DEMO \
  --name Priority \
  --data-type Text \
  --object-type TestCase \
  --description "Test priority" \
  --default-value Medium
```

#### Data shape

```json
{
  "Code": "CustomFieldDefinitionCreate",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "ProjectId": "p1",
    "Name": "Priority",
    "Description": "Test priority",
    "DefaultValue": "Medium",
    "ValueHints": "",
    "ObjectType": "TestCase",
    "DataType": "Text",
    "ScopeList": ["TestCase"]
  }
}
```

---

### uip tm customfield update

Update an existing custom field definition. Identify by `--field-id`, OR by `--name` + `--object-type`. Unspecified fields keep their current values.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--field-id <uuid>` — field UUID.
- `--name <name>` — field name (for lookup). Used together with `--object-type`.
- `--object-type <type>` — object type the field belongs to. Used together with `--name`.
- `--rename-to <name>` — new name for the field.
- `--description <text>` — new description.
- `--default-value <text>` — new default value.
- `--value-hints <text>` — new UI hint text.
- `--scope-list <types...>` — new multi-object scope (space-separated).

#### Example

```bash
uip tm customfield update \
  --project-key DEMO \
  --field-id a1b2c3d4-0000-0000-0000-000000000001 \
  --rename-to Severity
```

#### Data shape

```json
{
  "Code": "CustomFieldDefinitionUpdate",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Severity",
    "Result": "Updated"
  }
}
```

---

### uip tm customfield delete

Delete one or more custom field definitions. Identify by `--field-ids` (one or many UUIDs), OR by `--name` + `--object-type` (single, by natural key). Hard delete with no cascade — orphan label/value rows are **not** cleaned up.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--field-ids <uuid...>` — space-separated field UUIDs to delete.
- `--name <name>` — field name (used with `--object-type`).
- `--object-type <type>` — object type the field belongs to (used with `--name`).
- `-y, --yes` — confirm this irreversible operation. Required — the CLI never prompts.

#### Example

```bash
uip tm customfield delete \
  --project-key DEMO \
  --field-ids a1b2c3d4-0000-0000-0000-000000000001 \
  --yes
```

#### Data shape

```json
{
  "Code": "CustomFieldDefinitionsDelete",
  "Data": { "Passed": 1, "Failed": 0 }
}
```

`Passed`/`Failed` are counts, not per-id detail — the response does not echo back which UUIDs failed. Unknown UUIDs passed via `--field-ids` are forwarded to the bulk endpoint and counted as `Failed` rather than rejected up front.

---

## Label commands

Label rows carry one JSON object per object instance, mapping custom field name to an array of string values (`{"Priority":["High"],"Tags":["smoke","critical"]}`).

### uip tm customfield label get

Get a custom field label row by `--label-id`. To look up by object instead, use `customfield label list --object-id <uuid>` (returns the same row as a one-element array).

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-type <type>` *(required)* — object type the label belongs to: `Requirement`, `TestCase`, `TestSet`.
- `--label-id <uuid>` *(required)* — UUID of the label row (not the label name).

#### Example

```bash
uip tm customfield label get \
  --project-key DEMO \
  --object-type TestCase \
  --label-id f1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelGet",
  "Data": {
    "Id": "f1b2c3d4-0000-0000-0000-000000000001",
    "ProjectId": "p1",
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ObjectType": "TestCase",
    "Values": { "Priority": ["High"], "Tags": ["smoke", "critical"] },
    "Created": "2025-01-01T00:00:00Z",
    "CreatedBy": "alice@example.com",
    "Updated": "2025-01-02T00:00:00Z",
    "UpdatedBy": "alice@example.com"
  }
}
```

---

### uip tm customfield label list

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

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-type <type>` *(required)* — object type to list labels for.
- `--object-id <uuid>` — filter to a specific object UUID.
- `--filter <text>` — search label rows by value.
- `--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 label list \
  --project-key DEMO \
  --object-type TestCase \
  --object-id a1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelsList",
  "Data": [
    {
      "Id": "f1b2c3d4-0000-0000-0000-000000000001",
      "ProjectId": "p1",
      "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
      "ObjectType": "TestCase",
      "Values": { "Priority": ["High"], "Tags": ["smoke", "critical"] },
      "Created": "2025-01-01T00:00:00Z",
      "CreatedBy": "alice@example.com",
      "Updated": "2025-01-02T00:00:00Z",
      "UpdatedBy": "alice@example.com"
    }
  ]
}
```

---

### uip tm customfield label create

Upsert label values for an object. The backend merges any new field-name keys into an existing row for the same object — it does not replace the whole row.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-type <type>` *(required)* — object type to attach the labels to.
- `--object-id <uuid>` *(required)* — UUID of the object to label.
- `--values <json>` *(required)* — a non-empty JSON **object** mapping field names to arrays of strings, for example `{"Priority":["High"],"Tags":["smoke","critical"]}`. A JSON array, or a value that isn't an array of strings per key, is rejected client-side.

#### Example

```bash
uip tm customfield label create \
  --project-key DEMO \
  --object-type TestCase \
  --object-id a1b2c3d4-0000-0000-0000-000000000001 \
  --values '{"Priority":["High"],"Tags":["smoke"]}'
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelCreate",
  "Data": {
    "Id": "f1b2c3d4-0000-0000-0000-000000000001",
    "ProjectId": "p1",
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ObjectType": "TestCase",
    "Values": { "Priority": ["High"], "Tags": ["smoke"] },
    "Created": "2025-01-01T00:00:00Z",
    "CreatedBy": "alice@example.com",
    "Updated": "2025-01-01T00:00:00Z",
    "UpdatedBy": "alice@example.com"
  }
}
```

---

### uip tm customfield label add

Add label values to one named custom field across multiple objects in a single call.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-type <type>` *(required)* — object type.
- `--custom-field-name <name>` *(required)* — name of an existing custom field definition for this object type.
- `--object-ids <uuid...>` *(required)* — space-separated object UUIDs to apply the label to.
- `--values <value...>` *(required)* — space-separated label values to add.
- `--replace-existing-values` — replace existing values instead of merging (default: merge).

#### Example

```bash
uip tm customfield label add \
  --project-key DEMO \
  --object-type TestCase \
  --custom-field-name Priority \
  --object-ids id1 id2 \
  --values High Critical
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelAdd",
  "Data": {
    "CustomFieldName": "Priority",
    "ObjectCount": 2,
    "Result": "Added"
  }
}
```

---

### uip tm customfield label remove

Remove label values from one named custom field across multiple objects. This is a **destructive** operation — it requires `-y, --yes`; the CLI never prompts.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--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 <value...>` — space-separated label values to remove. Required unless `--remove-all-values` is set.
- `--remove-all-values` — clear all values for this field on the listed objects. Mutually exclusive with `--values`.
- `-y, --yes` — confirm this irreversible operation. Required — the CLI never prompts.

#### Example

```bash
uip tm customfield label remove \
  --project-key DEMO \
  --object-type TestCase \
  --custom-field-name Priority \
  --object-ids id1 id2 \
  --values Critical \
  --yes
```

#### Data shape

```json
{
  "Code": "CustomFieldLabelRemove",
  "Data": {
    "CustomFieldName": "Priority",
    "ObjectCount": 2,
    "Result": "Removed"
  }
}
```

---

## Value commands

Value rows carry a single Text-type value per object.

### uip tm customfield value list

List custom field values for an object type. Results are empty unless `--object-id` is provided.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-type <type>` *(required)* — object type.
- `--object-id <uuid>` — object UUID whose values to list. Required in practice — results are empty when omitted.
- `--filter <text>` — search values by content.
- `--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 value list \
  --project-key DEMO \
  --object-type TestCase \
  --object-id a1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldValuesList",
  "Data": [
    {
      "Id": "v1b2c3d4-0000-0000-0000-000000000001",
      "Name": "Priority",
      "Value": "High",
      "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
      "ObjectType": "TestCase",
      "DataType": "Text",
      "Updated": "2025-01-02T00:00:00Z"
    }
  ]
}
```

---

### uip tm customfield value get

Get a single custom field value row. Identify by `--value-id`, OR by `--name` + `--object-id`.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-type <type>` *(required)* — object type.
- `--value-id <uuid>` — value row UUID.
- `--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 \
  --project-key DEMO \
  --object-type TestCase \
  --value-id v1b2c3d4-0000-0000-0000-000000000001
```

#### Data shape

```json
{
  "Code": "CustomFieldValueGet",
  "Data": {
    "Id": "v1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Priority",
    "Value": "High",
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ObjectType": "TestCase",
    "DataType": "Text",
    "Updated": "2025-01-02T00:00:00Z"
  }
}
```

---

### uip tm customfield value create

Create a custom field value row on an object.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-type <type>` *(required)* — object type.
- `--name <name>` *(required)* — custom field name (must match an existing definition).
- `--object-id <uuid>` *(required)* — object UUID this value attaches to.
- `--data-type <type>` *(required)* — `Text` or `Label` (must match the definition).
- `--value <text>` — value content. Optional — omit to create an empty row.

#### Example

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

#### Data shape

```json
{
  "Code": "CustomFieldValueCreate",
  "Data": {
    "Id": "v1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Priority",
    "Value": "High",
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ObjectType": "TestCase",
    "DataType": "Text",
    "Updated": "2025-01-02T00:00:00Z"
  }
}
```

---

### uip tm customfield value update

Update an existing custom field value row. Identify by `--value-id`, OR by `--name` + `--object-id`. `--value` is required unless `--clear` is passed.

:::note
An empty `--value` can cause the row to be deleted instead of updated when its field name no longer maps to a definition. Pass `--clear` to acknowledge that intent.
:::

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-type <type>` *(required)* — object type.
- `--value-id <uuid>` — value row UUID.
- `--name <name>` — field name. Used together with `--object-id`.
- `--object-id <uuid>` — object UUID. Used together with `--name`.
- `--data-type <type>` — `Text` or `Label`. Defaults to the row's current data type.
- `--value <text>` — the new value. Required unless `--clear` is passed.
- `--clear` — acknowledge that an empty `--value` may delete the row.

#### Example

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

#### Data shape

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

---

### uip tm customfield value delete

Delete a custom field value row. Identify by `--value-id`, OR by `--name` + `--object-id`.

#### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-type <type>` *(required)* — object type.
- `--value-id <uuid>` — value row UUID.
- `--name <name>` — field name. Used together with `--object-id`.
- `--object-id <uuid>` — object UUID. Used together with `--name`.
- `-y, --yes` — confirm this irreversible operation. Required — the CLI never prompts.

#### Example

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

#### Data shape

```json
{
  "Code": "CustomFieldValueDelete",
  "Data": {
    "Id": "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)