UiPath Documentation
uipath-cli
latest
false
UiPath CLI user guide

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, and run AI jobs that generate test cases, evaluate requirements, and find obsolete test cases.

uip tm requirements manages requirements inside a Test Manager project. Requirements are the traceability layer: each one states what the system must do, and links to the test cases that cover it. You create requirements manually or sync them from an external Application Lifecycle Management (ALM) connector, such as Jira, when one is configured in Test Manager.

Three verbs run Test Manager's AI on a requirement as a background job: generate-testcases proposes test cases, evaluate reviews the requirement's quality, and find-obsolete-testcases flags linked test cases that no longer match it. AI jobs describes how you start, wait for, and read these jobs.

Synopsis​

uip tm requirements list (--project-key <key> | --project-id <id>) [--filter <text>] [--requirement-ids <uuid...>] [--labels <label...>] [--updated-by <user-id>] [--test-case-id <uuid>] [--changed-since <iso-date>] [--sort-by <expression>] [--limit <number>] [--offset <number>]
uip tm requirements get (--project-key <key> | --project-id <id>) (--requirement-id <uuid> | --requirement-key <key>)
uip tm requirements create (--project-key <key> | --project-id <id>) --name <name> [--description <text>] [--container-id <uuid>] [--external-reference <ref>] [--connector-requirement-uuid <uuid>]
uip tm requirements update (--project-key <key> | --project-id <id>) --requirement-id <uuid> [--name <name>] [--description <text>]
uip tm requirements delete (--project-key <key> | --project-id <id>) --requirement-ids <uuid...> -y
uip tm requirements export (--project-key <key> | --project-id <id>) --output-file <path> [--requirement-ids <uuid...>] [--updated-by <user-id>] [--test-case-id <uuid>] [--labels <label...>] [--filter <text>] [--sort-by <expression>]
uip tm requirements list-testcase-ids (--project-key <key> | --project-id <id>) --requirement-id <uuid>
uip tm requirements testcases (--project-key <key> | --project-id <id>) --requirement-id <uuid> (--add-testcase-ids <uuid...> | --remove-testcase-ids <uuid...>)
uip tm requirements list-by-test-execution (--project-key <key> | --project-id <id>) --execution-id <uuid> [--labels <label...>] [--updated-by <user-id>] [--filter <text>] [--sort-by <expression>] [--limit <number>] [--offset <number>]
uip tm requirements generate-testcases (--project-key <key> | --project-id <id>) (--requirement-id <uuid> | --requirement-key <key> | --activity-id <uuid>) [--instructions <text>] [--attachment-ids <uuid...>] [--wait] [--create [--select <numbers...>]] [--timeout <seconds>] [--poll-interval <seconds>]
uip tm requirements evaluate (--project-key <key> | --project-id <id>) (--requirement-id <uuid> | --requirement-key <key> | --activity-id <uuid> [--more-suggestions]) [--instructions <text>] [--attachment-ids <uuid...>] [--wait] [--timeout <seconds>] [--poll-interval <seconds>]
uip tm requirements find-obsolete-testcases (--project-key <key> | --project-id <id>) (--requirement-id <uuid> | --requirement-key <key> | --activity-id <uuid>) [--instructions <text>] [--attachment-ids <uuid...>] [--wait] [--unlink | --delete --yes] [--select <numbers...>] [--timeout <seconds>] [--poll-interval <seconds>]
uip tm requirements list (--project-key <key> | --project-id <id>) [--filter <text>] [--requirement-ids <uuid...>] [--labels <label...>] [--updated-by <user-id>] [--test-case-id <uuid>] [--changed-since <iso-date>] [--sort-by <expression>] [--limit <number>] [--offset <number>]
uip tm requirements get (--project-key <key> | --project-id <id>) (--requirement-id <uuid> | --requirement-key <key>)
uip tm requirements create (--project-key <key> | --project-id <id>) --name <name> [--description <text>] [--container-id <uuid>] [--external-reference <ref>] [--connector-requirement-uuid <uuid>]
uip tm requirements update (--project-key <key> | --project-id <id>) --requirement-id <uuid> [--name <name>] [--description <text>]
uip tm requirements delete (--project-key <key> | --project-id <id>) --requirement-ids <uuid...> -y
uip tm requirements export (--project-key <key> | --project-id <id>) --output-file <path> [--requirement-ids <uuid...>] [--updated-by <user-id>] [--test-case-id <uuid>] [--labels <label...>] [--filter <text>] [--sort-by <expression>]
uip tm requirements list-testcase-ids (--project-key <key> | --project-id <id>) --requirement-id <uuid>
uip tm requirements testcases (--project-key <key> | --project-id <id>) --requirement-id <uuid> (--add-testcase-ids <uuid...> | --remove-testcase-ids <uuid...>)
uip tm requirements list-by-test-execution (--project-key <key> | --project-id <id>) --execution-id <uuid> [--labels <label...>] [--updated-by <user-id>] [--filter <text>] [--sort-by <expression>] [--limit <number>] [--offset <number>]
uip tm requirements generate-testcases (--project-key <key> | --project-id <id>) (--requirement-id <uuid> | --requirement-key <key> | --activity-id <uuid>) [--instructions <text>] [--attachment-ids <uuid...>] [--wait] [--create [--select <numbers...>]] [--timeout <seconds>] [--poll-interval <seconds>]
uip tm requirements evaluate (--project-key <key> | --project-id <id>) (--requirement-id <uuid> | --requirement-key <key> | --activity-id <uuid> [--more-suggestions]) [--instructions <text>] [--attachment-ids <uuid...>] [--wait] [--timeout <seconds>] [--poll-interval <seconds>]
uip tm requirements find-obsolete-testcases (--project-key <key> | --project-id <id>) (--requirement-id <uuid> | --requirement-key <key> | --activity-id <uuid>) [--instructions <text>] [--attachment-ids <uuid...>] [--wait] [--unlink | --delete --yes] [--select <numbers...>] [--timeout <seconds>] [--poll-interval <seconds>]

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 server-side filtering.

