# uip or users

> Syntax and options for `uip or users`, which manages Orchestrator tenant users and their folder and role assignments.

`uip or users` manages Orchestrator users at the tenant level. Orchestrator users are backed by Identity Service (IS) — this tool does not create standalone users from scratch. Instead, `users import` references an **existing** IS directory principal (a user, group, robot account, or external application) and provisions it into the tenant; `users update` then edits the tenant-side properties (license, session permissions, unattended credentials) that live on the Orchestrator side. There is no `users delete` — user removal is managed through Identity Service or the Orchestrator portal, not this CLI. For folder-level role management, see [`uip or roles`](./uip-or-roles.md).

## Synopsis

```
uip or users list [options]
uip or users list-in-folder [--folder-path <path> | --folder-key <key>] [options]
uip or users list-available [--folder-path <path> | --folder-key <key>] [options]
uip or users get <user-key>
uip or users import (--username <name> | --directory-id <id>) --type <type> [--folder-path <path> | --folder-key <key>] [--role-keys <keys>]
uip or users assign --user-key <key> [--folder-path <path> | --folder-key <key>] [--role-keys <keys>]
uip or users unassign --user-key <key> [--folder-path <path> | --folder-key <key>]
uip or users update <user-key> [options]
uip or users current
uip or users assign-roles <user-key> --role-keys <keys>
```

## 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. |
| `import` | Import an existing Identity Service directory principal into the tenant. |
| `assign` | Assign a user to a folder, optionally with folder-level roles. |
| `unassign` | Remove a user from a folder. |
| `update` (alias `edit`) | Update a user's tenant-side 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. |
| — | `--sort-by` | field | — | OData sort (for example, `UserName asc`). |
| — | `--all-fields` | flag | off | Return the full API payload instead of the curated summary. |

### 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 }
}
```

## 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 |
|---|---|---|---|---|
| — | `--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. |
| — | `--sort-by` | field | `Id desc` | OData sort. |
| — | `--all-fields` | flag | off | Return the full API payload instead of the curated summary. |

### 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 |
|---|---|---|---|---|
| — | `--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 |
|---|---|---|---|---|
| — | `--all-fields` | flag | off | Return the full API payload instead of the curated summary. |

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

Import a directory principal — an Identity Service user, group, robot account, or external application — into this tenant. This is the only way this CLI provisions a new tenant user; there is no standalone "create a user" verb, because Orchestrator users are always backed by an IS principal.

References an existing IS principal by `--username` or `--directory-id`, plus `--type` to declare which kind of principal it is (the CLI does not guess). Optionally assigns folder roles in the same call with `--folder-path`/`--folder-key` and `--role-keys` — both a folder and roles must be provided together, or neither. `--directory-id` imports are idempotent: importing an already-imported principal by directory ID returns the existing tenant record instead of failing.

Robot accounts and external applications must be imported with `--directory-id` (the IS UUID) — Orchestrator can't resolve them by `<domain>\<name>` the way it resolves a directory user. Find the ID with `uip admin robot-accounts list --search <name>` or `uip admin external-apps list`.

### Arguments and required identifiers

| Name | Required | Purpose |
|---|---|---|
| `--username` | one of `--username`/`--directory-id` | Identity Service username (typically an email). |
| `--directory-id` | one of `--username`/`--directory-id` | Identity Service directory identifier (OIDC subject / IS UUID). **Required** for `DirectoryRobot` and `DirectoryExternalApplication` types. |

### Options

| Short | Long | Value | Default | Description |
|---|---|---|---|---|
| — | `--type` | `DirectoryUser` \| `DirectoryGroup` \| `DirectoryRobot` \| `DirectoryExternalApplication` | **required** | Directory principal type. |
| — | `--domain` | text | — | Directory domain name as configured in Identity Service. Only needed for on-premises environments with configured AD domains. |
| — | `--folder-path` | path | — | Folder to assign the imported principal to. Use with `--role-keys`. |
| — | `--folder-key` | GUID | — | Folder alternative to `--folder-path`. Use with `--role-keys`. |
| — | `--role-keys` | CSV of GUIDs | — | Folder role GUIDs to grant. Requires a folder option; a folder option without `--role-keys` is also rejected. |

### Examples

```bash
uip or users import --username alice@example.com

