# uip tm migration

> Syntax and options for `uip tm migration`, which checks and downloads the migration jobs behind project export and import, and lists the .tmh package schemas Test Manager accepts.

`uip tm migration` reads the background jobs that [`uip tm project export`](./uip-test-manager-project.md#uip-tm-project-export) and [`uip tm project import`](./uip-test-manager-project.md#uip-tm-project-import) start. Test Manager runs every project export and import as a migration job and sends no completion notification, so you poll the job for its status. A finished export job holds the `.tmh` package until you download it.

An export started without `--wait` returns the job `Id`. [`migration get`](#uip-tm-migration-get) reports the job status, and once `Status` reads `Completed`, [`migration download`](#uip-tm-migration-download) writes the package. [`migration list`](#uip-tm-migration-list) finds a job whose ID you no longer have. `Completed`, `Failed`, and `Cancelled` are terminal; any other status means the job is still in progress. `ExecutionStarted` is absent until Test Manager starts processing the job.

`Status` and `Type` come back in PascalCase (`Completed`, `ExportProject`). The `--status` and `--type` filters of `migration list` take camelCase values (`completed`, `exportProject`).

The `schemas` verbs list and download the `.tmh` package schema versions that Test Manager accepts, so you can check a package before you import it.

## Synopsis

```text
uip tm migration get (--project-key <key> | --project-id <id>) --job-id <uuid>
uip tm migration download (--project-key <key> | --project-id <id>) --job-id <uuid> --output-file <path> [--overwrite]
uip tm migration list [--project-key <key> | --project-id <id>] [--status <status>] [--type <type>] [--package-name <name>] [--filter <text>] [--sort-by <expression>] [--limit <number>] [--offset <number>]
uip tm migration schemas list
uip tm migration schemas download --schema-version <version> --output-file <path> [--overwrite]
```

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

## uip tm migration get

Get a migration job by ID. The job must belong to the project you name; a job from another project returns `not_found`, the same as a job that does not exist.

### 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. |
| `--job-id <uuid>` | **Required.** Migration job UUID, the `Id` that `project export` or `project import` returns. |

### Example

```bash
uip tm migration get \
  --project-id a1b2c3d4-0000-0000-0000-000000000001 \
  --job-id e5f6a7b8-0000-0000-0000-000000000001
```

### Data shape

```json
{
  "Code": "MigrationJobGet",
  "Data": {
    "Id": "e5f6a7b8-0000-0000-0000-000000000001",
    "Type": "ExportProject",
    "Status": "Processing",
    "SchemaVersion": "1.0.18",
    "PackageName": "DEMO.tmh",
    "PackageSize": 481203,
    "Created": "2026-09-17T10:00:00.000Z",
    "Updated": "2026-09-17T10:00:12.000Z",
    "ExecutionStarted": "2026-09-17T10:00:05.000Z",
    "CreatedBy": "c3d4e5f6-0000-0000-0000-000000000003",
    "UpdatedBy": "c3d4e5f6-0000-0000-0000-000000000003",
    "ProjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "TenantId": "d4e5f6a7-0000-0000-0000-000000000004"
  }
}
```

Fields without a value are left out of `Data`. For example, `ExecutionFinished` appears once the job ends.

## uip tm migration download

Download the `.tmh` package of an export job that already finished, without exporting again. The job must be an export job in the project you name, with `Status` `Completed`. Any other job is refused and nothing is written.

Test Manager can also refuse the package of a `Completed` job, for example when the package has expired or the job was a partial export. A failed or interrupted download leaves no partial file at `--output-file`.

### 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. |
| `--job-id <uuid>` | **Required.** Export job UUID. |
| `--output-file <path>` | **Required.** Where to write the package. The parent directory must exist. |
| `--overwrite` | Replace `--output-file` if it already exists. Without it, an existing file is refused and nothing is written. |

### Example

```bash
uip tm migration download \
  --project-id a1b2c3d4-0000-0000-0000-000000000001 \
  --job-id e5f6a7b8-0000-0000-0000-000000000001 \
  --output-file demo.tmh
```

### Data shape

```json
{
  "Code": "MigrationJobDownload",
  "Data": {
    "JobId": "e5f6a7b8-0000-0000-0000-000000000001",
    "OutputFile": "demo.tmh",
    "Bytes": 481203
  }
}
```

`Bytes` is the size of the file written.

## uip tm migration list

List migration jobs, newest first, to find a job whose ID you no longer have. Without `--project-key` or `--project-id`, the list covers the whole tenant, including projects you have no role on. With either flag, the list holds only that project's jobs.

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--project-key <key>` | Only jobs for this project. Optional. Ignored if `--project-id` is also given. |
| `--project-id <id>` | Only jobs for this project ID. Use instead of `--project-key`; wins if both are given. |
| `--status <status>` | Filter by job status: `none`, `created`, `uploading`, `ready`, `queued`, `processing`, `completed`, `failed`, or `cancelled`. |
| `--type <type>` | Filter by job type: `importProject` or `exportProject`. |
| `--package-name <name>` | Filter by the whole package name. |
| `--filter <text>` | Substring match on the package name. |
| `--sort-by <expression>` | Sort as `<property> asc` or `<property> desc`, for example `'updated asc'`. Defaults to `created desc`. |
| `--limit <number>` | Maximum jobs to return. Defaults to `50`. |
| `--offset <number>` | Jobs to skip. Defaults to `0`. |

### Example

```bash
uip tm migration list \
  --project-key DEMO \
  --type exportProject \
  --limit 10
```

### Data shape

```json
{
  "Code": "MigrationJobList",
  "Data": [
    {
      "Id": "e5f6a7b8-0000-0000-0000-000000000001",
      "Type": "ExportProject",
      "Status": "Failed",
      "SchemaVersion": "1.0.18",
      "PackageName": "DEMO.tmh",
      "Created": "2026-09-17T09:00:00.000Z",
      "Updated": "2026-09-17T09:01:00.000Z",
      "ExecutionStarted": "2026-09-17T09:00:30.000Z",
      "ExecutionFinished": "2026-09-17T09:01:00.000Z",
      "CreatedBy": "c3d4e5f6-0000-0000-0000-000000000003",
      "UpdatedBy": "c3d4e5f6-0000-0000-0000-000000000003",
      "ProjectId": "a1b2c3d4-0000-0000-0000-000000000001",
      "TenantId": "d4e5f6a7-0000-0000-0000-000000000004"
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 10, "Offset": 0, "Total": 1, "HasMore": false }
}
```

Each row has the shape that [`migration get`](#uip-tm-migration-get) returns. When `Pagination.HasMore` is `true`, `Instructions` gives the `--offset` for the next page.

## uip tm migration schemas list

List the `.tmh` schema versions that Test Manager accepts, newest first. Compare them with a package's `schemaVersion` before you import it.

Both `schemas` verbs need the `TM.Users` or `TM.Users.Read` scope, which the other migration verbs do not need. A token that can export a project can still get a 403 error here.

### Arguments

None.

### Options

None.

### Example

```bash
uip tm migration schemas list
```

### Data shape

```json
{
  "Code": "MigrationSchemaList",
  "Data": [
    { "SchemaVersion": "1.0.19" },
    { "SchemaVersion": "1.0.18" },
    { "SchemaVersion": "1.0.16" }
  ]
}
```

## uip tm migration schemas download

Download one `.tmh` schema version. Test Manager sends the schema as a zip, so the command writes it to a file. It needs the same scope as [`schemas list`](#uip-tm-migration-schemas-list).

### Arguments

None.

### Options

| Flag | Description |
|---|---|
| `--schema-version <version>` | **Required.** Version to download, as `schemas list` reports it, or `latest` for the newest. |
| `--output-file <path>` | **Required.** Where to write the schema zip. The parent directory must exist. |
| `--overwrite` | Replace `--output-file` if it already exists. Without it, an existing file is refused and nothing is written. |

### Example

```bash
uip tm migration schemas download \
  --schema-version latest \
  --output-file schema.zip
```

### Data shape

```json
{
  "Code": "MigrationSchemaDownload",
  "Data": {
    "SchemaVersion": "1.0.19",
    "OutputFile": "schema.zip",
    "Bytes": 20418
  }
}
```

With `--schema-version latest`, `SchemaVersion` holds the version number that was downloaded.

## Related

- [project export](./uip-test-manager-project.md#uip-tm-project-export): start an export job.
- [project import](./uip-test-manager-project.md#uip-tm-project-import): start an import job.
- [export-jobs](./uip-test-manager-export-jobs.md): the separate jobs that build Excel, PDF, and JUnit files.

## See also

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