# uip tm requirement

> Syntax and options for `uip tm requirement`, which manages requirements inside a Test Manager project: create, read, update, delete, clone, export, and link to test cases and defects.

`uip tm requirement` manages requirements inside a Test Manager project — create, read, update, delete, and relate requirements to test cases and defects. Requirements are the traceability layer: they express what the system must do, and each requirement can be linked to one or more test cases to show coverage.

A requirement is identified by a `RequirementKey` (`PROJECT:N`) and optionally by a connector-native key (`--requirement-key-external` / `--get-by-key`).

## Synopsis

```
uip tm requirement list --project-key <key> [filters…]
uip tm requirement get --project-key <key> --requirement-id <uuid>
uip tm requirement get-by-key --project-key <key> --requirement-key <key>
uip tm requirement create --project-key <key> --name <name> [options…]
uip tm requirement update --project-key <key> --requirement-key <key> [options…]
uip tm requirement delete --project-key <key> --requirement-key <key>
uip tm requirement bulk-delete --project-key <key> --requirement-keys <keys>
uip tm requirement clone --project-key <key> --requirement-key <key> [--name <name>]
uip tm requirement list-filtered --project-key <key> [filters…]
uip tm requirement list-related-defects --project-key <key> --requirement-key <key>
uip tm requirement list-by-test-execution --project-key <key> --execution-id <uuid>
uip tm requirement search-by-label --project-key <key> --label <text>
uip tm requirement export --project-key <key> [--format <format>] [--output-path <path>]
uip tm requirement list-testcase-ids --project-key <key> --requirement-key <key>
uip tm requirement assign-testcases --project-key <key> --requirement-key <key> --test-case-keys <keys>
uip tm requirement unassign-testcases --project-key <key> --requirement-key <key> --test-case-keys <keys>
uip tm requirement unlink-connector --project-key <key> --requirement-key <key>
```

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 requirement list

List all requirements in a project. The CLI pages through results automatically.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — project to list.
- `--filter <text>` — filter by name or key (server-side search).
- `--top <number>` — page size. Defaults to `50`.
- `--skip <number>` — results to skip. Defaults to `0`.

### Example

```bash
uip tm requirement list --project-key DEMO
```

### Data shape

```json
{
  "Code": "RequirementsList",
  "Data": [
    {
      "RequirementKey": "DEMO:1",
      "Name": "User must be able to log in",
      "Description": "Login with valid credentials succeeds"
    }
  ]
}
```

## uip tm requirement get

Get a single requirement by its internal UUID.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-id <uuid>` *(required)* — internal requirement UUID. Obtain from `requirement list` or from `RequirementCreate` output.

### Example

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

### Data shape

```json
{
  "Code": "RequirementGet",
  "Data": {
    "RequirementKey": "DEMO:1",
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "User must be able to log in",
    "Description": "Login with valid credentials succeeds"
  }
}
```

## uip tm requirement get-by-key

Get a requirement by its `PROJECT:N` key.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-key <key>` *(required)* — requirement key (for example, `DEMO:1`).

### Example

```bash
uip tm requirement get-by-key \
  --project-key DEMO \
  --requirement-key DEMO:1
```

### Data shape

```json
{
  "Code": "RequirementGetByKey",
  "Data": {
    "RequirementKey": "DEMO:1",
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "User must be able to log in",
    "Description": "Login with valid credentials succeeds"
  }
}
```

## uip tm requirement create

Create a new requirement in a project.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--name <name>` *(required)* — requirement name.
- `--description <text>` — free-form description. Defaults to empty.

### Example

```bash
uip tm requirement create \
  --project-key DEMO \
  --name "User must be able to log in" \
  --description "Login with valid credentials succeeds"
```

### Data shape

```json
{
  "Code": "RequirementCreate",
  "Data": {
    "RequirementKey": "DEMO:1",
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "User must be able to log in"
  }
}
```

## uip tm requirement update

Rename a requirement or change its description. At least one of `--name` or `--description` is required.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-key <key>` *(required)* — requirement key (for example, `DEMO:1`).
- `--name <name>` — new name. Omit to leave unchanged.
- `--description <text>` — new description. Omit to leave unchanged.

### Example

```bash
uip tm requirement update \
  --project-key DEMO \
  --requirement-key DEMO:1 \
  --name "User must be able to log in (revised)"
```

### Data shape

```json
{
  "Code": "RequirementUpdate",
  "Data": {
    "RequirementKey": "DEMO:1",
    "Name": "User must be able to log in (revised)",
    "Result": "Updated"
  }
}
```

## uip tm requirement delete

Delete a single requirement by its key.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-key <key>` *(required)* — requirement key (for example, `DEMO:1`).

### Example

```bash
uip tm requirement delete \
  --project-key DEMO \
  --requirement-key DEMO:1
```

### Data shape

```json
{
  "Code": "RequirementDelete",
  "Data": {
    "RequirementKey": "DEMO:1",
    "Result": "Deleted"
  }
}
```

## uip tm requirement bulk-delete

Delete multiple requirements in one call.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-keys <keys>` *(required)* — comma-separated `PROJECT:N` keys (for example, `DEMO:1,DEMO:2`).

### Example

```bash
uip tm requirement bulk-delete \
  --project-key DEMO \
  --requirement-keys DEMO:1,DEMO:2
```

### Data shape

```json
{
  "Code": "RequirementBulkDelete",
  "Data": {
    "Deleted": 2
  }
}
```

## uip tm requirement clone

Clone a requirement, optionally renaming the copy.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-key <key>` *(required)* — requirement key to clone (for example, `DEMO:1`).
- `--name <name>` — name for the cloned requirement. Defaults to `Copy of <original name>`.

### Example

```bash
uip tm requirement clone \
  --project-key DEMO \
  --requirement-key DEMO:1 \
  --name "User must be able to log in (copy)"
