# uip tm requirements

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

`uip tm requirements` manages requirements inside a Test Manager project. 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. You can create requirements manually or sync them from an external Application Lifecycle Management (ALM) connector (for example, Jira) if configured in Test Manager.

## Synopsis

```text
uip tm requirements list --project-key <key> [--filter <text>] [--requirement-ids <ids...>] [--labels <labels...>] [--updated-by <userId>] [--test-case-id <uuid>] [--changed-since <datetime>] [--sort-by <expr>] [--limit <n>] [--offset <n>]
uip tm requirements get --project-key <key> (--requirement-id <uuid> | --requirement-key <key>)
uip tm requirements create --project-key <key> --name <name> [--description <text>] [--container-id <uuid>] [--external-reference <ref>] [--connector-requirement-uuid <uuid>]
uip tm requirements update --project-key <key> --requirement-id <uuid> [--name <name>] [--description <text>]
uip tm requirements delete --project-key <key> --requirement-ids <uuid...> -y
uip tm requirements export --project-key <key> --output-file <path> [--requirement-ids <uuid...>] [--updated-by <userId>] [--test-case-id <uuid>] [--labels <label...>] [--filter <text>] [--sort-by <expr>]
uip tm requirements list-testcase-ids --project-key <key> --requirement-id <uuid>
uip tm requirements testcases --project-key <key> --requirement-id <uuid> (--add-testcase-ids <uuid...> | --remove-testcase-ids <uuid...>)
uip tm requirements list-by-test-execution --project-key <key> --execution-id <uuid> [--labels <label...>] [--updated-by <userId>] [--filter <text>] [--sort-by <expr>] [--limit <n>] [--offset <n>]
```

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`).

## uip tm requirements list

List requirements in a project with rich server-side filtering. The CLI picks the most specific backend endpoint based on the filter flags supplied — a label-only filter uses a fast path; combining labels with other filters uses the rich-filter endpoint.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Project to list. |
| `--filter <text>` | Search requirements by name or key. |
| `--requirement-ids <uuid...>` | Space-separated UUIDs to include. Routes through the rich-filter endpoint. |
| `--labels <labels...>` | Space-separated label names to filter by. When supplied alone, uses a label-only fast path. |
| `--updated-by <userId>` | Filter by the user ID who last updated the requirement. |
| `--test-case-id <uuid>` | Return only requirements linked to this test case UUID. |
| `--changed-since <datetime>` | Return requirements modified after this ISO-8601 timestamp. |
| `--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 requirements list \
  --project-key DEMO \
  --labels "high-priority" \
  --limit 20
```

### Data shape

```json
{
  "Code": "RequirementsList",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000001",
      "ObjKey": "DEMO:1",
      "ProjectId": "00000000-0000-0000-0000-000000000abc",
      "Name": "User must be able to log in",
      "Description": "Login with valid credentials succeeds",
      "ContainerId": "c1c2c3c4-0000-0000-0000-000000000001",
      "ConnectorRequirementId": "ext-req-42",
      "ForeignReference": "JIRA-100",
      "CustomFieldLabels": { "Tags": "smoke, auth" },
      "CustomFieldValues": { "Owner": "qa-team" },
      "Created": "2025-04-15T10:30:00Z",
      "CreatedBy": "11111111-2222-3333-4444-555555555555",
      "Updated": "2025-04-15T10:30:00Z",
      "UpdatedBy": "11111111-2222-3333-4444-555555555555"
    }
  ]
}
```

Key fields: `ObjKey` — use in `--requirement-key` on `get`. `Id` — use in `--requirement-id` on `get`, `update`, `delete`, `list-testcase-ids`, and `testcases`. `ForeignReference` — set via `--external-reference` on `create`.

## uip tm requirements get

Get a single requirement by its internal UUID or its `PROJECT:N` key. Pass either `--requirement-id` or `--requirement-key` — they are mutually exclusive.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--requirement-id <uuid>` | Internal requirement UUID. Mutually exclusive with `--requirement-key`. |
| `--requirement-key <key>` | Requirement key (for example, `DEMO:1`). Mutually exclusive with `--requirement-id`. |

### Example

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

### Data shape

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

## uip tm requirements create

Create a new requirement in a project.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--name <name>` | **Required.** Requirement name. |
| `--description <text>` | Free-form description. Defaults to empty. |
| `--container-id <uuid>` | Container UUID to place the requirement in (optionally). |
| `--external-reference <ref>` | External system reference (for example, a Jira ticket ID). |
| `--connector-requirement-uuid <uuid>` | UUID from a connected external requirements system. Must be a valid UUID. |

### Example

```bash
uip tm requirements create \
  --project-key DEMO \
  --name "User must be able to log in" \
  --external-reference "JIRA-123"
```

### Data shape

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

## uip tm requirements update

Update an existing requirement. At least one of these fields must be provided.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--requirement-id <uuid>` | **Required.** Internal UUID of the requirement to update. |
| `--name <name>` | New name. |
| `--description <text>` | New description. |

