# uip or users

> `uip or users` manages Orchestrator users at the tenant level — listing, creating, editing, and deleting users, plus assigning them to folders and managing tenant-level role assignments. For folder-level role management, see [`uip or roles`](./uip-orchestrator-roles.md).

`uip or users` manages Orchestrator users at the tenant level — listing, creating, editing, and deleting users, plus assigning them to folders and managing tenant-level role assignments. For folder-level role management, see [`uip or roles`](./uip-orchestrator-roles.md).

## Synopsis

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

## Verbs

| Verb | Purpose |
|---|---|
| `list` | List tenant users with optional filters. |
| `list-in-folder` | List users assigned to a folder, with their folder-level roles. |
| `list-available` | List users that can still be assigned to a folder (not yet assigned). |
| `get` | Fetch one user by key. |
| `create` | Create a new user; optionally assign tenant roles and set unattended execution credentials. |
| `delete` | Delete a user by key. |
| `assign` | Assign a user to a folder, optionally with folder-level roles. |
| `unassign` | Remove a user from a folder. |
| `edit` | Edit user properties (PATCH semantics). |
| `current` | Return details of the currently authenticated user. |
| `assign-roles` | Replace a user's tenant-level role assignments. |

## uip or users list

List users in the tenant. Returns user key (GUID), username, full name, email, type, and active status.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--key` | GUID | — | Filter by user key (exact match). |
| — | `--username` | text | — | Filter by username (contains match). |
| — | `--email` | text | — | Filter by email address (contains match). |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | — | OData sort (for example, `UserName asc`). |
| — | `--all-fields` | flag | off | Return the full API payload. |

### Examples

```bash
uip or users list --limit 10
uip or users list --username admin
uip or users list --output-filter 'Data[].{key:Key, name:UserName}'
```

### Data shape (--output json)

```json
{
  "Code": "UserList",
  "Data": [
    {
      "Key": "d4e5f6a7-0000-0000-0000-000000000001",
      "UserName": "admin@example.com",
      "FullName": "Admin User",
      "Email": "admin@example.com",
      "Type": "User",
      "IsActive": true
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "HasMore": false }
}
```

## uip or users list-in-folder

List users assigned to a folder, with their folder-level roles. Requires `--folder-path` or `--folder-key`.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--folder-path` | path | — | Target folder. Provide this or `--folder-key`. |
| — | `--folder-key` | GUID | — | Target folder. Provide this or `--folder-path`. |
| — | `--include-inherited` | flag | off | Also show users inherited from parent folders. |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |
| — | `--order-by` | field | `Id desc` | OData sort. |

### Examples

```bash
uip or users list-in-folder --folder-path "Shared"
uip or users list-in-folder --folder-path "Shared" --include-inherited
uip or users list-in-folder --folder-path "Shared" \
    --output-filter 'Data[].{name:UserName, roles:Roles}'
```

### Data shape (--output json)

```json
{
  "Code": "UserList",
  "Data": [
    {
      "Key": "d4e5f6a7-0000-0000-0000-000000000001",
      "UserName": "admin@example.com",
      "FullName": "Admin User",
      "Type": "User",
      "IsInherited": false,
      "Roles": "Folder Administrator"
    }
  ]
}
```

## uip or users list-available

List tenant users that can still be assigned to a folder. Use the returned keys with `users assign` or `roles assign`.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| `-t` | `--tenant` | name | session default | Override the tenant. |
| — | `--folder-path` | path | — | Target folder. Provide this or `--folder-key`. |
| — | `--folder-key` | GUID | — | Target folder. Provide this or `--folder-path`. |
| `-s` | `--search` | text | — | Filter by username (contains match). |
| `-l` | `--limit` | number | `50` | Page size. |
| — | `--offset` | number | `0` | Skip count. |

### Examples

```bash
uip or users list-available --folder-path "Shared"
uip or users list-available --folder-path "Shared" --search admin
uip or users list-available --folder-path "Shared" \
    --output-filter 'Data[].Key'
```

### Data shape (--output json)

```json
{
  "Code": "UserAvailableList",
  "Data": [
    {
      "Key": "d4e5f6a7-0000-0000-0000-000000000003",
      "UserName": "newuser@example.com",
      "Roles": ""
    }
  ]
}
```

## uip or users get

Fetch a user by GUID key.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<user-key>` | yes | User key (GUID). |

### 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 users get d4e5f6a7-0000-0000-0000-000000000001
uip or users get d4e5f6a7-0000-0000-0000-000000000001 --all-fields
uip or users get d4e5f6a7-0000-0000-0000-000000000001 --output-filter 'Data.Email'
```

### Data shape (--output json)

```json
{
  "Code": "User",
  "Data": {
    "Key": "d4e5f6a7-0000-0000-0000-000000000001",
    "UserName": "admin@example.com",
    "FullName": "Admin User",
    "Email": "admin@example.com",
    "Type": "User",
    "IsActive": true
  }
}
```

## uip or users create

Create a new tenant user. Only `--username` is required. The API requires `rolesList`, so `--role-keys` is effectively required in practice — use it with tenant-scope role GUIDs.

### Options

#### Identity

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--username` | text | **required** | Login username. |
| — | `--name` | text | — | First name. |
| — | `--surname` | text | — | Last name. |
| — | `--email` | text | — | Email address. |
| — | `--type` | enum | — | User type (for example, `User`, `DirectoryUser`). |
| `-t` | `--tenant` | name | session default | Override the tenant. |

#### Roles and license

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--role-keys` | CSV of GUIDs | — | Tenant-scope role GUIDs (resolved to role names for the API payload). |
| — | `--license-type` | enum | — | For example, `Attended`, `Unattended`, `StudioPro`. |

#### Session permissions (flag pairs)

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--allow-unattended` / `--deny-unattended` | flag | — | Allow or deny unattended job execution. |
| — | `--allow-attended` / `--deny-attended` | flag | — | Allow or deny attended sessions. |
| — | `--allow-login` / `--deny-login` | flag | — | Allow or deny Orchestrator login. |
| — | `--allow-personal-workspace` / `--deny-personal-workspace` | flag | — | Allow or deny personal workspace. |
| — | `--active` / `--inactive` | flag | — | Activate or deactivate the user. |

#### Unattended execution credentials

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--unattended-username` | text | — | Windows account (for example, `DOMAIN\user`). |
| — | `--unattended-password` | text | — | Password, or — for read-only credential stores — the external secret reference name. |
| — | `--credential-store-key` | GUID | — | Credential store. Use `credential-stores list` to find it. |
| — | `--credential-type` | enum | — | `Default` or `SmartCard`. |
| — | `--limit-concurrent` / `--no-limit-concurrent` | flag | — | Allow or disallow concurrent execution on multiple machines. |

### Examples

```bash
uip or users create --username newuser@example.com --email newuser@example.com \
    --role-keys a1b2c3d4-0000-0000-0000-000000000001

uip or users create --username bot@example.com --name Bot --surname Worker \
    --role-keys a1b2c3d4-0000-0000-0000-000000000002 \
    --unattended-username DOMAIN\\bot --unattended-password s3cret

uip or users create --username newuser@example.com \
    --role-keys a1b2c3d4-0000-0000-0000-000000000001 \
    --output-filter 'Data.Key'
```

### Data shape (--output json)

```json
{
  "Code": "User",
  "Data": {
    "Key": "d4e5f6a7-0000-0000-0000-000000000010",
    "UserName": "newuser@example.com",
    "FullName": "",
    "Email": "newuser@example.com",
    "Type": "User",
    "IsActive": true
  }
}
```

## uip or users delete

Permanently delete a user from the tenant.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<user-key>` | yes | User key (GUID). |

### Options

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

### Examples

```bash
uip or users delete d4e5f6a7-0000-0000-0000-000000000010
uip or users delete d4e5f6a7-0000-0000-0000-000000000010 --output-filter 'Data.Status'
uip or users delete d4e5f6a7-0000-0000-0000-000000000010 --output plain
```

### Data shape (--output json)

```json
{
  "Code": "UserDeleted",
  "Data": { "Key": "d4e5f6a7-0000-0000-0000-000000000010", "Status": "Deleted successfully" }
}
```

## uip or users assign

Assign a user to a folder, optionally with folder-level roles.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--user-key` | GUID | **required** | User key. |
| — | `--role-keys` | CSV of GUIDs | — | Folder-scope role GUIDs. |
| — | `--folder-path` | path | — | Target folder. Provide this or `--folder-key`. |
| — | `--folder-key` | GUID | — | Target folder. |
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or users assign --user-key d4e5f6a7-0000-0000-0000-000000000001 \
    --folder-path "Shared"

uip or users assign --user-key d4e5f6a7-0000-0000-0000-000000000001 \
    --folder-path "Shared" \
    --role-keys a1b2c3d4-0000-0000-0000-000000000002

uip or users assign --user-key d4e5f6a7-0000-0000-0000-000000000001 \
    --folder-path "Shared" --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "UserAssigned",
  "Data": {
    "UserKey": "d4e5f6a7-0000-0000-0000-000000000001",
    "FolderPath": "Shared",
    "Status": "Assigned successfully"
  }
}
```

## uip or users unassign

Remove a user from a folder. The user is not deleted.

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--user-key` | GUID | **required** | User key. |
| — | `--folder-path` | path | — | Folder to remove from. Provide this or `--folder-key`. |
| — | `--folder-key` | GUID | — | Folder to remove from. |
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or users unassign --user-key d4e5f6a7-0000-0000-0000-000000000001 \
    --folder-path "Shared"

