# uip or machines

> `uip or machines` manages machine templates — robot host definitions that describe where robots execute and how many license slots of each type are allocated. Machines are tenant-scoped but can be assigned to specific folders.

`uip or machines` manages machine templates — robot host definitions that describe where robots execute and how many license slots of each type are allocated. Machines are tenant-scoped but can be assigned to specific folders.

## Synopsis

```
uip or machines <verb> [options]
```

## Verbs

| Verb | Purpose |
|---|---|
| `list` | List machines in the tenant, or machines assigned to a specific folder. |
| `get` | Fetch one machine by key. |
| `create` | Create a new machine template (optionally serverless). |
| `edit` | Edit a machine's name, description, or slot allocation. |
| `delete` | Delete one or more machines. |
| `assign` | Assign machines to a folder. |
| `unassign` | Remove machines from a folder. |

## uip or machines list

List machines. Without `--folder-key` or `--folder-path`, returns every machine in the tenant. With either flag, returns only machines assigned to that folder.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--folder-key` | GUID | — | Scope to a folder by key. |
| — | `--folder-path` | path | — | Scope to a folder by path. |
| `-n` | `--name` | text | — | Contains-match on machine name. |
| — | `--scope` | enum | — | `Default`, `Shared`, `PersonalWorkspace`, `Cloud`, `Serverless`, `AutomationCloudRobot`, `ElasticRobot`. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | `Id desc` | OData sort. |
| — | `--all-fields` | flag | off | Return the full API payload. |

### Examples

```bash
uip or machines list --limit 10
uip or machines list --folder-path "Shared"
uip or machines list --scope Serverless \
    --output-filter 'Data[].{name:Name, slots:UnattendedSlots}'
