UiPath Documentation
uipath-cli
latest
false

UiPath CLI user guide

uip tm executions

uip tm executions inspects and manipulates test executions — the objects produced by uip tm testsets run or uip tm executions run. Use these verbs to start, list, and filter executions; get execution statistics; enumerate the test case logs of a finished run; and retry only the failed cases in place.

Both uip tm testsets run and uip tm executions run start an execution and return an ExecutionId. Every other verb on this page takes that ID (or derives it from context).

Synopsis​

uip tm executions list --project-key <key> --test-set-id <uuid> [filters…]
uip tm executions get-stats --execution-id <uuid> --project-key <key>
uip tm executions run --test-set-key <key> [--execution-type <type>] [--folder-key <uuid>]
uip tm executions list-filtered --project-key <key> [filters…]
uip tm executions testcaselogs list --execution-id <uuid> --project-key <key> [filters…]
uip tm executions retry --execution-id <uuid> (--project-key <key> | --test-set-key <key>) [--execution-type <type>]
uip tm executions list --project-key <key> --test-set-id <uuid> [filters…]
uip tm executions get-stats --execution-id <uuid> --project-key <key>
uip tm executions run --test-set-key <key> [--execution-type <type>] [--folder-key <uuid>]
uip tm executions list-filtered --project-key <key> [filters…]
uip tm executions testcaselogs list --execution-id <uuid> --project-key <key> [filters…]
uip tm executions retry --execution-id <uuid> (--project-key <key> | --test-set-key <key>) [--execution-type <type>]

All verbs honor the global options and the standard exit codes. Every verb accepts -t, --tenant <name> and --log-level <level> (default Information).

uip tm executions list​

List the executions associated with a test set. Filters are applied server-side; the CLI returns one page per call, sized by --top / --skip.

Arguments​

None.

Options​

  • --project-key <key> (required) — owning project.
  • --test-set-id <uuid> (required) — test set UUID (the Id field from testsets list, not TestSetKey).
  • --filter <text> — search executions by name.
  • --status <status> — filter by execution status. Accepted values come from the SDK TestExecutionStatus enum.
  • --execution-type <type> — filter by execution type. Accepted values come from the SDK ExecutionType enum (automated, manual, mixed, none).
  • --execution-finished-interval <interval> — filter by how recently the execution finished. Accepted values come from the SDK TestExecutionFinishedInterval enum.
  • --top <number> — page size. Defaults to 50.
  • --skip <number> — results to skip. Defaults to 0.
Note:

The exact enum values accepted by --status, --execution-type, and --execution-finished-interval are generated from the Test Manager SDK at runtime. Run uip tm executions list --help to see the current set for your installed tool version.

Example​

uip tm executions list \
  --project-key DEMO \
  --test-set-id a1b2c3d4-0000-0000-0000-000000000001 \
  --top 2
uip tm executions list \
  --project-key DEMO \
  --test-set-id a1b2c3d4-0000-0000-0000-000000000001 \
  --top 2

Data shape​

{
  "Code": "ExecutionsList",
  "Data": [
    {
      "Id": "b2c3d4e5-0000-0000-0000-000000000001",
      "Name": "Nightly Run 2025-04-15",
      "Status": "Passed"
    },
    {
      "Id": "b2c3d4e5-0000-0000-0000-000000000002",
      "Name": "Nightly Run 2025-04-14",
      "Status": "Failed"
    }
  ]
}
{
  "Code": "ExecutionsList",
  "Data": [
    {
      "Id": "b2c3d4e5-0000-0000-0000-000000000001",
      "Name": "Nightly Run 2025-04-15",
      "Status": "Passed"
    },
    {
      "Id": "b2c3d4e5-0000-0000-0000-000000000002",
      "Name": "Nightly Run 2025-04-14",
      "Status": "Failed"
    }
  ]
}

uip tm executions get-stats​

Retrieve summary statistics for a single execution: total count, passed, failed, skipped, and execution status. Useful for CI scripts that need a quick pass/fail verdict without downloading the full JUnit report.

executions get-stats is the lightweight alternative to report get. Use report get when you need named failed cases and pass rate; use get-stats when you only need the numeric totals.

Arguments​

None.

Options​

  • --execution-id <uuid> (required) — execution to query.
  • --project-key <key> (required) — owning project.

Example​

uip tm executions get-stats \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001 \
  --project-key DEMO
uip tm executions get-stats \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001 \
  --project-key DEMO

Data shape​

{
  "Code": "ExecutionStats",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Status": "Finished",
    "Total": 10,
    "Passed": 8,
    "Failed": 2,
    "Skipped": 0
  }
}
{
  "Code": "ExecutionStats",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Status": "Finished",
    "Total": 10,
    "Passed": 8,
    "Failed": 2,
    "Skipped": 0
  }
}

A zero Failed count means the execution passed cleanly. Exit code is always 0 on a successful API call — the script must inspect the Failed field to decide whether to fail the build.