Arguments​

None.

Options​

FlagDescription
--project-key <key>Project key. Pass this or --project-id.
--project-id <id>Project ID. Use instead of --project-key. When you pass both, --project-id is used.
--filter <text>Search requirements by name or key.
--requirement-ids <uuid...>Space-separated UUIDs to include.
--labels <label...>Space-separated label names to filter by. When supplied alone, uses a label-only fast path.
--updated-by <user-id>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 <iso-date>Return only requirements updated after this ISO-8601 timestamp. A value that is not a valid timestamp is refused before the request. Cannot be combined with --labels or --requirement-ids.
--sort-by <expression>Sort as <field> asc or <field> desc, for example 'name asc'.
--limit <number>Page size. Defaults to 50.
--offset <number>Results to skip. Defaults to 0.

Example​

uip tm requirements list \
  --project-key DEMO \
  --labels "high-priority" \
  --limit 20
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"
    }
  ]
}
{
  "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 and the AI verbs. Id — use in --requirement-id on get, update, delete, list-testcase-ids, testcases, and the AI verbs. 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 exactly one of --requirement-id or --requirement-key.

Arguments​

None.

Options​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--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
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"
  }
}
{
  "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​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--name <name>Required. Requirement name.
--description <text>Free-form description. Defaults to empty. The AI verbs work from this text.
--container-id <uuid>Container UUID to place the requirement in.
--external-reference <ref>External system reference (for example, a Jira issue key).
--connector-requirement-uuid <uuid>UUID that identifies the requirement in the linked connector system. Must be a valid UUID; the server rejects free-form strings.

Example​

uip tm requirements create \
  --project-key DEMO \
  --name "User must be able to log in" \
  --external-reference "JIRA-123"
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"
  }
}
{
  "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's name or description. Pass at least one of --name or --description.

Arguments​

None.

Options​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--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"
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"
  }
}
{
  "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.

Arguments​

None.

Options​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--requirement-ids <uuid...>Required. Requirement UUIDs to delete (space-separated). Pass a single UUID to delete one requirement.
-y, --yesRequired. Confirm this irreversible operation. The CLI never prompts; without --yes the command returns Result: "Failure" and exits 1.

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
# 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 }
}
{
  "Code": "RequirementDelete",
  "Data": { "Passed": 2, "Failed": 0 }
}

