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

# Invite and manage your app's users from the CLI

> Invite people to your hosted app, change their roles, lock them out and end their sessions from the terminal, with forge cloud identity on Reliant hosting.

By the end of this guide you will have invited a person to your hosted app, given them roles, locked and unlocked their account, ended their sessions and removed them, all from the terminal. These are the users who sign in to the app you deployed, not the members of your Reliant organization.

A hosted environment that declares `forge.ManagedIdentity` gets its own identity instance, and `reliant forge cloud identity` administers it through the control plane. You never handle the identity provider's console or an admin password.

## Before you begin

* A Forge app with sign-in deployed to a hosted environment. [Add sign-in methods](https://docs.reliantlabs.io/guides/forge/add-sign-in-passkeys.md) declares the identity, and [Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md) ships it.
* Forge v1.6 or later, run as `reliant forge` inside the project.
* To read users, the `identity:read` grant. To change them, you must be an organization admin with `identity:manage`. Under Reliant, forge exchanges your sign-in for that scope per command; there is no separate login.

**1. Check the identity**

```bash terminal theme={null}
reliant forge cloud identity status prod
```

```text theme={null}
State: IDENTITY_STATE_READY
Issuer: https://guides-sandbox-users2-prod-54e52a.reliantidentity.com
Mail: none (invite and reset need --return-code; you deliver the code)
App: prod:api (client 4004697…)
```

`Mail:` decides how invitations travel. With `smtp` declared in `forge.ManagedIdentity`, the code is emailed. With `none`, you pass `--return-code` and deliver it yourself.

**2. Invite a user**

```bash terminal theme={null}
reliant forge cloud identity invite prod --email guides-sandbox+1@example.com --role member --return-code
```

```text theme={null}
Invited guides-sandbox+1@example.com (user 400470558912808269, created=true).
Password-set code — a credential: give it only to this person, over a channel you control. Single use; it expires at 2026-11-20T18:17:34.504630660Z.
  https://twilight-antelope.sites.reliantlabs.dev/auth/reset?userID=400470558912808269&code=…&orgID=…
```

The link opens your app's own password page. It works once and expires in about an hour; `reset` issues a new one. Inviting an existing account grants it the roles instead. `--role` takes the role keys `identity.k` declares, and is repeatable.

**3. List users**

```bash terminal theme={null}
reliant forge cloud identity users prod
```

```text theme={null}
EMAIL                         USER ID             STATE                       ROLES   LAST SIGN-IN
guides-sandbox+1@example.com  400470558912808269  IDENTITY_USER_STATE_ACTIVE  member  -
1 of 1 user(s)
Role: admin (declared/read-only: false)
Role: member (declared/read-only: false)
```

`--query` filters by an email substring, and `--page-size` with `--page-token` pages through large lists. `--json` prints the same as a document, never with credentials.

**4. Change roles**

`set-roles` replaces the user's roles with exactly the ones you name:

```bash terminal theme={null}
reliant forge cloud identity set-roles prod --user guides-sandbox+1@example.com --role admin --role member
```

```text theme={null}
Roles of guides-sandbox+1@example.com (user 400470558912808269) are now: admin, member.
```

`--none` removes every role. A role whose members `identity.k` declares (`members_from = "declared"`) is read-only here: change its `members` list and deploy instead.

**5. Lock an account and end its sessions**

```bash terminal theme={null}
reliant forge cloud identity lock prod --user guides-sandbox+1@example.com
reliant forge cloud identity revoke-sessions prod --user guides-sandbox+1@example.com
```

```text theme={null}
Locked guides-sandbox+1@example.com (user 400470558912808269).
Revoked 0 session(s) of guides-sandbox+1@example.com (user 400470558912808269).
```

`users` now shows `IDENTITY_USER_STATE_LOCKED`. Locking stops new sign-ins; `revoke-sessions` ends the ones in progress, though an access token already issued stays valid until it expires. `unlock` lets the user back in.

**6. Reset a password or remove a user**

`reset --user <email> --return-code` issues a new password-set code; the current password keeps working until the code is used. To remove the account for good:

```bash terminal theme={null}
reliant forge cloud identity delete prod --user guides-sandbox+1@example.com --yes
```

```text theme={null}
Deleted guides-sandbox+1@example.com (user 400470558912808269).
```

Without `--yes` it asks on the terminal, and refuses when there is no terminal to ask. A user who holds a declared role is refused, since the next deploy would recreate them.

## What this does not do

* **It doesn't send mail unless the environment can.** With `Mail: none`, invitations and resets need `--return-code`, and the code is a credential you deliver.
* **It doesn't set passwords.** There is no password option and no seed account: each person sets their own through the link.
* **Exporting users isn't available on Reliant hosting yet.** `reliant forge cloud identity export` is refused with "export is not enabled for this deployment".
* **Roles are not permissions.** What a role may do is your handler code ([Scope rows to their owner](https://docs.reliantlabs.io/guides/forge/scope-rows-to-owner.md)).

## Troubleshooting

> [accordion] this environment's identity has no mail delivery
>
> The invite or reset was refused because the environment declares no `smtp`. Add `--return-code`, or declare `smtp` in `forge.ManagedIdentity` and deploy.

## Next steps

> [card] [Add sign-in methods](https://docs.reliantlabs.io/guides/forge/add-sign-in-passkeys.md)
>
> Passwords, passkeys and the roles your app declares.

> [card] [Scope rows to their owner](https://docs.reliantlabs.io/guides/forge/scope-rows-to-owner.md)
>
> Use the signed-in user in every query.

> [card] [Manage production secrets](https://docs.reliantlabs.io/guides/hosting/manage-production-secrets.md)
>
> Keep credentials out of git, per environment.

> [card] [CLI reference](https://docs.reliantlabs.io/reference/cli.md#reliant-forge-cloud-identity)
>
> Every `cloud identity` verb and flag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.