uip or users unassign --user-key d4e5f6a7-0000-0000-0000-000000000001 \
    --folder-key b1c2d3e4-0000-0000-0000-000000000001

uip or users unassign --user-key d4e5f6a7-0000-0000-0000-000000000001 \
    --folder-path "Shared" --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "UserUnassigned",
  "Data": {
    "UserKey": "d4e5f6a7-0000-0000-0000-000000000001",
    "FolderPath": "Shared",
    "Status": "Unassigned successfully"
  }
}
```

## uip or users edit

Edit a user by key. Reads current values, merges the provided fields, and saves. Provide at least one option to update.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<user-key>` | yes | User key (GUID). |

### Options

Same flags as `users create`, except `--username` (cannot be changed) and `--role-keys` (use `users assign-roles` instead). All session-permission flag pairs, license type, and unattended credential options apply.

### Examples

```bash
uip or users edit d4e5f6a7-0000-0000-0000-000000000001 --email newmail@example.com

uip or users edit d4e5f6a7-0000-0000-0000-000000000001 \
    --allow-unattended --license-type Unattended

uip or users edit d4e5f6a7-0000-0000-0000-000000000001 --inactive \
    --output-filter 'Data.Status'
```

### Data shape (--output json)

```json
{
  "Code": "UserUpdated",
  "Data": { "Key": "d4e5f6a7-0000-0000-0000-000000000001", "Status": "Updated successfully" }
}
```

