# 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.

## 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>] [--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>
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 `-t, --tenant <name>` and `--log-level <level>` (default `Information`).

## uip tm requirements list

List requirements in a project with rich server-side filtering.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — project to list.
- `--filter <text>` — search requirements by name or key.
- `--requirement-ids <uuid...>` — space-separated UUIDs to include.
- `--labels <labels...>` — space-separated label names to filter by.
- `--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": [
    {
      "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 requirements get

Get a single requirement. Either `--requirement-id` or `--requirement-key` must be supplied; they are optional and mutually exclusive.

### Arguments

None.

### Options

- `--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": {
    "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 requirements 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.
- `--external-reference <ref>` — external system reference (for example, a Jira ticket ID).
- `--connector-requirement-uuid <uuid>` — UUID from a connected external requirements system.

### 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": {
    "RequirementKey": "DEMO:1",
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "User must be able to log in"
  }
}
```

## uip tm requirements update

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

### Arguments

None.

### Options

- `--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": {
    "RequirementKey": "DEMO:1",
    "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 by their internal UUIDs.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--requirement-ids <uuid...>` *(required)* — space-separated internal UUIDs to delete.
- `-y, --yes` — skip the confirmation prompt.

### Example

```bash
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": {
    "Deleted": 2,
    "Result": "Deleted"
  }
}
```

## uip tm requirements export

Export requirements to a file.

### Arguments

None.

### Options

- `--project-key <key>` *(required)* — owning project.
- `--output-file <path>` *(required)* — path to write the export file.

### Example

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

### Data shape

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

## uip tm requirements list-testcase-ids

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

### Arguments

None.

### Options

- `--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": "RequirementTestCaseIds",
  "Data": [
    "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

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

```json
{
  "Code": "RequirementTestCases",
  "Data": {
    "RequirementId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Result": "Updated"
  }
}
```

## 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

- `--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": "RequirementsListByTestExecution",
  "Data": [
    {
      "RequirementKey": "DEMO:1",
      "Id": "a1b2c3d4-0000-0000-0000-000000000001",
      "Name": "User must be able to log in",
      "Description": "Login with valid credentials succeeds"
    }
  ]
}
```

## Related

- [project](./uip-test-manager-project.md) — owning project scope.
- [testcases](./uip-test-manager-testcases.md) — test cases that can be linked to requirements.

## See also

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