# uip or sessions

> `uip or sessions` views and manages Orchestrator sessions — live host connections between robots (attended and unattended) and Orchestrator. Use it to see which hosts are connected, inspect runtime slot usage, toggle debug mode on a session, place a session into maintenance, or clean up inactive sessions.

`uip or sessions` views and manages Orchestrator sessions — live host connections between robots (attended and unattended) and Orchestrator. Use it to see which hosts are connected, inspect runtime slot usage, toggle debug mode on a session, place a session into maintenance, or clean up inactive sessions.

## Synopsis

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

## Verbs

| Verb | Purpose |
|---|---|
| `list-attended-sessions` | List attended (Studio/Assistant) sessions across the tenant or scoped to a folder. |
| `list-machines-sessions` | List sessions for a specific machine by machine key. |
| `list-usernames` | List usernames of users with active sessions. |
| `list-unattended-sessions` | List unattended session runtimes (slot usage across machines). |
| `list-user-executors` | List automation executors (robot names) grouped by username. |
| `toggle-debug-mode` | Enable or disable debug mode on a machine session. |
| `delete-inactive` | Delete disconnected or unresponsive sessions (all or by ID). |
| `set-maintenance-mode` | Place a machine session into maintenance mode. |

All verbs honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## uip or sessions list-attended-sessions

List attended sessions — Studio and Assistant connections. Without a folder flag, returns sessions across all folders (global view). With `--folder-key` or `--folder-path`, returns sessions scoped to the folder.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--folder-key` | GUID | — | Folder key for folder-scoped listing. |
| — | `--folder-path` | path | — | Folder path (for example, `Shared`). |
| — | `--state` | enum | — | `Available`, `Busy`, `Disconnected`, `Unknown`. Without `--state`, `Disconnected` sessions are excluded. |
| — | `--machine-name` | text | — | Contains-match on machine name. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | `Id desc` | OData sort expression (for example, `MachineName asc`). |

### Examples

```bash
# Attended sessions across the tenant, excluding Disconnected
uip or sessions list-attended-sessions

# Only Busy sessions in a specific folder
uip or sessions list-attended-sessions --folder-path "Shared" --state Busy

# Just machine names and states, script-friendly
uip or sessions list-attended-sessions \
    --output-filter 'Data[].{m:MachineName, s:State}'
```

### Data shape (--output json)

```json
{
  "Code": "SessionList",
  "Data": [
    {
      "Id": 501,
      "HostMachineName": "host-01",
      "MachineId": 101,
      "MachineName": "attended-01",
      "State": "Available",
      "Job": null,
      "ReportingTime": "2025-04-15T10:30:00Z",
      "Info": "",
      "IsUnresponsive": false,
      "LicenseErrorCode": "",
      "OrganizationUnitId": 42,
      "FolderName": "Shared",
      "RobotSessionType": "Attended",
      "Version": "23.10.0",
      "Source": "Studio",
      "DebugModeExpirationDate": "",
      "UpdateInfo": null,
      "InstallationId": "",
      "Platform": "Windows",
      "EndpointDetection": ""
    }
  ]
}
```

## uip or sessions list-machines-sessions

List sessions for one machine by machine key. The machine key is the GUID returned by `uip or machines list`. Optionally scope to a folder.

### Arguments

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

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--folder-key` | GUID | — | Folder key for folder-scoped listing. |
| — | `--folder-path` | path | — | Folder path for folder-scoped listing. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | `Id desc` | OData sort expression. |

### Examples

```bash
uip or sessions list-machines-sessions a1b2c3d4-0000-0000-0000-000000000001
uip or sessions list-machines-sessions a1b2c3d4-0000-0000-0000-000000000001 \
    --folder-path "Production"
```

### Data shape (--output json)

```json
{
  "Code": "SessionGetMachine",
  "Data": [
    {
      "Id": 601,
      "ServiceUserName": "svc-runner",
      "HostMachineName": "prod-worker-01",
      "MachineId": 101,
      "MachineName": "prod-worker-01",
      "State": "Available",
      "Job": null,
      "ReportingTime": "2025-04-15T10:30:00Z",
      "Info": "",
      "IsUnresponsive": false,
      "LicenseErrorCode": "",
      "OrganizationUnitId": 42,
      "FolderName": "Shared",
      "RobotSessionType": "Unattended",
      "Version": "23.10.0",
      "Source": "",
      "DebugModeExpirationDate": "",
      "UpdateInfo": null,
      "InstallationId": "",
      "Platform": "Windows",
      "EndpointDetection": ""
    }
  ]
}
```

## uip or sessions list-usernames

Return the usernames of users currently connected to Orchestrator. Useful for quickly answering "who is active right now?".

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | — | Sort expression (empty by default). |

### Examples

```bash
uip or sessions list-usernames
uip or sessions list-usernames --limit 200
```

### Data shape (--output json)

```json
{
  "Code": "SessionListUsernames",
  "Data": ["admin@example.com", "ops@example.com"]
}
```

## uip or sessions list-unattended-sessions

List unattended session runtimes — the slot usage view for unattended machines. Without a folder flag, returns sessions across the tenant. With `--folder-key` or `--folder-path`, returns sessions scoped to the folder.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--folder-key` | GUID | — | Folder key for folder-scoped listing. |
| — | `--folder-path` | path | — | Folder path (for example, `Shared`). |
| — | `--runtime-type` | enum | — | Filter by runtime type (for example, `Unattended`, `Attended`, `Headless`, `Serverless`). |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | `SessionId desc` | OData sort expression. |

### Examples

```bash
# All unattended runtimes in the tenant
uip or sessions list-unattended-sessions

