> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> Manage the users of an organization.

Users are the individual accounts with access to an organization. Membership starts with an invitation, and what a user can do is determined by the [groups](https://docs.nscale.com/docs/cli/groups.md) they belong to.

Commands that act on one user take its ID or name either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts.

## Subcommands

* [list](#list) — List users
* [invite](#invite) — Invite a user
* [delete](#delete) — Delete a user

***

## list

List users in an organization, along with their state and the number of groups each belongs to.

**Aliases:** `list`, `ls`

```bash theme={null}
nscale users list --org <org-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>

    <tr>
      <td>
        `--limit int`
      </td>

      <td>Show at most N results (client-side; every result is still fetched). Cuts before `-q`. `0` for all</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale users list --org <org-id> --json
nscale users list -q '.[].metadata.id' -q '.[].spec.subject' -q '.[].spec.state'
# Email addresses of pending invitations
nscale users list -q '.[] | select(.spec.state == "pending") | .spec.subject'
```

***

## invite

Invite a user into an organization. A user is identified by their canonical name, which is usually an email address.

Whether groups are accepted depends on how the organization authenticates its members:

* **Private organizations** — members are added explicitly, so at least one group is required. Omit `--group` and the CLI presents a group picker.
* **Public organizations** — members sign in with an email address on the organization's domain, and group membership is managed separately, so `--group` is rejected.

To check which kind an organization is, read its type — `adhoc` for private, `domain` for public:

```bash theme={null}
nscale organizations list -q ".[].metadata.name" -q ".[].spec.organizationType"
```

`--group` takes a group ID or name; use [`nscale groups list`](https://docs.nscale.com/docs/cli/groups#list) to see them. For how groups and roles fit together, see [Groups and roles](https://docs.nscale.com/docs/manage/roles-and-groups.md).

`--state` sets the state of the user's **membership of this organization**, which is what governs their access to it:

* `pending` (the default) matches the Console flow — the member is listed as Pending and has no access until they join.
* `active` skips that step, so the membership is usable as soon as the person can sign in.
* `suspended` creates the membership with access already revoked.

> [!NOTE]
>
> `--state active` does not bypass account sign-up. If the person has no Nscale account yet, they must still complete the verification email before they can authenticate; the flag only decides whether their membership of this organization is waiting on them to join.

```bash theme={null}
nscale users invite --org <org-id> --email <email> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td>`--org string`</td><td>Organization ID or name</td></tr>
    <tr><td>`--email string`</td><td>The user's canonical name, usually an email address</td></tr>
    <tr><td>`--group stringArray`</td><td>Group ID or name to add the user to (repeatable)</td></tr>
    <tr><td>`--state string`</td><td>Membership state — `active`, `pending`, or `suspended` (default `pending`)</td></tr>
    <tr><td>`--dry-run`</td><td>Preview actions and payload without persisting</td></tr>
    <tr><td>`-y, --yes`</td><td>Automatically confirm the invitation</td></tr>

    <tr>
      <td>
        `--json`
      </td>

      <td>Emit the full JSON payload (mutually exclusive with `-q`)</td>
    </tr>

    <tr>
      <td>
        `-q, --query stringArray`
      </td>

      <td>jq filter for value extraction (see [Query output with `-q`](https://docs.nscale.com/docs/cli/query-output))</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale users invite --org <org-id> --email user@example.com
nscale users invite --org <org-id> --email user@example.com --group <group-id> --group <group-id>
# Invite unattended and print only the new ID
nscale users invite --email user@example.com --group <group-id> --yes -q '.metadata.id'
# Interactive mode
nscale users invite
```

***

## delete

Delete an existing user from an organization. The user can be given by ID or by email address.

**Aliases:** `delete`, `rm`, `remove`

```bash theme={null}
nscale users delete <user-id> --org <org-id> [flags]
```

### Flags

| Flag | Description |
| - | - |
| `--id string` | User ID or email address |
| `--org string` | Organization ID or name |
| `--dry-run` | Preview actions and payload without persisting |
| `-y, --yes` | Automatically confirm deletion |

### Examples

```bash theme={null}
nscale users delete <user-id> --org <org-id> --yes
nscale users delete user@example.com --yes
```