## uip or users current

Return the currently authenticated user. Useful for verifying the session and discovering your own user key.

### Options

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

### Examples

```bash
uip or users current
uip or users current --output-filter 'Data.Key'
uip or users current --output table
```

### Data shape (--output json)

Same `User` shape as `users get`.

## uip or users assign-roles

Assign tenant-level roles to a user. This replaces the user's current tenant roles — use `roles set-role-users` for additive membership at a role level.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<user-key>` | yes | User key (GUID). |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--role-keys` | CSV of GUIDs | **required** | Role GUIDs to assign at tenant scope. |
| `-t` | `--tenant` | name | session default | Override the tenant. |

### Examples

```bash
uip or users assign-roles d4e5f6a7-0000-0000-0000-000000000001 \
    --role-keys a1b2c3d4-0000-0000-0000-000000000001

uip or users assign-roles d4e5f6a7-0000-0000-0000-000000000001 \
    --role-keys a1b2c3d4-0000-0000-0000-000000000001,a1b2c3d4-0000-0000-0000-000000000002

uip or users assign-roles d4e5f6a7-0000-0000-0000-000000000001 \
    --role-keys a1b2c3d4-0000-0000-0000-000000000001 \
    --output-filter 'Data.RolesAssigned'
```

### Data shape (--output json)

```json
{
  "Code": "UserRolesAssigned",
  "Data": {
    "UserKey": "d4e5f6a7-0000-0000-0000-000000000001",
    "RolesAssigned": 1,
    "Status": "Assigned successfully"
  }
}
```

## Exit codes

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

## Related commands

- [`uip or roles`](./uip-orchestrator-roles.md) — manage roles and role-user membership.
- [`uip or folders`](./uip-orchestrator-folders.md) — find folder keys for `users assign` / `unassign`.
- [`uip or jobs`](./uip-orchestrator-jobs.md) — especially `jobs start --user-keys`.

## See also

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