uip tm requirements export​

Export requirements to an .xlsx file. Takes the filter flags of requirements list except --changed-since, and has no paging flags.

Arguments​

None.

Options​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--output-file <path>Required. Path to write the export file. An empty path is refused.
--requirement-ids <uuid...>Filter by requirement UUIDs, space-separated.
--updated-by <user-id>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, space-separated.
--filter <text>Search by name or key.
--sort-by <expression>Sort as <field> asc or <field> desc, for example 'name asc'.

Example​

uip tm requirements export \
  --project-key DEMO \
  --output-file ./requirements-export.xlsx
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" }
}
{
  "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​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--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
uip tm requirements list-testcase-ids \
  --project-key DEMO \
  --requirement-id a1b2c3d4-0000-0000-0000-000000000001

Data shape​

{
  "Code": "RequirementTestCaseIdsList",
  "Data": { "TestCaseIds": ["b2c3d4e5-0000-0000-0000-000000000001", "c3d4e5f6-0000-0000-0000-000000000001"] }
}
{
  "Code": "RequirementTestCaseIdsList",
  "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; they are mutually exclusive.

Arguments​

None.

Options​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--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
# 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": "RequirementAssignTestCases", "Data": { "Id": "a1b2c3d4-...", "Assigned": 2, "Result": "Assigned" } }
{ "Code": "RequirementAssignTestCases", "Data": { "Id": "a1b2c3d4-...", "Assigned": 2, "Result": "Assigned" } }

Data shape — detach​

{ "Code": "RequirementUnassignTestCases", "Data": { "Id": "a1b2c3d4-...", "Unassigned": 1, "Result": "Unassigned" } }
{ "Code": "RequirementUnassignTestCases", "Data": { "Id": "a1b2c3d4-...", "Unassigned": 1, "Result": "Unassigned" } }

uip tm requirements list-by-test-execution​

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

Arguments​

None.

Options​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--execution-id <uuid>Required. Test execution UUID.
--labels <label...>Filter by label names, space-separated.
--updated-by <user-id>Filter by the user ID who last updated the requirement.
--filter <text>Search requirements by name or key.
--sort-by <expression>Sort as <field> asc or <field> desc, for example 'name asc'.
--limit <number>Page size. Defaults to 50.
--offset <number>Results to skip. Defaults to 0.

Example​

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

Data shape​

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

AI jobs​

generate-testcases, evaluate, and find-obsolete-testcases each start a background job in Test Manager, identified by an ActivityId. Every new job uses AI units.

  • Without --wait, the command returns RequirementId and ActivityId as soon as the job starts. Run the same verb with --activity-id <id> to read the job: a running job returns its Status, and a finished job returns its result. Add --wait to wait for it.
  • With --wait, or a flag that implies it, the CLI checks the job every --poll-interval seconds (default 5) for up to --timeout seconds (default 600). Both take a positive number and are refused when the command does not wait. When the timeout passes first, the command fails with ErrorCode timeout and exits 2; the job can still finish, so read it again with --activity-id.
  • With --activity-id, the requirement comes from the job. A --requirement-id or --requirement-key passed alongside must name the same requirement. --instructions and --attachment-ids are refused with --activity-id. An ActivityId from another verb, or from a job in another project, is refused.
  • The AI works from the requirement's description and any --attachment-ids. Starting a job for a requirement with neither fails, and the error explains how to add a description or find attachment IDs. The CLI checks --attachment-ids against the requirement's own attachments before the job starts; list them with uip tm attachment list --object-type requirement --object-ids <requirement-id>.
  • The project's prompt library holds reusable guidelines that steer these jobs. --instructions adds guidance for a single job.

A finished job ends in one of these statuses:

StatusOutcome
ProcessedSuccess. Data holds the result.
CannotGenerateAdditionalAIArtifactsSuccess with an empty result. Instructions says the AI found nothing to add.
RateLimitReachedFailure, ErrorCode rate_limited. Retry later.
TokenLimitReachedValidationError, ErrorCode invalid_argument. The requirement and its attachments are too large for the AI model.
TooManyImagesValidationError, ErrorCode invalid_argument. The attachments contain too many images.
ExpiredFailure, ErrorCode server_error. The job ran too long and the server stopped it.
FailedFailure, ErrorCode server_error. Data.CanRetry carries the server's retry hint, when it sends one.

On a failed job, Data holds ActivityId, Status, and CanRetry when the server sends it. When a new job can help, Instructions holds the command that starts one with the same inputs; otherwise it says to change the requirement's description or attachments first.

uip tm requirements generate-testcases​

Ask Test Manager's AI to propose test cases for a requirement. The job runs as described in AI jobs. With --create, the CLI creates the proposed test cases in the project, links them to the requirement, and labels them autopilot-generated. Pass --activity-id with --create to create test cases from a job that already ran, without generating again.

Arguments​

None.

Options​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--requirement-id <uuid>Requirement UUID. Exactly one of --requirement-id or --requirement-key is required unless --activity-id is given.
--requirement-key <key>Requirement key (for example, DEMO:1).
--activity-id <uuid>Use this existing job instead of starting a new one: the ActivityId an earlier run printed. Without --wait, prints the job's current status, and its test cases once it has finished. The requirement comes from the job.
--instructions <text>Extra guidance for the AI, for example which paths to focus on. New jobs only; refused with --activity-id.
--attachment-ids <uuid...>Requirement attachment UUIDs to generate from, space-separated. An ID that is not attached to the requirement returns not_found, and no job starts. New jobs only; refused with --activity-id.
--waitWait for the job to finish and print the proposed test cases, each with a Number.
--createCreate the proposed test cases in the project, link them to the requirement, and label them autopilot-generated. Implies --wait. Test cases the web app already created from this job are skipped. The CLI cannot mark the job as used, so the web app can still offer the test cases the CLI creates.
--select <numbers...>With --create: create only the test cases with these Number values, space-separated, for example --select 1 3. Each value must be a whole number from 1 up; repeats are dropped, and a number the job does not have is refused.
--timeout <seconds>Maximum seconds to wait. Defaults to 600. Used with --wait or --create.
--poll-interval <seconds>Seconds between status checks. Defaults to 5. Used with --wait or --create.

Examples​

# Start a job and return its ActivityId
uip tm requirements generate-testcases \
  --project-key DEMO \
  --requirement-key DEMO:1

# Create test cases 1 and 3 from that job, without generating again
uip tm requirements generate-testcases \
  --project-key DEMO \
  --activity-id f1e2d3c4-0000-0000-0000-000000000001 \
  --create \
  --select 1 3
# Start a job and return its ActivityId
uip tm requirements generate-testcases \
  --project-key DEMO \
  --requirement-key DEMO:1

# Create test cases 1 and 3 from that job, without generating again
uip tm requirements generate-testcases \
  --project-key DEMO \
  --activity-id f1e2d3c4-0000-0000-0000-000000000001 \
  --create \
  --select 1 3

Data shape — job started​

{
  "Code": "RequirementGenerateTestCases",
  "Data": {
    "RequirementId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ActivityId": "f1e2d3c4-0000-0000-0000-000000000001"
  }
}
{
  "Code": "RequirementGenerateTestCases",
  "Data": {
    "RequirementId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ActivityId": "f1e2d3c4-0000-0000-0000-000000000001"
  }
}

Data shape — finished, with --create​

{
  "Code": "RequirementGenerateTestCases",
  "Data": {
    "RequirementId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ActivityId": "f1e2d3c4-0000-0000-0000-000000000001",
    "Status": "Processed",
    "TestCases": [
      {
        "Number": 1,
        "Title": "Sign in with valid credentials",
        "Description": "A registered user signs in with a correct password",
        "Steps": [
          { "Action": "Open the sign-in page", "Result": "The form is shown" },
          { "Action": "Enter a valid user name and password and submit", "Result": "The home page is shown" }
        ],
        "Precondition": "The user has an account",
        "Postcondition": "The user is signed in",
        "Labels": ["auth"],
        "Properties": {},
        "IsTestCaseCreated": false
      }
    ],
    "Created": 1,
    "Selected": [1]
  }
}
{
  "Code": "RequirementGenerateTestCases",
  "Data": {
    "RequirementId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ActivityId": "f1e2d3c4-0000-0000-0000-000000000001",
    "Status": "Processed",
    "TestCases": [
      {
        "Number": 1,
        "Title": "Sign in with valid credentials",
        "Description": "A registered user signs in with a correct password",
        "Steps": [
          { "Action": "Open the sign-in page", "Result": "The form is shown" },
          { "Action": "Enter a valid user name and password and submit", "Result": "The home page is shown" }
        ],
        "Precondition": "The user has an account",
        "Postcondition": "The user is signed in",
        "Labels": ["auth"],
        "Properties": {},
        "IsTestCaseCreated": false
      }
    ],
    "Created": 1,
    "Selected": [1]
  }
}

Key fields:

  • TestCases: every test case the job proposed, numbered from 1 in the job's order. --select takes these numbers. Without --create, Data ends here.
  • Created: how many test cases this run created.
  • Selected: the --select numbers, when given.
  • Skipped: numbers of test cases the web app already created from this job, when any.

The create step runs in one transaction. When it fails, nothing is created, Data holds ActivityId and Generated (the number of test cases it tried to create), and Instructions holds the --activity-id … --create command that retries the step without generating again.

uip tm requirements evaluate​

Ask Test Manager's AI to review a requirement's quality and suggest improvements. The job runs as described in AI jobs. The command changes nothing; apply a suggestion with requirements update. To get more suggestions from a finished evaluation, pass its --activity-id with --more-suggestions.

Arguments​

None.

Options​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--requirement-id <uuid>Requirement UUID. Exactly one of --requirement-id or --requirement-key is required unless --activity-id is given.
--requirement-key <key>Requirement key (for example, DEMO:1).
--activity-id <uuid>Read this existing evaluation job instead of starting a new one: the ActivityId an earlier run printed. Without --wait, prints the job's current status, and its suggestions once it has finished.
--more-suggestionsWith --activity-id: run that finished evaluation again with the same inputs. The AI adds new suggestions to the earlier ones, and the run uses AI units like a new evaluation. A job that is still running is refused. Without --wait, prints the new job's ActivityId.
--instructions <text>Extra guidance for the AI, for example what to focus on. New jobs only; refused with --activity-id.
--attachment-ids <uuid...>Requirement attachment UUIDs for the AI to read, space-separated. An ID that is not attached to the requirement returns not_found, and no job starts. New jobs only; refused with --activity-id.
--waitWait for the job to finish and print the suggestions.
--timeout <seconds>Maximum seconds to wait. Defaults to 600. Used with --wait.
--poll-interval <seconds>Seconds between status checks. Defaults to 5. Used with --wait.

Example​

uip tm requirements evaluate \
  --project-key DEMO \
  --requirement-key DEMO:1 \
  --wait
uip tm requirements evaluate \
  --project-key DEMO \
  --requirement-key DEMO:1 \
  --wait

Data shape​

{
  "Code": "RequirementEvaluate",
  "Data": {
    "RequirementId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ActivityId": "f1e2d3c4-0000-0000-0000-000000000001",
    "Status": "Processed",
    "Suggestions": [
      {
        "Title": "Define the reset link lifetime",
        "SuggestiveDescription": "The requirement does not say how long the reset link stays valid.",
        "ActionableDescription": "Add: the reset link expires 30 minutes after it is sent.",
        "State": "TODO"
      }
    ]
  }
}
{
  "Code": "RequirementEvaluate",
  "Data": {
    "RequirementId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ActivityId": "f1e2d3c4-0000-0000-0000-000000000001",
    "Status": "Processed",
    "Suggestions": [
      {
        "Title": "Define the reset link lifetime",
        "SuggestiveDescription": "The requirement does not say how long the reset link stays valid.",
        "ActionableDescription": "Add: the reset link expires 30 minutes after it is sent.",
        "State": "TODO"
      }
    ]
  }
}

Key fields:

  • Suggestions: each with Title, SuggestiveDescription (what is missing), ActionableDescription (the proposed change), and State (TODO, INWORK, or DONE).
  • Added: with --more-suggestions, the number of suggestions the new run added. Suggestions then lists the earlier and the new ones together.

uip tm requirements find-obsolete-testcases​

Ask Test Manager's AI which of the test cases linked to a requirement look obsolete. The job runs as described in AI jobs. The requirement needs linked test cases, and a description or --attachment-ids.

On its own the command changes nothing. Add --unlink to remove the flagged test cases from the requirement, or --delete --yes to delete them, and --select to act on only some. The CLI acts only on flagged test cases that are linked to the requirement when the action runs; it lists the others under NotLinked and adds a Warning.

Arguments​

None.

Options​

FlagDescription
--project-key <key>Owning project key. Pass this or --project-id.
--project-id <id>Owning project ID. Use instead of --project-key. When you pass both, --project-id is used.
--requirement-id <uuid>Requirement UUID. Exactly one of --requirement-id or --requirement-key is required unless --activity-id is given.
--requirement-key <key>Requirement key (for example, DEMO:1).
--activity-id <uuid>Read this existing obsolete test case search instead of starting a new one: the ActivityId an earlier run printed. Without --wait, prints the job's current status, and the flagged test cases once it has finished.
--instructions <text>Extra guidance for the AI, for example what to focus on. New jobs only; refused with --activity-id.
--attachment-ids <uuid...>Requirement attachment UUIDs for the AI to read, space-separated. An ID that is not attached to the requirement returns not_found, and no job starts. New jobs only; refused with --activity-id.
--waitWait for the job to finish and print the obsolete test cases, each with a Number.
--unlinkRemove the flagged test cases from the requirement. The test cases themselves are kept. Implies --wait. Mutually exclusive with --delete.
--deleteDelete the flagged test cases. Cannot be undone; needs --yes. Implies --wait. Test cases that are already gone are listed under AlreadyDeleted.
--select <numbers...>With --unlink or --delete: act only on the flagged test cases with these Number values, space-separated, for example --select 1 3. A number the job does not have is refused.
-y, --yesRequired with --delete, and refused without it. Confirms the irreversible operation. The CLI never prompts; --delete without --yes returns Result: "Failure" and exits 1 before any job starts.
--timeout <seconds>Maximum seconds to wait. Defaults to 600. Used with --wait, --unlink, or --delete.
--poll-interval <seconds>Seconds between status checks. Defaults to 5. Used with --wait, --unlink, or --delete.

Examples​

# Find obsolete test cases and wait for the result
uip tm requirements find-obsolete-testcases \
  --project-key DEMO \
  --requirement-key DEMO:1 \
  --wait

# Unlink flagged test cases 1 and 2, reusing the finished search
uip tm requirements find-obsolete-testcases \
  --project-key DEMO \
  --activity-id f1e2d3c4-0000-0000-0000-000000000001 \
  --unlink \
  --select 1 2
# Find obsolete test cases and wait for the result
uip tm requirements find-obsolete-testcases \
  --project-key DEMO \
  --requirement-key DEMO:1 \
  --wait

# Unlink flagged test cases 1 and 2, reusing the finished search
uip tm requirements find-obsolete-testcases \
  --project-key DEMO \
  --activity-id f1e2d3c4-0000-0000-0000-000000000001 \
  --unlink \
  --select 1 2

Data shape​

{
  "Code": "RequirementFindObsoleteTestCases",
  "Data": {
    "RequirementId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ActivityId": "f1e2d3c4-0000-0000-0000-000000000001",
    "Status": "Processed",
    "ObsoleteTestCases": [
      {
        "Number": 1,
        "TestCaseId": "c1c2c3c4-0000-0000-0000-000000000001",
        "TestCaseKey": "DEMO:42",
        "Name": "Reset password by SMS",
        "Score": 85,
        "ConfidenceLevel": "High",
        "Criteria": ["The requirement no longer mentions SMS reset"],
        "Summary": "Covers a reset channel the requirement dropped.",
        "IsDeleted": false
      },
      {
        "Number": 2,
        "TestCaseId": "c1c2c3c4-0000-0000-0000-000000000002",
        "TestCaseKey": "DEMO:43",
        "Name": "Reset password by security question",
        "Score": 78,
        "ConfidenceLevel": "High",
        "Criteria": ["The requirement no longer mentions security questions"],
        "Summary": "Covers a reset channel the requirement dropped.",
        "IsDeleted": false
      }
    ],
    "Unlinked": [1, 2],
    "Selected": [1, 2]
  }
}
{
  "Code": "RequirementFindObsoleteTestCases",
  "Data": {
    "RequirementId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ActivityId": "f1e2d3c4-0000-0000-0000-000000000001",
    "Status": "Processed",
    "ObsoleteTestCases": [
      {
        "Number": 1,
        "TestCaseId": "c1c2c3c4-0000-0000-0000-000000000001",
        "TestCaseKey": "DEMO:42",
        "Name": "Reset password by SMS",
        "Score": 85,
        "ConfidenceLevel": "High",
        "Criteria": ["The requirement no longer mentions SMS reset"],
        "Summary": "Covers a reset channel the requirement dropped.",
        "IsDeleted": false
      },
      {
        "Number": 2,
        "TestCaseId": "c1c2c3c4-0000-0000-0000-000000000002",
        "TestCaseKey": "DEMO:43",
        "Name": "Reset password by security question",
        "Score": 78,
        "ConfidenceLevel": "High",
        "Criteria": ["The requirement no longer mentions security questions"],
        "Summary": "Covers a reset channel the requirement dropped.",
        "IsDeleted": false
      }
    ],
    "Unlinked": [1, 2],
    "Selected": [1, 2]
  }
}

Key fields:

  • ObsoleteTestCases: every flagged test case, numbered from 1. IsDeleted is true once the test case has been deleted. Without --unlink or --delete, Data ends here.
  • Unlinked or Deleted: numbers of the test cases this run unlinked or deleted.
  • AlreadyDeleted: numbers of test cases that were already gone when --delete ran.
  • Skipped: numbers of flagged test cases already marked deleted, which the action leaves alone.
  • NotLinked: numbers of flagged test cases not linked to the requirement, which the action leaves alone.
  • Selected: the --select numbers, when given.

--delete deletes test cases one at a time and continues after a failure. When any deletion fails, the command fails and Data holds ActivityId, Deleted, AlreadyDeleted, and Failed (each entry with Number, TestCaseKey, and Message); Instructions holds the command that retries only the failed ones.

  • 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.
  • attachment — requirement attachments passed to the AI verbs with --attachment-ids.
  • prompts — the project prompt library that steers the AI verbs.

See also​

Was this page helpful?

Connect

Need help? Support(opens in new window)

Want to learn? UiPath Academy(opens in new window)

Have questions? UiPath Forum(opens in new window)

Stay updated