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

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 and the standard exit codes. 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

uip tm requirements list \
  --project-key DEMO \
  --labels "high-priority" \
  --limit 20

Data shape

{
  "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

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

Data shape

{
  "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

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

Data shape

{
  "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

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

{
  "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

# 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

{
  "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

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

Data shape

{
  "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

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

Data shape

{
  "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

# 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

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

Data shape — detach

{ "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

uip tm requirements list-by-test-execution \
  --project-key DEMO \
  --execution-id b2c3d4e5-0000-0000-0000-000000000001

Data shape

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

Related

• project — owning project scope.
• testcases — test cases that can be linked to requirements.
• executions — source of the --execution-id used by list-by-test-execution.

See also

• Test Manager overview