# uip admin users

> Syntax and options for `uip admin users` and `uip admin groups`, which manage Identity Server directory users, groups, and group membership.

`uip admin users` and `uip admin groups` manage local Identity Server users and groups within your organization's partition — the directory-level identities behind login, not Orchestrator-level role assignments. Two independent command groups live here: `users` (create/read/update/delete/invite directory users) and `groups` (create/read/update/delete groups, plus membership management).

`--organization` is accepted on most verbs in both groups but is **deprecated and ignored** — the organization is always derived from your current login context. Passing it prints a warning (`--organization is deprecated and ignored; organization is derived from login context`) but has no effect.

## Synopsis

```text
uip admin users list [--search <term>] [--sort-by <field>] [--sort-order asc|desc] [--limit <n>] [--offset <n>]
uip admin users get <user-id>
uip admin users create <username> --email <email> [--name <name>] [--surname <surname>]
uip admin users update <user-id> [--email <email>] [--name <name>] [--surname <surname>]
uip admin users delete <user-id>
uip admin users invite --email <emails> [--name <name>] [--surname <surname>]

uip admin groups list
uip admin groups get <group-id>
uip admin groups create <name>
uip admin groups update <group-id> --name <name>
uip admin groups delete <group-id>
uip admin groups members list <group-id> [--limit <n>] [--offset <n>]
uip admin groups members add <group-id> --user-ids <ids>
uip admin groups members revoke <group-id> --user-ids <ids>
```

## Verbs

| Group | Verb | Purpose |
|---|---|---|
| `users` | `list` | List users in the partition (searchable, sortable, paginated). |
| `users` | `get` | Get a user's full details by ID. |
| `users` | `create` | Create a new local user. |
| `users` | `update` | Update a user's email, first name, or last name. |
| `users` | `delete` | Delete a user by ID. |
| `users` | `invite` | Invite one or more users by email. |
| `groups` | `list` | List all groups in the partition. |
| `groups` | `get` | Get a group's details by ID. |
| `groups` | `create` | Create a new local group. |
| `groups` | `update` | Rename a group. |
| `groups` | `delete` | Delete a group by ID. |
| `groups members` | `list` | List a group's members. |
| `groups members` | `add` | Add one or more users to a group. |
| `groups members` | `revoke` | Remove one or more users from a group. |

## uip admin users list

List users in the partition. Returns user ID, username, email, name, and creation time.

### Options

| Long | Short | Value | Default | Description |
|---|---|---|---|---|
| `--search <term>` | `-s` | string | — | Search users by name or email. |
| `--sort-by <field>` | | string | — | Sort field, e.g. `UserName`, `Email`. |
| `--sort-order <direction>` | | `asc`\|`desc` | `asc` | Sort direction. |
| `--limit <number>` | `-l` | integer | 50 (`DEFAULT_PAGE_SIZE`) | Number of items to return. |
| `--offset <number>` | | integer | `0` | Number of items to skip. |
| `--login-validity <minutes>` | | integer | — | Override token validity for this call. |

### Example

```bash
uip admin users list --limit 5
```

### Data shape (--output json)

```json
{
  "Code": "UserList",
  "Data": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "userName": "admin@example.com",
      "email": "admin@example.com",
      "name": "Admin",
      "surname": "User",
      "displayName": "Admin User",
      "creationTime": "2026-01-15T10:00:00.000Z"
    }
  ]
}
```

## uip admin users get

Get user details by ID.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<user-id>` | yes | User ID (UUID). Find it with `users list`. |

### Example

```bash
uip admin users get a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{
  "Code": "UserDetails",
  "Data": {
    "id": "a1b2c3d4-0000-0000-0000-000000000001",
    "userName": "admin@example.com",
    "email": "admin@example.com",
    "name": "Admin",
    "surname": "User",
    "displayName": "Admin User",
    "creationTime": "2026-01-15T10:00:00.000Z"
  }
}
```

## uip admin users create

Create a new local user.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<username>` | yes | Username for the new user. |

### Options

| Long | Short | Value | Required | Description |
|---|---|---|---|---|
| `--email <email>` | `-e` | email | **yes** | Email address. |
| `--name <name>` | `-n` | string | no | First name. |
| `--surname <surname>` | | string | no | Last name. |

### Example

```bash
uip admin users create newuser --email "user@example.com" --name "John" --surname "Doe"
```

### Data shape (--output json)

```json
{ "Code": "UserCreated", "Data": { "Succeeded": true } }
```

## uip admin users update

Update an existing user's email, first name, or last name. At least one field is required — calling with none fails client-side (`"No fields to update"`) before any network call.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<user-id>` | yes | User ID (UUID). |

### Options

| Long | Short | Value | Description |
|---|---|---|---|
| `--email <email>` | `-e` | email | New email address. |
| `--name <name>` | `-n` | string | New first name. |
| `--surname <surname>` | | string | New last name. |

### Example

```bash
uip admin users update a1b2c3d4-0000-0000-0000-000000000001 --name "Jane" --surname "Doe" --email "jane@example.com"
```

### Data shape (--output json)

```json
{ "Code": "UserUpdated" }
```

## uip admin users delete