uip tm executions run​

Start a new execution for a test set. This is the primary way to trigger a test run from the executions resource. It is equivalent to uip tm testsets run (documented on the testsets page); both verbs start the same underlying execution and return the same ExecutionId.

Note:

uip tm testsets run is the canonical verb for the typical CI flow. uip tm executions run is provided for scripting contexts where you are already working with execution-level resources.

Arguments​

None.

Options​

  • --test-set-key <key> (required) — test set to run (for example, DEMO:10).
  • --execution-type <type> — execution type: automated (default), manual, mixed, or none.
  • --folder-key <uuid> — Orchestrator folder to run in. Defaults to the test set's configured folder.

Example​

uip tm executions run \
  --test-set-key DEMO:10 \
  --execution-type automated
uip tm executions run \
  --test-set-key DEMO:10 \
  --execution-type automated

Data shape​

{
  "Code": "ExecutionRun",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Status": "Running",
    "StartTime": "2025-04-15T10:30:00Z"
  }
}
{
  "Code": "ExecutionRun",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Status": "Running",
    "StartTime": "2025-04-15T10:30:00Z"
  }
}

Pass ExecutionId to uip tm wait to block until the run finishes.

uip tm executions list-filtered​

List executions with richer server-side filtering than executions list. While executions list requires a specific --test-set-id, list-filtered can query across the entire project and supports multi-value filters.

Arguments​

None.

Options​

  • --project-key <key> (required) — project to query.
  • --test-set-id <uuid> — narrow results to one test set.

Status and type filters:

  • --statuses <statuses...> — space-separated execution statuses to include. Accepted values come from the SDK TestExecutionStatus enum.
  • --execution-types <types...> — space-separated execution types. Accepted values: automated, manual, mixed, none.

Date range:

  • --from-date <datetime> — include only executions started on or after this ISO 8601 datetime (for example, 2025-01-01T00:00:00Z).
  • --to-date <datetime> — include only executions started on or before this ISO 8601 datetime.

Paging:

  • --top <number> — page size. Defaults to 50.
  • --skip <number> — results to skip. Defaults to 0.

Run uip tm executions list-filtered --help to see current enum values.

Example​

uip tm executions list-filtered \
  --project-key DEMO \
  --statuses Failed \
  --from-date 2025-04-01T00:00:00Z
uip tm executions list-filtered \
  --project-key DEMO \
  --statuses Failed \
  --from-date 2025-04-01T00:00:00Z

Data shape​

{
  "Code": "ExecutionsListFiltered",
  "Data": [
    {
      "Id": "b2c3d4e5-0000-0000-0000-000000000001",
      "Name": "Nightly Run 2025-04-15",
      "Status": "Failed",
      "ExecutionType": "automated",
      "StartTime": "2025-04-15T02:00:00Z"
    }
  ]
}
{
  "Code": "ExecutionsListFiltered",
  "Data": [
    {
      "Id": "b2c3d4e5-0000-0000-0000-000000000001",
      "Name": "Nightly Run 2025-04-15",
      "Status": "Failed",
      "ExecutionType": "automated",
      "StartTime": "2025-04-15T02:00:00Z"
    }
  ]
}

uip tm executions testcaselogs list​

List the test case logs produced by a single execution. Each log is one run of one test case, carrying result, status, and timing.

Arguments​

None.

Options​

  • --execution-id <uuid> (required) — execution to inspect.
  • --project-key <key> (required) — owning project.
  • --only-failed — shortcut for "show only failed logs".
  • --filter <text> — search logs by name.
  • --results <results...> — space-separated results to include. Accepted values come from the SDK Result enum.
  • --statuses <statuses...> — space-separated execution statuses. Accepted values come from the SDK TestCaseLogExecutionStatus enum.
  • --duration-period <period> — filter by duration bucket. Accepted values come from the SDK DurationPeriod enum.
  • --top <number> — page size. Defaults to 50.
  • --skip <number> — results to skip. Defaults to 0.

Example​

uip tm executions testcaselogs list \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001 \
  --project-key DEMO \
  --only-failed
uip tm executions testcaselogs list \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001 \
  --project-key DEMO \
  --only-failed

Data shape​

{
  "Code": "ExecutionTestCaseLogs",
  "Data": [
    {
      "Id": "c3d4e5f6-0000-0000-0000-000000000001",
      "TestCaseName": "Login flow",
      "Status": "Finished",
      "Result": "Failed"
    }
  ]
}
{
  "Code": "ExecutionTestCaseLogs",
  "Data": [
    {
      "Id": "c3d4e5f6-0000-0000-0000-000000000001",
      "TestCaseName": "Login flow",
      "Status": "Finished",
      "Result": "Failed"
    }
  ]
}

Each Id in the output is a test case log UUID. Feed it to uip tm testcaselogs list-assertions to see why a test case log was marked Failed.