```

### Data shape (--output json)

```json
{
  "Code": "MachineList",
  "Data": [
    {
      "Name": "prod-worker-01",
      "ID": 101,
      "Key": "a1b2c3d4-0000-0000-0000-000000000001",
      "Type": "Standard",
      "Scope": "Default",
      "Description": "",
      "UnattendedSlots": 3,
      "HeadlessSlots": 0,
      "NonProductionSlots": 0,
      "TestAutomationSlots": 0,
      "LicenseKey": "b1c2d3e4-0000-0000-0000-000000000100"
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "HasMore": false }
}
```

## uip or machines get

Fetch a machine by GUID key. No folder context required — machines are tenant-scoped.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<machine-key>` | yes | Machine key (GUID). Find it with `machines list`. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--all-fields` | flag | off | Return the full API payload. |

### Examples

```bash
uip or machines get a1b2c3d4-0000-0000-0000-000000000001
uip or machines get a1b2c3d4-0000-0000-0000-000000000001 --all-fields
uip or machines get a1b2c3d4-0000-0000-0000-000000000001 \
    --output-filter 'Data.UnattendedSlots'
```

### Data shape (--output json)

```json
{
  "Code": "MachineGet",
  "Data": {
    "Name": "prod-worker-01",
    "ID": 101,
    "Key": "a1b2c3d4-0000-0000-0000-000000000001",
    "Type": "Standard",
    "Scope": "Default",
    "Description": "",
    "UnattendedSlots": 3,
    "HeadlessSlots": 0,
    "NonProductionSlots": 0,
    "TestAutomationSlots": 0,
    "LicenseKey": "b1c2d3e4-0000-0000-0000-000000000100"
  }
}
```

## uip or machines create

Create a new machine template. `--name` is required; with `--serverless`, the machine is created as a cloud-hosted (Portable) template.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-n` | `--name` | text | **required** | Machine name (must be unique within the tenant). |
| `-d` | `--description` | text | — | Machine description. |
| — | `--serverless` | flag | off | Create a serverless (cloud-hosted) machine. |
| — | `--unattended-slots` | number | — | Unattended robot slots. |
| — | `--headless-slots` | number | — | Headless robot slots. |
| — | `--non-production-slots` | number | — | Non-production robot slots. |
| — | `--testing-slots` | number | — | Test-automation robot slots. |
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or machines create --name "staging-worker" --unattended-slots 2

uip or machines create --name "serverless-pool" --serverless \
    --unattended-slots 10

uip or machines create --name "qa-host" --unattended-slots 1 --testing-slots 2 \
    --output-filter 'Data.Key'
```

### Data shape (--output json)

```json
{
  "Code": "MachineCreated",
  "Data": {
    "Name": "staging-worker",
    "ID": 103,
    "Key": "a1b2c3d4-0000-0000-0000-000000000010",
    "Type": "Template",
    "Scope": "Default",
    "Description": "",
    "UnattendedSlots": 2,
    "HeadlessSlots": 0,
    "NonProductionSlots": 0,
    "TestAutomationSlots": 0,
    "LicenseKey": ""
  }
}
```

## uip or machines edit

Edit a machine's name, description, or slot allocation. Only provided options are updated; omitted fields remain unchanged.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<machine-key>` | yes | Machine key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-n` | `--name` | text | — | New machine name. |
| `-d` | `--description` | text | — | New machine description. |
| — | `--unattended-slots` | number | — | Unattended robot slots. |
| — | `--headless-slots` | number | — | Headless robot slots. |
| — | `--non-production-slots` | number | — | Non-production robot slots. |
| — | `--testing-slots` | number | — | Test-automation robot slots. |
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or machines edit a1b2c3d4-0000-0000-0000-000000000010 --unattended-slots 5
uip or machines edit a1b2c3d4-0000-0000-0000-000000000010 \
    --name "staging-worker-eu" --description "EU staging host"
uip or machines edit a1b2c3d4-0000-0000-0000-000000000010 \
    --unattended-slots 5 --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "MachineUpdate",
  "Data": {
    "Key": "a1b2c3d4-0000-0000-0000-000000000010",
    "Name": "staging-worker",
    "Status": "Updated successfully"
  }
}
```

## uip or machines delete

Delete one or more machines. A single key uses `DeleteById`; multiple keys use the bulk API. Machines must be unassigned from all folders before deletion.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<machine-keys...>` | yes | One or more machine keys (GUIDs). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or machines delete a1b2c3d4-0000-0000-0000-000000000010
uip or machines delete key-1 key-2 key-3
uip or machines delete key-1 key-2 --output-filter 'Data.Count'
```

### Data shape (--output json)

```json
{
  "Code": "MachineDelete",
  "Data": {
    "Deleted": [
      { "Key": "a1b2c3d4-0000-0000-0000-000000000010", "Name": "staging-worker" }
    ],
    "Count": 1,
    "Status": "Deleted successfully"
  }
}
```

## uip or machines assign

Assign one or more machines to a folder. Requires `--folder-path` or `--folder-key`.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<machine-keys...>` | yes | One or more machine keys (GUIDs). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--folder-path` | path | — | Target folder by path. |
| — | `--folder-key` | GUID | — | Target folder by key. |

### Examples

```bash
uip or machines assign a1b2c3d4-0000-0000-0000-000000000001 \
    --folder-path "Shared"

uip or machines assign key-1 key-2 --folder-key b1c2d3e4-0000-0000-0000-000000000001

uip or machines assign a1b2c3d4-0000-0000-0000-000000000001 \
    --folder-path "Shared" --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "MachineAssign",
  "Data": {
    "MachineKeys": ["a1b2c3d4-0000-0000-0000-000000000001"],
    "FolderPath": "Shared",
    "Count": 1,
    "Status": "Assigned successfully"
  }
}
```

## uip or machines unassign

Remove machines from a folder. The machines are not deleted — only their folder assignment is removed. Requires `--folder-path` or `--folder-key`.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<machine-keys...>` | yes | One or more machine keys (GUIDs). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--folder-path` | path | — | Folder to unassign from. |
| — | `--folder-key` | GUID | — | Folder to unassign from. |

### Examples

```bash
uip or machines unassign a1b2c3d4-0000-0000-0000-000000000001 \
    --folder-path "Shared"

uip or machines unassign key-1 key-2 --folder-path "Production"

uip or machines unassign a1b2c3d4-0000-0000-0000-000000000001 \
    --folder-path "Shared" --output-filter 'Data.Count'
```

### Data shape (--output json)

```json
{
  "Code": "MachineUnassign",
  "Data": {
    "MachineKeys": ["a1b2c3d4-0000-0000-0000-000000000001"],
    "FolderPath": "Shared",
    "Count": 1,
    "Status": "Unassigned successfully"
  }
}
```

## Exit codes

See [Exit codes](./exit-codes.md). No verb-specific overrides.

## Related commands

- [`uip or folders`](./uip-orchestrator-folders.md) — especially `folders runtimes` to inspect machine allocation from the folder side.
- [`uip or licenses`](./uip-orchestrator-licenses.md) — `licenses toggle` enables/disables licensing on a specific machine.
- [`uip or jobs`](./uip-orchestrator-jobs.md) — `jobs start --machine-keys` targets specific machines.

## See also

- [Global options](./global-options.md).