Delete a user by ID.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<user-id>` | yes | User ID (UUID). |

### Example

```bash
uip admin users delete a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{ "Code": "UserDeleted", "Data": { "Id": "a1b2c3d4-0000-0000-0000-000000000001", "Status": "Deleted successfully" } }
```

## uip admin users invite

Invite one or more users by email. Sends an invitation to join the organization.

### Options

| Long | Short | Value | Required | Description |
|---|---|---|---|---|
| `--email <emails>` | `-e` | comma-separated | **yes** | One or more email addresses to invite. |
| `--name <name>` | `-n` | string | no | First name applied to every invited user. |
| `--surname <surname>` | | string | no | Last name applied to every invited user. |

### Example

```bash
uip admin users invite --email "user@example.com"
```

### Data shape (--output json)

```json
{ "Code": "UsersInvited", "Data": { "succeeded": true } }
```

## uip admin groups list

List all groups in the partition. Returns group ID, name, type, and creation time. No filtering/pagination options — returns everything in one call.

### Example

```bash
uip admin groups list
```

### Data shape (--output json)

```json
{
  "Code": "GroupList",
  "Data": [
    { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Administrators", "displayName": "Administrators", "type": "BuiltIn", "creationTime": "2026-01-15T10:00:00.000Z" }
  ]
}
```

## uip admin groups get

Get group details by ID.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<group-id>` | yes | Group ID (UUID). Find it with `groups list`. |

### Example

```bash
uip admin groups get a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{ "Code": "GroupDetails", "Data": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Administrators", "displayName": "Administrators", "type": "BuiltIn", "creationTime": "2026-01-15T10:00:00.000Z" } }
```

## uip admin groups create

Create a new local group.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<name>` | yes | Group name. |

### Example

```bash
uip admin groups create "DevOps Team"
```

### Data shape (--output json)

```json
{ "Code": "GroupCreated", "Data": { "id": "a1b2c3d4-0000-0000-0000-000000000002", "name": "DevOps Team", "displayName": "DevOps Team", "type": "Custom" } }
```

The command generates a client-side UUID for the group's `id` before calling the API — the server rejects group creation with a 409 if no ID is supplied.

## uip admin groups update

Rename a group. `--name` is the only updatable field and is required — omitting it fails client-side (`"No fields to update"`).

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<group-id>` | yes | Group ID (UUID). |

### Options

| Long | Short | Value | Required | Description |
|---|---|---|---|---|
| `--name <name>` | `-n` | string | **yes** | New group name. |

### Example

```bash
uip admin groups update a1b2c3d4-0000-0000-0000-000000000001 --name "Renamed Group"
```

### Data shape (--output json)

```json
{ "Code": "GroupUpdated" }
```

## uip admin groups delete

Delete a group by ID.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<group-id>` | yes | Group ID (UUID). |

### Example

```bash
uip admin groups delete a1b2c3d4-0000-0000-0000-000000000002
```

### Data shape (--output json)

```json
{ "Code": "GroupDeleted", "Data": { "Id": "a1b2c3d4-0000-0000-0000-000000000002", "Status": "Deleted successfully" } }
```

## uip admin groups members list

List a group's members.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<group-id>` | yes | Group ID (UUID). |

### Options

| Long | Short | Value | Default | Description |
|---|---|---|---|---|
| `--limit <number>` | `-l` | integer | `50` | Number of items to return. |
| `--offset <number>` | | integer | `0` | Number of items to skip. |

### Example

```bash
uip admin groups members list a1b2c3d4-0000-0000-0000-000000000001
```

### Data shape (--output json)

```json
{ "Code": "GroupMembers", "Data": [] }
```

## uip admin groups members add

Add one or more users to a group.

:::note
Implemented as a read-modify-write: the command fetches the group's current name, then calls the group-update API with `directoryUserIDsToAdd` — the same underlying operation as `groups update`, just with a different payload field. There is no dedicated "add member" API call.
:::

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<group-id>` | yes | Group ID (UUID). |

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--user-ids <ids>` | comma-separated | **yes** | User IDs to add. Find them with `users list`. |

### Example

```bash
uip admin groups members add a1b2c3d4-0000-0000-0000-000000000001 --user-ids "user-id-1,user-id-2"
```

### Data shape (--output json)

```json
{ "Code": "GroupMembersAdded" }
```

## uip admin groups members revoke

Remove one or more users from a group. Same read-modify-write mechanism as `members add`, using `directoryUserIDsToRemove`.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<group-id>` | yes | Group ID (UUID). |

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--user-ids <ids>` | comma-separated | **yes** | User IDs to remove. Must be current members. |

### Example

```bash
uip admin groups members revoke a1b2c3d4-0000-0000-0000-000000000001 --user-ids "user-id-1"
```

### Data shape (--output json)

```json
{ "Code": "GroupMembersRevoked" }
```

## Related

- [`uip admin robot-accounts`](./uip-admin-robot-accounts.md) — non-human identities, personal access tokens, and OAuth scope reference.
- [`uip admin external-apps`](./uip-admin-external-apps.md) — OAuth2 client registrations and federated credentials.
- [`uip admin smtp`](./uip-admin-smtp.md) — organization email configuration.
- [`uip platform users`](./uip-platform-users.md) — license allocation (a different, license-focused user surface).

## See also

- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)