# Serverless-only in a specific folder
uip or sessions list-unattended-sessions --folder-path "Shared" \
    --runtime-type Serverless
```

### Data shape (--output json)

```json
{
  "Code": "SessionListMachineSessions",
  "Data": [
    {
      "SessionId": 701,
      "MachineId": 101,
      "MachineKey": "a1b2c3d4-0000-0000-0000-000000000001",
      "MachineName": "prod-worker-01",
      "MaintenanceMode": "Default",
      "HostMachineName": "prod-worker-01",
      "RuntimeType": "Unattended",
      "MachineType": "Standard",
      "MachineScope": "Default",
      "Status": "Available",
      "IsUnresponsive": false,
      "Runtimes": 3,
      "UsedRuntimes": 1,
      "ServiceUserName": "svc-runner",
      "ReportingTime": "2025-04-15T10:30:00Z",
      "Version": "23.10.0",
      "DebugModeExpirationDate": "",
      "Platform": "Windows",
      "EndpointDetection": "",
      "TriggersCount": 0
    }
  ]
}
```

## uip or sessions list-user-executors

List automation executors assigned to each user. Returns robot (executor) names grouped by username — useful for discovering which users have which unattended robots.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | — | Sort expression (empty by default). |

### Examples

```bash
uip or sessions list-user-executors
```

### Data shape (--output json)

```json
{
  "Code": "SessionListUserExecutors",
  "Data": [
    { "UserName": "admin@example.com", "RobotNames": ["prod-worker-01", "prod-worker-02"] },
    { "UserName": "ops@example.com", "RobotNames": ["dev-serverless"] }
  ]
}
```

## uip or sessions toggle-debug-mode

Toggle debug mode on a machine session. Enabling debug mode allows connecting a Studio instance to the running session. Use `list-unattended-sessions` or `list-machines-sessions` to find session IDs.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<session-id>` | yes | Session ID (integer). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--enabled` | `true`/`false` | — (required) | Enable or disable debug mode. |
| — | `--minutes` | number | — | Duration, in minutes, for debug mode to remain active. |

### Examples

```bash
# Enable debug mode for 60 minutes
uip or sessions toggle-debug-mode 701 --enabled true --minutes 60

# Disable debug mode
uip or sessions toggle-debug-mode 701 --enabled false
```

### Data shape (--output json)

```json
{
  "Code": "SessionToggleDebugMode",
  "Data": {
    "SessionId": 701,
    "Enabled": true,
    "Status": "Debug mode updated successfully"
  }
}
```

## uip or sessions delete-inactive

Delete disconnected or unresponsive (inactive) sessions. Provide one or more session IDs to target specific sessions, or omit all IDs to delete every inactive session in the tenant.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `[session-ids...]` | no | Session IDs (integers). Omit to delete all inactive sessions. |

### Options

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

### Examples

```bash
# Delete specific inactive sessions
uip or sessions delete-inactive 701 702

# Delete every inactive session in the tenant
uip or sessions delete-inactive
```

### Data shape (--output json)

With explicit IDs:

```json
{
  "Code": "SessionDeleteInactive",
  "Data": {
    "SessionIds": [701, 702],
    "Count": 2,
    "Status": "Inactive sessions deleted successfully"
  }
}
```

Without IDs:

```json
{
  "Code": "SessionDeleteInactive",
  "Data": { "Status": "All inactive sessions deleted successfully" }
}
```

## uip or sessions set-maintenance-mode

Place a machine session into maintenance mode (or take it out). Maintenance prevents new jobs from being assigned to the session. When enabling maintenance, `--stop-jobs-strategy` controls whether running jobs are soft-stopped or force-killed.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<session-id>` | yes | Session ID (integer). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--maintenance-mode` | enum | — (required) | `Default` or `Enabled`. |
| — | `--stop-jobs-strategy` | enum | — | `SoftStop` (graceful) or `Kill` (immediate). Only applies when enabling maintenance. |

### Examples

```bash
# Enable maintenance, soft-stop running jobs
uip or sessions set-maintenance-mode 701 \
    --maintenance-mode Enabled --stop-jobs-strategy SoftStop

# Take the session back out of maintenance
uip or sessions set-maintenance-mode 701 --maintenance-mode Default
```

### Data shape (--output json)

```json
{
  "Code": "SessionSetMaintenanceMode",
  "Data": {
    "SessionId": 701,
    "MaintenanceMode": "Enabled",
    "Status": "Maintenance mode updated successfully"
  }
}
```

## Related commands

- [`uip or machines`](./uip-orchestrator-machines.md) — resolve machine names to keys for `list-machines-sessions`.
- [`uip or users`](./uip-orchestrator-users.md) — user directory; session usernames map back to user records here.
- [`uip or jobs`](./uip-orchestrator-jobs.md) — investigate jobs running on a session.

## See also

- [Global options](./global-options.md) — `--output`, `--output-filter`, `--log-level`, `--log-file`.
- [Exit codes](./exit-codes.md) — standard exit-code contract.
- [Sessions and credentials](./concepts-sessions.md) — how tenant context is resolved.