# uip tm defects

> Syntax and options for `uip tm defects`, which raises defects from failed test case results, updates and deletes them, reads what they link to, and downloads their evidence.

`uip tm defects` manages defects in a Test Manager project. A defect is a bug raised from a failed test case result in an execution and synced to the project's external defect tracker, such as Jira or Azure DevOps. Each defect stays linked to the [test case log](./uip-test-manager-testcaselog.md) it was raised from.

Test Manager syncs a new defect to the tracker in the background. `SyncStatus` reports where that stands: `None`, `InProgress`, `Success`, or `Failed`. Changes you make with `update` stay in Test Manager and are not pushed to the tracker.

## Synopsis

```text
uip tm defects list (--project-key <key> | --project-id <id>) [--changed-since <iso-date>] [--sort-by <expression>] [--limit <number>] [--offset <number>]
uip tm defects get (--project-key <key> | --project-id <id>) --defect-id <uuid>
uip tm defects create (--project-key <key> | --project-id <id>) --execution-id <uuid> (--test-case-id <uuid> | --test-case-key <key>) [--variation-id <id>] [--detail-link <url>]
uip tm defects update (--project-key <key> | --project-id <id>) --defect-id <uuid> [--status <text>] [--priority <text>] [--external-reference <ref>] [--external-link <url>]
uip tm defects delete (--project-key <key> | --project-id <id>) --defect-id <uuid> --yes
uip tm defects get-related (--project-key <key> | --project-id <id>) --defect-id <uuid> --object-type <type>
uip tm defects get-external-issue (--project-key <key> | --project-id <id>) --defect-id <uuid>
uip tm defects attachments list (--project-key <key> | --project-id <id>) --defect-id <uuid> [--sort-by <expression>] [--limit <number>] [--offset <number>]
uip tm defects attachments download (--project-key <key> | --project-id <id>) --defect-id <uuid> --attachment-id <id> [--result-path <path>] [--output-file <path>] [--overwrite]
```

All verbs honor the [global options](./global-options.md) and the standard [exit codes](./exit-codes.md).

## uip tm defects list

List the defects in a project, one page at a time. The server has no name or status filter; narrow the result with `--changed-since`.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--changed-since <iso-date>` | Return only defects updated after this ISO-8601 timestamp, for example `2026-04-01T00:00:00Z`. A value that is not a valid timestamp is refused before the request. |
| `--sort-by <expression>` | Sort as `<Property> asc` or `<Property> desc`, for example `'Updated desc'`. Without it the server returns rows in no fixed order, so pass it when you page with `--offset`. |
| `--limit <number>` | Rows per page, from `1` to `100`. Defaults to `50`. |
| `--offset <number>` | Rows to skip. Defaults to `0`. |

### Example

```bash
uip tm defects list \
  --project-key DEMO \
  --changed-since 2026-04-01T00:00:00Z \
  --sort-by "Updated desc" \
  --limit 20
```

### Data shape

```json
{
  "Code": "DefectsList",
  "Data": [
    {
      "Id": "d1e2f3a4-0000-0000-0000-000000000001",
      "Name": "Login with valid credentials — Failed",
      "Description": "Start time: 2026-04-15 10:30:00 ...",
      "Status": "To Do",
      "Priority": "High",
      "Link": "https://example.atlassian.net/browse/QA-123",
      "LinkLabel": "QA-123",
      "SyncStatus": "Success",
      "Created": "2026-04-15T10:30:00Z",
      "CreatedBy": "11111111-2222-3333-4444-555555555555",
      "Updated": "2026-04-15T10:31:00Z",
      "UpdatedBy": "11111111-2222-3333-4444-555555555555"
    }
  ]
}
```

Key fields:

- `Link`, `LinkLabel`: URL and key of the issue in the external tracker. Both are absent until the defect is synced or linked by hand with `update`.
- `SyncStatus`: `None`, `InProgress`, `Success`, or `Failed`.

## uip tm defects get

Get one defect by its UUID.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--defect-id <uuid>` | **Required.** Defect UUID. |

### Example

```bash
uip tm defects get \
  --project-key DEMO \
  --defect-id d1e2f3a4-0000-0000-0000-000000000001
```

### Data shape

```json
{
  "Code": "DefectGet",
  "Data": {
    "Id": "d1e2f3a4-0000-0000-0000-000000000001",
    "Name": "Login with valid credentials — Failed",
    "Description": "Start time: 2026-04-15 10:30:00 ...",
    "Status": "To Do",
    "Priority": "High",
    "Link": "https://example.atlassian.net/browse/QA-123",
    "LinkLabel": "QA-123",
    "SyncStatus": "Success",
    "Created": "2026-04-15T10:30:00Z",
    "CreatedBy": "11111111-2222-3333-4444-555555555555",
    "Updated": "2026-04-15T10:31:00Z",
    "UpdatedBy": "11111111-2222-3333-4444-555555555555"
  }
}
```