### Example

```bash
uip tm requirements update \
  --project-key DEMO \
  --requirement-id a1b2c3d4-0000-0000-0000-000000000001 \
  --name "User must be able to log in with MFA"
```

### Data shape

```json
{
  "Code": "RequirementUpdate",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "User must be able to log in with MFA",
    "Result": "Updated"
  }
}
```

## uip tm requirements delete

Delete one or more requirements. `-y`/`--yes` is required — the CLI never prompts interactively. A single UUID and multiple UUIDs both route through the same bulk endpoint.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--requirement-ids <uuid...>` | **Required.** Requirement UUIDs to delete (space-separated). |
| `-y, --yes` | **Required.** Confirm this irreversible operation. |

### Examples

```bash
# Delete a single requirement
uip tm requirements delete \
  --project-key DEMO \
  --requirement-ids a1b2c3d4-0000-0000-0000-000000000001 \
  --yes

# Delete multiple requirements in one call
uip tm requirements delete \
  --project-key DEMO \
  --requirement-ids a1b2c3d4-0000-0000-0000-000000000001 b2c3d4e5-0000-0000-0000-000000000001 \
  --yes
```

### Data shape

```json
{
  "Code": "RequirementDelete",
  "Data": { "Passed": 2, "Failed": 0 }
}
```

## uip tm requirements export

Export requirements to an `.xlsx` file. Supports the same filter flags as `requirements list`.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--output-file <path>` | **Required.** Path to write the export file. |
| `--requirement-ids <uuid...>` | Filter by requirement UUIDs. |
| `--updated-by <userId>` | Filter by the user ID who last updated the requirement. |
| `--test-case-id <uuid>` | Filter by linked test case UUID. |
| `--labels <label...>` | Filter by labels. |
| `--filter <text>` | Search by name or key. |
| `--sort-by <expr>` | Sort results. |

### Example

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

### Data shape

```json
{
  "Code": "RequirementExport",
  "Data": { "OutputFile": "./requirements-export.xlsx", "Bytes": 1024, "Result": "Exported" }
}
```

## uip tm requirements list-testcase-ids

List the UUIDs of the test cases linked to a requirement.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--requirement-id <uuid>` | **Required.** Internal UUID of the requirement. |

### Example

```bash
uip tm requirements list-testcase-ids \
  --project-key DEMO \
  --requirement-id a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape

```json
{
  "Code": "RequirementListTestCaseIds",
  "Data": { "TestCaseIds": ["b2c3d4e5-0000-0000-0000-000000000001", "c3d4e5f6-0000-0000-0000-000000000001"] }
}
```

## uip tm requirements testcases

Add or remove test case links on a requirement. Pass either `--add-testcase-ids` or `--remove-testcase-ids` (not both in the same call).

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--requirement-id <uuid>` | **Required.** Requirement to modify. |
| `--add-testcase-ids <uuid...>` | Space-separated test case UUIDs to link. |
| `--remove-testcase-ids <uuid...>` | Space-separated test case UUIDs to unlink. |

### Examples

```bash
# link test cases
uip tm requirements testcases \
  --project-key DEMO \
  --requirement-id a1b2c3d4-0000-0000-0000-000000000001 \
  --add-testcase-ids b2c3d4e5-0000-0000-0000-000000000001 c3d4e5f6-0000-0000-0000-000000000001

# unlink test cases
uip tm requirements testcases \
  --project-key DEMO \
  --requirement-id a1b2c3d4-0000-0000-0000-000000000001 \
  --remove-testcase-ids b2c3d4e5-0000-0000-0000-000000000001
```

### Data shape — attach

```json
{ "Code": "RequirementTestCasesAssign", "Data": { "Id": "a1b2c3d4-...", "Assigned": 2, "Result": "Assigned" } }
```

### Data shape — detach

```json
{ "Code": "RequirementTestCasesUnassign", "Data": { "Id": "a1b2c3d4-...", "Unassigned": 1, "Result": "Unassigned" } }
```

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

List requirements covered by a specific test execution. Returns the requirements whose linked test cases were included in that execution.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | **Required.** Owning project. |
| `--execution-id <uuid>` | **Required.** Test execution UUID. |
| `--labels <label...>` | Filter by label names (space-separated). |
| `--updated-by <userId>` | Filter by the user ID who last updated the requirement. |
| `--filter <text>` | Search requirements by name or key. |
| `--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 requirements list-by-test-execution \
  --project-key DEMO \
  --execution-id b2c3d4e5-0000-0000-0000-000000000001
```

### Data shape

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

## Related

- [project](./uip-test-manager-project.md) — owning project scope.
- [testcases](./uip-test-manager-testcases.md) — test cases that can be linked to requirements.
- [executions](./uip-test-manager-executions.md) — source of the `--execution-id` used by `list-by-test-execution`.

## See also

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