uip or sessions

Syntax and options for `uip or sessions`, which views and manages live robot connections to Orchestrator.

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
attended list	List attended (Studio/Assistant) sessions across the tenant or scoped to a folder.
machines list	List sessions for a specific machine by machine key.
list-usernames	List usernames of users with active sessions.
unattended list	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 (--output, --output-filter, --log-level, --log-file). Exit codes follow the standard contract.

uip or sessions attended list

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
—	--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.
—	--sort-by	field	Id desc	OData sort expression (for example, MachineName asc).

Examples

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

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

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

Data shape (--output 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 machines list

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
—	--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.
—	--sort-by	field	Id desc	OData sort expression.

Examples

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

Data shape (--output 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
-l	--limit	number	50	Page size.
—	--offset	number	0	Skip count.
—	--sort-by	field	—	Sort expression (empty by default).

Examples

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

Data shape (--output json)

{
  "Code": "SessionListUsernames",
  "Data": ["[e-mail]", "[e-mail]"]
}

uip or sessions unattended list

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
—	--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.
—	--sort-by	field	SessionId desc	OData sort expression.

Examples

# All unattended runtimes in the tenant
uip or sessions unattended list

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

Data shape (--output 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
-l	--limit	number	50	Page size.
—	--offset	number	0	Skip count.
—	--sort-by	field	—	Sort expression (empty by default).

Examples

uip or sessions list-user-executors

Data shape (--output json)

{
  "Code": "SessionListUserExecutors",
  "Data": [
    { "UserName": "[e-mail]", "RobotNames": ["prod-worker-01", "prod-worker-02"] },
    { "UserName": "[e-mail]", "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 sessions unattended list or sessions machines list <machine-key> to find session IDs.

Arguments

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

Options

Short	Long	Value	Default	Description
—	--enabled	true/false	— (required)	Enable or disable debug mode.
—	--minutes	number	—	Duration, in minutes, for debug mode to remain active.

Examples

# 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)

{
  "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

Examples

# 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:

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

Without IDs:

{
  "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
—	--maintenance-mode	enum	— (required)	Default or Enabled.
—	--stop-jobs-strategy	enum	—	SoftStop (graceful) or Kill (immediate). Only applies when enabling maintenance.

Examples

# 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)

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

Related commands

• uip or machines — resolve machine names to keys for sessions machines list.
• uip or users — user directory; session usernames map back to user records here.
• uip or jobs — investigate jobs running on a session.

See also

• Global options — --output, --output-filter, --log-level, --log-file.
• Exit codes — standard exit-code contract.
• Sessions and credentials — how tenant context is resolved.