## uip tm defects create

Raise a defect from a test case's result in an execution. Test Manager writes the defect name and description from the result, then syncs the defect to the project's defect tracker in the background, so the response usually shows `SyncStatus` `InProgress`.

One result carries one defect. A second `create` for the same result fails while its defect is `InProgress` or `Success`. When the defect's `SyncStatus` is `Failed`, run `create` again to retry the sync.

:::note
With no tracker connected, the defect stays `InProgress`. Link it to an issue by hand with [`defects update`](#uip-tm-defects-update) `--external-reference` and `--external-link`.
:::

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--execution-id <uuid>` | **Required.** Test execution UUID the result belongs to. |
| `--test-case-id <uuid>` | Test case UUID. Exactly one of `--test-case-id` or `--test-case-key` is required. |
| `--test-case-key <key>` | Test case key, for example `DEMO:7`. A key with no matching test case in the project returns `ErrorCode` `not_found`. |
| `--variation-id <id>` | Data variation ID, for a data-driven test case with several results in the execution. |
| `--detail-link <url>` | Link to the result in Test Manager, written into the defect description. |

### Example

```bash
uip tm defects create \
  --project-key DEMO \
  --execution-id b2c3d4e5-0000-0000-0000-000000000001 \
  --test-case-key DEMO:7
```

### Data shape

```json
{
  "Code": "DefectCreate",
  "Data": {
    "Id": "d1e2f3a4-0000-0000-0000-000000000001",
    "Name": "Login with valid credentials — Failed",
    "Description": "Start time: 2026-04-15 10:30:00 ...",
    "Status": "To Do",
    "Priority": "High",
    "SyncStatus": "InProgress",
    "Created": "2026-04-15T10:30:00Z",
    "CreatedBy": "11111111-2222-3333-4444-555555555555",
    "Updated": "2026-04-15T10:31:00Z",
    "UpdatedBy": "11111111-2222-3333-4444-555555555555"
  }
}
```

## uip tm defects update

Update a defect's status, priority, or external tracker link. These are the only fields Test Manager lets you change. The change stays in Test Manager and is not pushed to the tracker. Setting `--external-reference` or `--external-link` marks the defect synced. Pass at least one of the four field flags.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--defect-id <uuid>` | **Required.** Defect UUID. |
| `--status <text>` | New status, as free text, for example `'In Progress'`. |
| `--priority <text>` | New priority, as free text, for example `'High'`. |
| `--external-reference <ref>` | Issue key in the external tracker, for example `QA-123`. Stored as `LinkLabel`. |
| `--external-link <url>` | URL of the issue in the tracker. Stored as `Link`. |

### Example

```bash
uip tm defects update \
  --project-key DEMO \
  --defect-id d1e2f3a4-0000-0000-0000-000000000001 \
  --external-reference QA-123 \
  --external-link https://example.atlassian.net/browse/QA-123
```

### Data shape

```json
{
  "Code": "DefectUpdate",
  "Data": {
    "Id": "d1e2f3a4-0000-0000-0000-000000000001",
    "Name": "Login with valid credentials — Failed",
    "Status": "To Do",
    "Priority": "High",
    "Link": "https://example.atlassian.net/browse/QA-123",
    "LinkLabel": "QA-123",
    "SyncStatus": "Success"
  }
}
```

`Data` is the full defect after the update, with the same fields as [`get`](#uip-tm-defects-get).

## uip tm defects delete

Permanently delete a defect and unlink it from its test case result. The issue in the external tracker is not deleted.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--defect-id <uuid>` | **Required.** Defect UUID. |
| `-y, --yes` | **Required.** Confirms the irreversible operation. The CLI never prompts; without `--yes` the command returns `Result: "Failure"` and exits `1`. |

### Example

```bash
uip tm defects delete \
  --project-key DEMO \
  --defect-id d1e2f3a4-0000-0000-0000-000000000001 \
  --yes
```

### Data shape

```json
{
  "Code": "DefectDelete",
  "Data": {
    "Id": "d1e2f3a4-0000-0000-0000-000000000001",
    "Result": "Deleted"
  }
}
```

## uip tm defects get-related

Get an object a defect links to, picked by `--object-type`. The command fails with `not_found` when no result is linked to the defect any more.

| `--object-type` | Returns | `Code` |
|---|---|---|
| `TestCase` | The test case the defect was raised against. | `DefectTestCaseGet` |
| `TestExecution` | The execution the defect was raised in. | `DefectExecutionGet` |
| `TestCaseLog` | The [test case log](./uip-test-manager-testcaselog.md) (result) the defect came from. | `DefectTestCaseLogGet` |
| `Requirement` | The requirements that cover that test case, as a list. | `DefectRequirementsList` |

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--defect-id <uuid>` | **Required.** Defect UUID. |
| `--object-type <type>` | **Required.** Linked object to return: `TestCase`, `TestExecution`, `TestCaseLog`, or `Requirement`. |

### Example

```bash
uip tm defects get-related \
  --project-key DEMO \
  --defect-id d1e2f3a4-0000-0000-0000-000000000001 \
  --object-type TestCaseLog
```

### Data shape

```json
{
  "Code": "DefectTestCaseLogGet",
  "Data": {
    "Id": "f1f1f1f1-0000-0000-0000-000000000001",
    "Result": "Failed",
    "DefectId": "d1e2f3a4-0000-0000-0000-000000000001"
  }
}
```

With `--object-type Requirement`, `Data` is an array:

```json
{
  "Code": "DefectRequirementsList",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000001",
      "ObjKey": "DEMO:1",
      "Name": "Login flow"
    }
  ]
}
```

Each object carries the same fields as the matching read: [`testcases get`](./uip-test-manager-testcases.md#uip-tm-testcases-get), [`testcaselog get`](./uip-test-manager-testcaselog.md#uip-tm-testcaselog-get), and [`requirements get`](./uip-test-manager-requirements.md#uip-tm-requirements-get).

## uip tm defects get-external-issue

Show the external tracker issue a defect is synced to. `Synchronized` is `false`, and the key and link are absent, until the tracker has created the issue.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--defect-id <uuid>` | **Required.** Defect UUID. |

### Example

```bash
uip tm defects get-external-issue \
  --project-key DEMO \
  --defect-id d1e2f3a4-0000-0000-0000-000000000001
```

### Data shape

```json
{
  "Code": "DefectExternalIssueGet",
  "Data": {
    "Id": "e1e1e1e1-0000-0000-0000-000000000001",
    "ExternalKey": "QA-123",
    "ExternalLink": "https://example.atlassian.net/browse/QA-123",
    "DefectId": "d1e2f3a4-0000-0000-0000-000000000001",
    "Synchronized": true
  }
}
```

## uip tm defects attachments list

List the attachments on a defect: the screenshots and step attachments taken from the result it was raised from.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--defect-id <uuid>` | **Required.** Defect UUID. |
| `--sort-by <expression>` | Sort expression, for example `'fileName asc'`. |
| `--limit <number>` | Rows per page, from `1` to `100`. Defaults to `50`. |
| `--offset <number>` | Rows to skip. Defaults to `0`. |

### Example

```bash
uip tm defects attachments list \
  --project-key DEMO \
  --defect-id d1e2f3a4-0000-0000-0000-000000000001
```

### Data shape

```json
{
  "Code": "DefectAttachmentsList",
  "Data": [
    {
      "Id": "a7a7a7a7-0000-0000-0000-000000000001",
      "FileName": "screenshot_1.jpg"
    }
  ]
}
```

Pass `Id` to `attachments download` as `--attachment-id`.

## uip tm defects attachments download

Download one defect attachment. The file is saved under the server's file name inside `--result-path`, or to the exact path in `--output-file`. When the target file already exists, the command refuses and writes nothing unless you pass `--overwrite`. A target path that is a directory is always refused.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Test Manager project key. One of `--project-key` or `--project-id` is required. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Test Manager project ID. Use instead of `--project-key`; wins if both are given. |
| `--defect-id <uuid>` | **Required.** Defect UUID. |
| `--attachment-id <id>` | **Required.** Attachment ID from [`attachments list`](#uip-tm-defects-attachments-list): a UUID, or a number for Orchestrator screenshots. |
| `--result-path <path>` | Output directory. Defaults to the current directory. When the server's file name is empty, starts with a dot, or is a Windows device name, the file is named after the attachment ID. |
| `--output-file <path>` | Exact path to write, overriding `--result-path`. Parent directories are created. `FileName` in the output is then the basename of this path. |
| `--overwrite` | Replace the file if it already exists. |

### Example

```bash
uip tm defects attachments download \
  --project-key DEMO \
  --defect-id d1e2f3a4-0000-0000-0000-000000000001 \
  --attachment-id a7a7a7a7-0000-0000-0000-000000000001 \
  --result-path ./evidence
```

### Data shape

```json
{
  "Code": "DefectAttachmentDownload",
  "Data": {
    "DefectId": "d1e2f3a4-0000-0000-0000-000000000001",
    "AttachmentId": "a7a7a7a7-0000-0000-0000-000000000001",
    "FileName": "screenshot_1.jpg",
    "OutputPath": "evidence/screenshot_1.jpg",
    "Size": 20480
  }
}
```

`Size` is the number of bytes written.

## Related

- [testcaselog](./uip-test-manager-testcaselog.md): the test case results that defects are raised from.
- [executions](./uip-test-manager-executions.md): source of the `--execution-id` used by `create`.
- [requirements](./uip-test-manager-requirements.md): requirements returned by `get-related --object-type Requirement`.

## See also

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