uip or users import --username alice@example.com \
    --folder-path Shared --role-keys a1b2c3d4-0000-0000-0000-000000000001

# Robot account — directory ID required
uip or users import --directory-id 11111111-2222-3333-4444-555555555555 \
    --type DirectoryRobot
```

### Data shape (--output json)

```json
{
  "Code": "UserImported",
  "Data": {
    "UserName": "alice@example.com",
    "Type": "DirectoryUser",
    "AssignedFolderPath": "Shared",
    "AssignedRoleKeys": ["a1b2c3d4-0000-0000-0000-000000000001"]
  }
}
```

`AlreadyImported: true` is added when `--directory-id` matched a principal already present in the tenant.

## uip or users assign

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

:::note
**CAUTION — destructive on roles.** If `--role-keys` is passed, the server replaces **all** of the user's existing roles in the target folder with the ones supplied — roles not in the payload are removed silently. To preserve existing roles, read them first with `roles user-roles list <principal-name> --type <type>` and pass the full desired union to `--role-keys`. For additive tenant-level role membership on a role, use `roles users set` instead.
:::

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

### 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 — only their folder assignment is removed.

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

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

Update a user's tenant-side properties by key (GUID). Reads current values, merges the supplied fields, and saves. Provide at least one option.

`edit` is a registered alias for this verb — `uip or users edit` works identically to `uip or users update`.

Reliably editable: license profile, session flags, and unattended robot credentials. Identity attributes (`--name`, `--surname`, `--email`, `--type`) are accepted by the API, but for directory principals (`DirectoryUser`/`Group`/`Robot`/`ExternalApplication`) those fields are normally synced from Identity Service — changing them here only edits the Orchestrator-side cached copy and may be overwritten on the next IS sync. For a durable identity change, edit the IS principal directly.

This command does **not** expose role assignments — use `users assign` (folder roles) or `users assign-roles` (tenant roles) for that; the current tenant role list is always re-sent unchanged so an update never touches it.

### Arguments

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

### Options

#### Identity (Orchestrator-side cache only for directory principals)

| Long | Value | Description |
|---|---|---|
| `--name` | text | New first name. |
| `--surname` | text | New last name. |
| `--email` | text | New email address. |
| `--type` | text | New user type (for example `User`, `DirectoryUser`). |

#### License and session permissions

| Long | Value | Description |
|---|---|---|
| `--license-type` | text | For example `Attended`, `Unattended`, `StudioPro`. |
| `--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

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

If you set any unattended-credential flag on a user with no existing `UnattendedRobot` record, both `--unattended-username` and `--unattended-password` are required together — Orchestrator silently discards an incomplete record, so the CLI refuses to submit one rather than report a false success. Editing an *existing* record accepts any subset of these flags.

### Examples

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

uip or users update d4e5f6a7-0000-0000-0000-000000000001 \
    --allow-unattended --license-type Unattended \
    --unattended-username DOMAIN\\bot --unattended-password s3cret

uip or users update 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 |
|---|---|---|---|---|

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

:::note
**CAUTION — destructive.** The server replaces the user's **entire** tenant-level role list with the keys passed via `--role-keys` — roles not in the payload are removed silently. To preserve existing tenant roles, read them first with `roles user-roles list <principal-name> --type <type>` and pass the full desired union to `--role-keys`. Unlike `users assign` (folder-level roles), this sets roles that apply across the entire tenant.
:::

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

### 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-or-roles.md) — manage roles, role-user membership, and principal permission inspection (`roles user-roles list`, `roles user-permissions list`).
- [`uip or folders`](./uip-or-folders.md) — find folder keys for `users assign` / `unassign`.
- [`uip or jobs`](./uip-or-jobs.md) — especially `jobs start --user-keys`.

## See also

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