```

### Data shape

```json
{
  "Code": "RequirementClone",
  "Data": {
    "RequirementKey": "DEMO:5",
    "Name": "User must be able to log in (copy)"
  }
}
```

## uip tm requirement list-filtered

List requirements with richer server-side filters than `list`. Supports multi-value status and label filters.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — project to query.
- `--statuses <statuses...>` — space-separated requirement statuses to include. Accepted values are tool-version-dependent; run `uip tm requirement list-filtered --help` to see the current set.
- `--labels <labels...>` — space-separated label names to filter by.
- `--top <number>` — page size. Defaults to `50`.
- `--skip <number>` — results to skip. Defaults to `0`.

### Example

```bash
uip tm requirement list-filtered \
  --project-key DEMO \
  --labels "high-priority"
```

### Data shape

```json
{
  "Code": "RequirementsListFiltered",
  "Data": [
    {
      "RequirementKey": "DEMO:1",
      "Name": "User must be able to log in",
      "Status": "Active"
    }
  ]
}
```

## uip tm requirement list-related-defects

List defects linked to a requirement via a connector integration.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-key <key>` *(required)* — requirement key (for example, `DEMO:1`).

### Example

```bash
uip tm requirement list-related-defects \
  --project-key DEMO \
  --requirement-key DEMO:1
```

### Data shape

```json
{
  "Code": "RequirementRelatedDefects",
  "Data": [
    {
      "DefectId": "DEF-42",
      "Title": "Login fails on Safari",
      "Status": "Open"
    }
  ]
}
```

## uip tm requirement list-by-test-execution

List the requirements covered by a given test execution.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--execution-id <uuid>` *(required)* — execution UUID. Get from `uip tm testsets run` or `uip tm executions list`.

### Example

```bash
uip tm requirement list-by-test-execution \
  --project-key DEMO \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape

```json
{
  "Code": "RequirementsByExecution",
  "Data": [
    {
      "RequirementKey": "DEMO:1",
      "Name": "User must be able to log in"
    }
  ]
}
```

## uip tm requirement search-by-label

Find requirements tagged with a specific label.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--label <text>` *(required)* — label to search for.

### Example

```bash
uip tm requirement search-by-label \
  --project-key DEMO \
  --label "high-priority"
```

### Data shape

```json
{
  "Code": "RequirementsSearchByLabel",
  "Data": [
    {
      "RequirementKey": "DEMO:1",
      "Name": "User must be able to log in"
    }
  ]
}
```

## uip tm requirement export

Export requirements to a file. Format options and output defaults are tool-version-dependent; run `uip tm requirement export --help` to see the current set.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--format <format>` — export format (run `--help` to see accepted values).
- `--output-path <path>` — destination path for the exported file. Defaults to the current directory.

### Example

```bash
uip tm requirement export \
  --project-key DEMO \
  --output-path ./requirements-export.xlsx
```

### Data shape

Writes a file to `--output-path` and prints a `RequirementExport` envelope:

```json
{
  "Code": "RequirementExport",
  "Data": {
    "OutputPath": "./requirements-export.xlsx"
  }
}
```

## uip tm requirement list-testcase-ids

List the internal UUIDs of all test cases assigned to a requirement.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-key <key>` *(required)* — requirement key (for example, `DEMO:1`).

### Example

```bash
uip tm requirement list-testcase-ids \
  --project-key DEMO \
  --requirement-key DEMO:1
```

### Data shape

```json
{
  "Code": "RequirementTestCaseIds",
  "Data": [
    "a1b2c3d4-0000-0000-0000-000000000001",
    "a1b2c3d4-0000-0000-0000-000000000002"
  ]
}
```

## uip tm requirement assign-testcases

Link one or more test cases to a requirement.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-key <key>` *(required)* — requirement key (for example, `DEMO:1`).
- `--test-case-keys <keys>` *(required)* — comma-separated test case keys (for example, `DEMO:1,DEMO:2`).

### Example

```bash
uip tm requirement assign-testcases \
  --project-key DEMO \
  --requirement-key DEMO:1 \
  --test-case-keys DEMO:1,DEMO:2
```

### Data shape

```json
{
  "Code": "RequirementAssignTestCases",
  "Data": {
    "Assigned": 2
  }
}
```

## uip tm requirement unassign-testcases

Remove one or more test case links from a requirement.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-key <key>` *(required)* — requirement key (for example, `DEMO:1`).
- `--test-case-keys <keys>` *(required)* — comma-separated test case keys to unlink.

### Example

```bash
uip tm requirement unassign-testcases \
  --project-key DEMO \
  --requirement-key DEMO:1 \
  --test-case-keys DEMO:1,DEMO:2
```

### Data shape

```json
{
  "Code": "RequirementUnassignTestCases",
  "Data": {
    "Unassigned": 2
  }
}
```

## uip tm requirement unlink-connector

Remove a connector integration link from a requirement. Disconnects the external tool mapping without deleting the requirement itself.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-key <key>` *(required)* — requirement key (for example, `DEMO:1`).

### Example

```bash
uip tm requirement unlink-connector \
  --project-key DEMO \
  --requirement-key DEMO:1
```

### Data shape

```json
{
  "Code": "RequirementUnlinkConnector",
  "Data": {
    "RequirementKey": "DEMO:1",
    "Result": "Unlinked"
  }
}
```

## Related

- [testcases](./uip-test-manager-testcases.md) — assign test cases to requirements with `requirement assign-testcases`.
- [objectlabel](./uip-test-manager-objectlabel.md) — manage the labels you can search by with `requirement search-by-label`.
- [executions](./uip-test-manager-executions.md) — list requirements covered by a run with `requirement list-by-test-execution`.

## See also

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