# uip tm objectlabel

> Syntax and options for `uip tm objectlabel`, which manages labels attached to Test Manager objects such as test cases and requirements.

`uip tm objectlabel` manages labels attached to Test Manager objects (test cases, requirements, and so on). Labels are free-form strings used to tag and group objects for filtering and search.

:::important
`--object-ids` and `--labels` are **plural and space-separated** throughout this command group. The singular forms `--object-id` and `--label` do not exist. `--project-key` is required on `list`.
:::

## Synopsis

```text
uip tm objectlabel list --project-key <key> [--object-ids <uuid...>] [--label-types <types...>] [--filter <text>] [--sort-by <expr>] [--limit <n>] [--offset <n>]
uip tm objectlabel get --label-id <uuid>
uip tm objectlabel add --object-ids <uuid...> --labels <name...> [--label-type <type>] [--remove-other-labels]
uip tm objectlabel remove --object-ids <uuid...> (--labels <name...> | --remove-all-labels) [-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`).

## uip tm objectlabel list

List label assignments, optionally scoped to specific objects.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--object-ids <uuid...>` — space-separated object UUIDs to filter by. Optional; omit to list across all objects in the project.
- `--label-types <types...>` — space-separated label types to filter by.
- `--filter <text>` — free-text search over label names.
- `--sort-by <expr>` — sort expression (field name, optionally suffixed with `:asc` or `:desc`).
- `--limit <n>` — page size. Defaults to `50`.
- `--offset <n>` — results to skip. Defaults to `0`.

### Example

```bash
uip tm objectlabel list \
  --project-key DEMO \
  --object-ids a1b2c3d4-0000-0000-0000-000000000001 b2c3d4e5-0000-0000-0000-000000000001
```

### Data shape

```json
{
  "Code": "ObjectLabelList",
  "Data": [
    {
      "LabelId": "c3d4e5f6-0000-0000-0000-000000000001",
      "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
      "Label": "smoke",
      "LabelType": "Tag"
    }
  ]
}
```

## uip tm objectlabel get

Get a single label assignment by its assignment UUID.

### Arguments

None.

### Options

- `--label-id <uuid>` *(required)* — UUID of the label assignment (the `LabelId` returned by `objectlabel list`). This is the assignment record UUID, not a label name.

### Example

```bash
uip tm objectlabel get \
  --label-id c3d4e5f6-0000-0000-0000-000000000001
```

### Data shape

```json
{
  "Code": "ObjectLabelGet",
  "Data": {
    "LabelId": "c3d4e5f6-0000-0000-0000-000000000001",
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Label": "smoke",
    "LabelType": "Tag"
  }
}
```

## uip tm objectlabel add

Add one or more labels to one or more objects.

### Arguments

None.

### Options

- `--object-ids <uuid...>` *(required)* — space-separated object UUIDs to apply the labels to.
- `--labels <name...>` *(required)* — space-separated label names to add.
- `--label-type <type>` — label type classification. Optional.
- `--remove-other-labels` — remove any existing labels on the specified objects before adding the new ones. Optional.

### Example

```bash
uip tm objectlabel add \
  --object-ids a1b2c3d4-0000-0000-0000-000000000001 b2c3d4e5-0000-0000-0000-000000000001 \
  --labels smoke regression \
  --label-type Tag
```

### Data shape

```json
{
  "Code": "ObjectLabelAdd",
  "Data": {
    "Added": 4,
    "Result": "Added"
  }
}
```

## uip tm objectlabel remove

Remove labels from one or more objects. Supply either `--labels` to remove specific labels, or `--remove-all-labels` to remove every label from the specified objects.

### Arguments

None.

### Options

- `--object-ids <uuid...>` *(required)* — space-separated object UUIDs.
- `--labels <name...>` — space-separated label names to remove. Mutually exclusive with `--remove-all-labels`.
- `--remove-all-labels` — remove all labels from the specified objects. Mutually exclusive with `--labels`.
- `-y, --yes` — skip the confirmation prompt.

### Examples

```bash
# remove specific labels
uip tm objectlabel remove \
  --object-ids a1b2c3d4-0000-0000-0000-000000000001 \
  --labels smoke \
  --yes

# remove all labels
uip tm objectlabel remove \
  --object-ids a1b2c3d4-0000-0000-0000-000000000001 \
  --remove-all-labels \
  --yes
```

### Data shape

```json
{
  "Code": "ObjectLabelRemove",
  "Data": {
    "Removed": 1,
    "Result": "Removed"
  }
}
```

## Related

- [requirements](./uip-test-manager-requirements.md) — search requirements by label with `requirements list --labels <label...>`.
- [customfield](./uip-test-manager-customfield.md) — custom field definitions can use labels.

## See also

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