uip tm executions retry​

Retry only the failed test cases of a completed execution, in place. The command:

  1. Fetches the execution's stats and refuses to proceed unless the run is in a terminal state (otherwise it exits 1 with a guidance message).
  2. If there are zero failed cases, prints a Message envelope and exits 0 — this is intentionally not an error.
  3. Otherwise collects every failed test case log ID (paged) and kicks off a retry that targets only those logs.

The retry reuses the same execution ID; it does not create a new one.

Arguments​

None.

Options​

  • --execution-id <uuid> (required) — execution to retry.
  • --project-key <key> — owning project. Either this or --test-set-key is required.
  • --test-set-key <key> — test set key (for example, DEMO:42); the project key is derived from the prefix.
  • --execution-type <type> — execution type for the retry: automated (default), manual, mixed, or none.

Example​

uip tm executions retry \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001 \
  --project-key DEMO
uip tm executions retry \
  --execution-id a1b2c3d4-0000-0000-0000-000000000001 \
  --project-key DEMO

Data shape — when there are failures to retry:

{
  "Code": "ExecutionRetry",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Status": "Running",
    "StartTime": "2025-04-15T10:30:00Z",
    "RetriedCount": 3
  }
}
{
  "Code": "ExecutionRetry",
  "Data": {
    "ExecutionId": "a1b2c3d4-0000-0000-0000-000000000001",
    "Status": "Running",
    "StartTime": "2025-04-15T10:30:00Z",
    "RetriedCount": 3
  }
}

When there are no failures to retry:

{
  "Code": "ExecutionRetry",
  "Data": {
    "Message": "Execution 'a1b2c3d4-0000-0000-0000-000000000001' has no failed test cases to retry."
  }
}
{
  "Code": "ExecutionRetry",
  "Data": {
    "Message": "Execution 'a1b2c3d4-0000-0000-0000-000000000001' has no failed test cases to retry."
  }
}

Exit codes​

All uip tm executions … verbs follow the standard exit codes — 0 on success (even when retry finds nothing to retry), 1 on generic failure, 2 on authentication failure, 3 on validation error.

The Test Manager run lifecycle adds one behavior worth calling out explicitly, and it lives on wait, not on the execution verbs themselves:

Distinguishing "timed out" from "finished with failures"​

There is no single tm verb that exits non-zero because tests failed. The standard CI pattern is a three-step pipeline:

  1. Launch — uip tm testsets run returns an ExecutionId and exits 0 as soon as the run is queued.
  2. Block — uip tm wait --execution-id <id> --timeout <seconds> polls until the execution reaches a terminal state.
    • Exits 0 when the execution finished (regardless of pass/fail — "finished" is the success signal here).
    • Exits 2 on --timeout expiry. This is domain-specific: the shared contract reserves 2 for AuthenticationError, but wait reuses it for TimeoutError so scripts can branch on "took too long" without parsing text. See the note on this under uip tm wait exit codes.
    • Exits 1 on API failure, interrupt, or abort.
  3. Verdict — uip tm report get --execution-id <id> reads Passed / Failed / Skipped / PassRate. Your script decides what a pass looks like and fails the build explicitly (for example, exit 1 when Failed > 0). report get itself exits 0 whenever it successfully produces the summary, regardless of the outcome of the run it is summarizing.
# Start the run
id=$(uip tm testsets run --test-set-key DEMO:10 --output-filter .Data.ExecutionId)

# Block with a timeout; branch on the outcome
if ! uip tm wait --execution-id "$id" --timeout 1800; then
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "timed out" >&2
    exit 2
  fi
  echo "wait failed ($code)" >&2
  exit "$code"
fi

# Decide pass/fail from the summary
failed=$(uip tm report get --execution-id "$id" --project-key DEMO --output-filter .Data.Failed)
if [ "$failed" -gt 0 ]; then
  echo "$failed test case(s) failed" >&2
  exit 1
fi
echo "all passed"
# Start the run
id=$(uip tm testsets run --test-set-key DEMO:10 --output-filter .Data.ExecutionId)

# Block with a timeout; branch on the outcome
if ! uip tm wait --execution-id "$id" --timeout 1800; then
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "timed out" >&2
    exit 2
  fi
  echo "wait failed ($code)" >&2
  exit "$code"
fi

# Decide pass/fail from the summary
failed=$(uip tm report get --execution-id "$id" --project-key DEMO --output-filter .Data.Failed)
if [ "$failed" -gt 0 ]; then
  echo "$failed test case(s) failed" >&2
  exit 1
fi
echo "all passed"
  • testsets run — start an execution.
  • wait — block until an execution reaches a terminal state.
  • report, result, attachment — post-run artifacts.
  • testcases — testcaselogs list-assertions turns a failed log into per-assertion detail.

See also​

Was this page helpful?

Connect

Need help? Support

Want to learn? UiPath Academy

Have questions? UiPath Forum

Stay updated