@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-admin/references/identity-commands.md

@@ -1,662 +1,109 @@
 # Identity CLI Command Reference
 
-Complete reference for all `uip admin` commands.
+Complete reference for `uip admin` commands.
 
-## Global Flags
+## Global usage
 
-Every command accepts these flags (omitted from per-command tables):
+Run `uip login status --output json` first. Organization ID comes from the active login session.
 
-| Flag | Description |
-|------|-------------|
-| `--output <format>` | Output format: `json`, `table`, `yaml`, `plain` (default: json) |
-| `--login-validity <minutes>` | Override token validity — forces refresh if token expires within this window |
-
-Organization ID is resolved automatically from the active login session.
-
-## Prerequisites
-
-```bash
-uip login status --output json
-```
-
----
+Every command accepts `--output <format>` (`json`, `table`, `yaml`, or `plain`; default `json`) and `--login-validity <minutes>` (overrides token validity and forces refresh when the token expires within this window).
 
 ## Users — `uip admin users`
 
-### `users list`
-
-List users in a partition.
-
-```bash
-uip admin users list --output json
-```
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `-s, --search <term>` | No | Search by name or email |
-| `--sort-by <field>` | No | Sort field (e.g., `UserName`, `Email`) |
-| `--sort-order <asc\|desc>` | No | Sort direction (default: asc) |
-| `-l, --limit <number>` | No | Items to return (default: 20) |
-| `--offset <number>` | No | Items to skip (default: 0) |
-
-**Output code:** `UserList`
-
-### `users get`
-
-Get user details by ID.
-
-```bash
-uip admin users get <USER_ID> --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<USER_ID>` | Yes | User ID (UUID) |
-
-**Output code:** `UserDetails`
-
-### `users create`
-
-Create a new user.
-
-```bash
-uip admin users create <USERNAME> \
-  --email <EMAIL> \
-  --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<USERNAME>` | Yes | Username |
-| `-e, --email <email>` | Yes | Email address |
-| `-n, --name <name>` | No | First name |
-| `--surname <surname>` | No | Last name |
-
-**Output code:** `UserCreated`
-
-### `users update`
-
-Update an existing user. At least one field flag is required.
-
-```bash
-uip admin users update <USER_ID> \
-  --email <NEW_EMAIL> \
-  --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<USER_ID>` | Yes | User ID (UUID) |
-| `-e, --email <email>` | No | New email |
-| `-n, --name <name>` | No | New first name |
-| `--surname <surname>` | No | New last name |
-
-**Output code:** `UserUpdated`
-
-### `users delete`
-
-Delete a user by ID.
-
-```bash
-uip admin users delete <USER_ID> --output json
-```
-
-**Output code:** `UserDeleted`
-
-### `users invite`
-
-Invite users by email. Sends an invitation to join the organization.
-
-```bash
-uip admin users invite \
-  --email "user@example.com" \
-  --name "John" \
-  --surname "Doe" \
-  --output json
-```
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `-e, --email <email>` | Yes | Email address to invite |
-| `-n, --name <name>` | No | First name |
-| `--surname <surname>` | No | Last name |
-
-Always include `--name` and `--surname` when the user's full name is known. Invite one user at a time.
-
-**Output code:** `UsersInvited`
-
----
+| Command | Usage | Arguments and flags | Output |
+|---|---|---|---|
+| `list` | `uip admin users list --output json` | `-s, --search <term>`; `--sort-by <field>` (for example, `UserName`, `Email`); `--sort-order <asc\|desc>` (default `asc`); `-l, --limit <number>` (default `20`); `--offset <number>` (default `0`) | `UserList` |
+| `get` | `uip admin users get <USER_ID> --output json` | `<USER_ID>` required, UUID | `UserDetails` |
+| `create` | `uip admin users create <USERNAME> --email <EMAIL> --output json` | `<USERNAME>` and `-e, --email <email>` required; `-n, --name <name>`; `--surname <surname>` | `UserCreated` |
+| `update` | `uip admin users update <USER_ID> --email <NEW_EMAIL> --output json` | `<USER_ID>` required, UUID; at least one of `-e, --email <email>`, `-n, --name <name>`, `--surname <surname>` required | `UserUpdated` |
+| `delete` | `uip admin users delete <USER_ID> --output json` | `<USER_ID>` required | `UserDeleted` |
+| `invite` | `uip admin users invite --email <EMAIL> --output json` | `-e, --email <email>` required; `-n, --name <name>`; `--surname <surname>`. Always include name and surname when known; invite one user at a time. | `UsersInvited` |
 
 ## Groups — `uip admin groups`
 
-> **Group ID is a positional argument, not a flag.** Write `groups get <GROUP_ID>`, NOT `groups get --group-id <GROUP_ID>`. Same for `members add`, `members revoke`, `members list`, `update`, `delete`.
-
-### `groups list`
-
-List all groups in a partition.
-
-```bash
-uip admin groups list --output json
-```
-
-**Output code:** `GroupList`
-
-### `groups get`
-
-Get group details by ID.
-
-```bash
-uip admin groups get <GROUP_ID> --output json
-```
-
-**Output code:** `GroupDetails`
-
-### `groups create`
-
-Create a new group. Group names must be unique within a partition.
-
-```bash
-uip admin groups create "<GROUP_NAME>" --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<GROUP_NAME>` | Yes | Group name |
+Group IDs are positional, not flags. Run `groups get <GROUP_ID>`, not `groups get --group-id <GROUP_ID>`. This applies to `members add`, `members revoke`, `members list`, `update`, and `delete`.
 
-**Output code:** `GroupCreated`
-
-### `groups update`
-
-Rename a group.
-
-```bash
-uip admin groups update <GROUP_ID> \
-  --name "<NEW_NAME>" \
-  --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<GROUP_ID>` | Yes | Group ID (UUID) |
-| `-n, --name <name>` | Yes | New group name |
-
-**Output code:** `GroupUpdated`
-
-### `groups delete`
-
-Delete a group. Only custom groups can be deleted — built-in groups cannot.
-
-```bash
-uip admin groups delete <GROUP_ID> --output json
-```
-
-**Output code:** `GroupDeleted`
-
-### `groups members list`
-
-List members of a group.
-
-```bash
-uip admin groups members list <GROUP_ID> --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<GROUP_ID>` | Yes | Group ID (UUID) |
-| `-l, --limit <number>` | No | Items to return (default: 50) |
-| `--offset <number>` | No | Items to skip (default: 0) |
-
-**Output code:** `GroupMembers`
-
-### `groups members add`
-
-Add users to a group. User IDs are required — resolve them via `users list` first.
-
-```bash
-uip admin groups members add <GROUP_ID> \
-  --user-ids "<USER_ID_1>,<USER_ID_2>" \
-  --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<GROUP_ID>` | Yes | Group ID (UUID) |
-| `--user-ids <ids>` | Yes | Comma-separated user IDs (UUIDs) |
-
-**Output code:** `GroupMembersAdded`
-
-### `groups members revoke`
-
-Remove users from a group.
-
-```bash
-uip admin groups members revoke <GROUP_ID> \
-  --user-ids "<USER_ID>" \
-  --output json
-```
-
-**Output code:** `GroupMembersRevoked`
-
----
+| Command | Usage | Arguments and flags | Output |
+|---|---|---|---|
+| `list` | `uip admin groups list --output json` | None | `GroupList` |
+| `get` | `uip admin groups get <GROUP_ID> --output json` | `<GROUP_ID>` required, UUID | `GroupDetails` |
+| `create` | `uip admin groups create "<GROUP_NAME>" --output json` | `<GROUP_NAME>` required; unique within a partition | `GroupCreated` |
+| `update` | `uip admin groups update <GROUP_ID> --name "<NEW_NAME>" --output json` | `<GROUP_ID>` required, UUID; `-n, --name <name>` required | `GroupUpdated` |
+| `delete` | `uip admin groups delete <GROUP_ID> --output json` | Only custom groups can be deleted; built-in groups cannot | `GroupDeleted` |
+| `members list` | `uip admin groups members list <GROUP_ID> --output json` | `<GROUP_ID>` required, UUID; `-l, --limit <number>` (default `50`); `--offset <number>` (default `0`) | `GroupMembers` |
+| `members add` | `uip admin groups members add <GROUP_ID> --user-ids "<USER_ID_1>,<USER_ID_2>" --output json` | `<GROUP_ID>` required; `--user-ids <ids>` required, comma-separated UUIDs. Run `users list` first to resolve IDs. | `GroupMembersAdded` |
+| `members revoke` | `uip admin groups members revoke <GROUP_ID> --user-ids "<USER_ID>" --output json` | `<GROUP_ID>` and `--user-ids <ids>` required | `GroupMembersRevoked` |
 
 ## Robot Accounts — `uip admin robot-accounts`
 
-> **IDs and names are positional arguments, not flags.** Write `robot-accounts get <ID>`, NOT `robot-accounts get --id <ID>`. Same for `create <NAME>`, `update <ID>`, `delete <ID>`.
-
-### `robot-accounts list`
-
-List robot accounts in a partition.
-
-```bash
-uip admin robot-accounts list --output json
-```
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `-s, --search <term>` | No | Search by name |
-| `--sort-by <field>` | No | Sort field (e.g., `Name`) |
-| `--sort-order <asc\|desc>` | No | Sort direction (default: asc) |
-| `-l, --limit <number>` | No | Items to return (default: 20) |
-| `--offset <number>` | No | Items to skip (default: 0) |
-
-**Output code:** `RobotAccountList`
-
-### `robot-accounts get`
-
-Get robot account details.
-
-```bash
-uip admin robot-accounts get <ROBOT_ACCOUNT_ID> --output json
-```
-
-**Output code:** `RobotAccountDetails`
-
-### `robot-accounts create`
-
-Create a new robot account. Names must be unique within a partition.
-
-```bash
-uip admin robot-accounts create "<NAME>" \
-  --display-name "<DISPLAY_NAME>" \
-  --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<NAME>` | Yes | Robot account name (unique) |
-| `--display-name <name>` | No | Display name (defaults to name) |
-
-**Output code:** `RobotAccountCreated`
-
-### `robot-accounts update`
-
-Update a robot account. At least one field flag is required.
-
-```bash
-uip admin robot-accounts update <ROBOT_ACCOUNT_ID> \
-  --display-name "<NEW_DISPLAY_NAME>" \
-  --output json
-```
-
-**Output code:** `RobotAccountUpdated`
-
-### `robot-accounts delete`
-
-Delete a robot account.
-
-```bash
-uip admin robot-accounts delete <ROBOT_ACCOUNT_ID> --output json
-```
-
-**Output code:** `RobotAccountDeleted`
+IDs and names are positional, not flags. Run `robot-accounts get <ID>`, not `robot-accounts get --id <ID>`. This applies to `create <NAME>`, `update <ID>`, and `delete <ID>`.
 
----
+| Command | Usage | Arguments and flags | Output |
+|---|---|---|---|
+| `list` | `uip admin robot-accounts list --output json` | `-s, --search <term>`; `--sort-by <field>` (for example, `Name`); `--sort-order <asc\|desc>` (default `asc`); `-l, --limit <number>` (default `20`); `--offset <number>` (default `0`) | `RobotAccountList` |
+| `get` | `uip admin robot-accounts get <ROBOT_ACCOUNT_ID> --output json` | ID positional and required | `RobotAccountDetails` |
+| `create` | `uip admin robot-accounts create "<NAME>" --display-name "<DISPLAY_NAME>" --output json` | `<NAME>` required and unique; `--display-name <name>` optional, defaults to name | `RobotAccountCreated` |
+| `update` | `uip admin robot-accounts update <ROBOT_ACCOUNT_ID> --display-name "<NEW_DISPLAY_NAME>" --output json` | ID positional; at least one field flag required; `--display-name <name>` | `RobotAccountUpdated` |
+| `delete` | `uip admin robot-accounts delete <ROBOT_ACCOUNT_ID> --output json` | ID positional and required | `RobotAccountDeleted` |
 
 ## External Apps — `uip admin external-apps`
 
-> **IDs and names are positional arguments, not flags.** Write `external-apps create "My App"`, NOT `external-apps create --name "My App"`. Same for `get <CLIENT_ID>`, `update <ID>`, `delete <ID>`, `generate-secret <ID>`, `delete-secret <ID>`.
->
-> **Non-confidential apps only support `--user-scope`.** Do NOT combine `--non-confidential` with `--app-scope` — the CLI will reject it. If user wants app-only scopes, use confidential (default).
->
-> **`--redirect-uri` is required** for `--non-confidential` apps and any app with `--user-scope`. Always ask the user for their callback URL — do not omit it.
+IDs and names are positional, not flags. Run `external-apps create "<APP_NAME>"`, not `external-apps create --name "<APP_NAME>"`. This applies to `get <CLIENT_ID>`, `update <ID>`, `delete <ID>`, `generate-secret <ID>`, and `delete-secret <ID>`.
 
-### `external-apps list`
+Non-confidential apps support only `--user-scope`; never combine `--non-confidential` with `--app-scope`. Use confidential apps (default) for app-only scopes. `--redirect-uri` is required for `--non-confidential` apps and any app with `--user-scope`; always ask for the callback URL and do not omit it.
 
-List external OAuth2 apps in a partition.
+| Command | Usage | Arguments and flags | Output |
+|---|---|---|---|
+| `list` | `uip admin external-apps list --output json` | None | `ExternalClientList` |
+| `get` | `uip admin external-apps get <CLIENT_ID> --output json` | `<CLIENT_ID>` required; returns resources, scopes, and federated credentials | `ExternalClientDetails` |
+| `create` | `uip admin external-apps create "<APP_NAME>" --app-scope "<SCOPES>" --output json` | `<APP_NAME>` required; at least one of `--app-scope <scopes>`, `--user-scope <scopes>`; `--scope <scopes>` deprecated alias for `--app-scope`; `--redirect-uri <uri>` optional unless required above, comma-separated; `--non-confidential`; `--no-secret`. Confidential by default; generates a client secret. | `ExternalClientCreated` |
+| `update` | `uip admin external-apps update <CLIENT_ID> --name "<NEW_NAME>" --app-scope "<SCOPES>" --output json` | `<CLIENT_ID>` required; at least one field flag required; `-n, --name <name>`; `--redirect-uri <uri>`; `--app-scope <scopes>` and `--user-scope <scopes>` replace existing scopes; `--scope <scopes>` deprecated alias for `--app-scope` | `ExternalClientUpdated` |
+| `delete` | `uip admin external-apps delete <CLIENT_ID> --output json` | `<CLIENT_ID>` required | `ExternalClientDeleted` |
+| `generate-secret` | `uip admin external-apps generate-secret <CLIENT_ID> --output json` | `<CLIENT_ID>` required; `--description <text>`; `--expiration <date>` ISO 8601 | `ExternalClientSecretGenerated` |
+| `delete-secret` | `uip admin external-apps delete-secret <SECRET_ID> --output json` | `<SECRET_ID>` required, numeric; takes no client ID | `ExternalClientSecretDeleted` |
 
-```bash
-uip admin external-apps list --output json
-```
+### Federated credentials
 
-**Output code:** `ExternalClientList`
-
-### `external-apps get`
-
-Get external app details including resources, scopes, and federated credentials.
-
-```bash
-uip admin external-apps get <CLIENT_ID> --output json
-```
-
-**Output code:** `ExternalClientDetails`
-
-### `external-apps create`
-
-Create an external app. Confidential by default (generates client secret). Use `--non-confidential` for public clients.
-
-```bash
-uip admin external-apps create "<APP_NAME>" \
-  --app-scope "OR.Folders,OR.Assets,OR.Queues" \
-  --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<APP_NAME>` | Yes | App display name |
-| `--app-scope <scopes>` | Conditional | Comma-separated application scopes (at least one scope type required) |
-| `--user-scope <scopes>` | Conditional | Comma-separated user (delegated) scopes |
-| `--scope <scopes>` | No | Deprecated alias for `--app-scope` |
-| `--redirect-uri <uri>` | Conditional | OAuth2 redirect URI(s), comma-separated. Required with `--user-scope` or `--non-confidential` |
-| `--non-confidential` | No | Create public client (no secret) |
-| `--no-secret` | No | Skip generating secret on creation |
-
-**Output code:** `ExternalClientCreated`
-
-### `external-apps update`
-
-Update an external app. At least one field flag is required.
-
-```bash
-uip admin external-apps update <CLIENT_ID> \
-  --name "<NEW_NAME>" \
-  --app-scope "OR.Folders,OR.Jobs" \
-  --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<CLIENT_ID>` | Yes | External app ID |
-| `-n, --name <name>` | No | New display name |
-| `--redirect-uri <uri>` | No | New redirect URI(s) |
-| `--app-scope <scopes>` | No | New application scopes (replaces existing) |
-| `--user-scope <scopes>` | No | New user scopes (replaces existing) |
-| `--scope <scopes>` | No | Deprecated alias for `--app-scope` |
-
-**Output code:** `ExternalClientUpdated`
-
-### `external-apps delete`
-
-Delete an external app.
-
-```bash
-uip admin external-apps delete <CLIENT_ID> --output json
-```
-
-**Output code:** `ExternalClientDeleted`
-
-### `external-apps generate-secret`
-
-Generate a new secret for an external app. Value returned only once.
-
-```bash
-uip admin external-apps generate-secret <CLIENT_ID> --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<CLIENT_ID>` | Yes | External app ID |
-| `--description <text>` | No | Description for the secret |
-| `--expiration <date>` | No | Expiration date (ISO 8601, e.g., `2027-01-01`) |
-
-**Output code:** `ExternalClientSecretGenerated`
-
-### `external-apps delete-secret`
-
-Delete a specific secret. Takes only the secret ID — no client ID needed.
-
-```bash
-uip admin external-apps delete-secret <SECRET_ID> --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<SECRET_ID>` | Yes | Secret ID (numeric) |
-
-**Output code:** `ExternalClientSecretDeleted`
-
-### `external-apps federated-credentials list`
-
-List federated credentials for an external app.
-
-```bash
-uip admin external-apps federated-credentials list <CLIENT_ID> --output json
-```
-
-**Output code:** `FederatedCredentialList`
-
-### `external-apps federated-credentials get`
-
-Get a federated credential by ID.
-
-```bash
-uip admin external-apps federated-credentials get <CLIENT_ID> <CREDENTIAL_ID> --output json
-```
-
-**Output code:** `FederatedCredentialDetails`
-
-### `external-apps federated-credentials create`
-
-Create a federated credential. Maps an external identity (e.g., GitHub Actions OIDC) to this app.
-
-```bash
-uip admin external-apps federated-credentials create <CLIENT_ID> \
-  --name "GitHub Actions" \
-  --issuer "https://token.actions.githubusercontent.com" \
-  --audience "<AUDIENCE>" \
-  --subject "repo:myorg/myrepo:ref:refs/heads/main" \
-  --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<CLIENT_ID>` | Yes | External app ID |
-| `-n, --name <name>` | Yes | Credential name |
-| `--issuer <url>` | Yes | Token issuer URL |
-| `--audience <audience>` | Yes | Expected audience claim |
-| `--subject <subject>` | Yes | Expected subject claim |
-| `--description <text>` | No | Description |
-
-**Output code:** `FederatedCredentialCreated`
-
-### `external-apps federated-credentials update`
-
-Update a federated credential. All fields required (full replace).
-
-```bash
-uip admin external-apps federated-credentials update <CLIENT_ID> <CREDENTIAL_ID> \
-  --name "Updated Name" \
-  --issuer "https://token.actions.githubusercontent.com" \
-  --audience "<AUDIENCE>" \
-  --subject "repo:myorg/myrepo:ref:refs/heads/release" \
-  --output json
-```
-
-**Output code:** `FederatedCredentialUpdated`
-
-### `external-apps federated-credentials delete`
-
-Delete a federated credential.
-
-```bash
-uip admin external-apps federated-credentials delete <CLIENT_ID> <CREDENTIAL_ID> --output json
-```
-
-**Output code:** `FederatedCredentialDeleted`
-
----
+| Command | Usage | Arguments and flags | Output |
+|---|---|---|---|
+| `list` | `uip admin external-apps federated-credentials list <CLIENT_ID> --output json` | `<CLIENT_ID>` required | `FederatedCredentialList` |
+| `get` | `uip admin external-apps federated-credentials get <CLIENT_ID> <CREDENTIAL_ID> --output json` | Both IDs required | `FederatedCredentialDetails` |
+| `create` | `uip admin external-apps federated-credentials create <CLIENT_ID> --name "<NAME>" --issuer "<ISSUER>" --audience "<AUDIENCE>" --subject "<SUBJECT>" --output json` | `<CLIENT_ID>`; `-n, --name <name>`; `--issuer <url>`; `--audience <audience>`; and `--subject <subject>` required; `--description <text>` optional. Maps an external identity to the app. | `FederatedCredentialCreated` |
+| `update` | `uip admin external-apps federated-credentials update <CLIENT_ID> <CREDENTIAL_ID> --name "<NAME>" --issuer "<ISSUER>" --audience "<AUDIENCE>" --subject "<SUBJECT>" --output json` | All fields required; full replace | `FederatedCredentialUpdated` |
+| `delete` | `uip admin external-apps federated-credentials delete <CLIENT_ID> <CREDENTIAL_ID> --output json` | Both IDs required | `FederatedCredentialDeleted` |
 
 ## Personal Access Tokens — `uip admin pat`
 
-> **Token ID is a positional argument for `revoke` and `regenerate`.** Write `pat revoke <TOKEN_ID>`, NOT `pat revoke --token-id <TOKEN_ID>`.
-
-### `pat list`
-
-List personal access tokens. By default lists your own. Use `--scope all` for all org tokens (admin only).
-
-```bash
-uip admin pat list --output json
-```
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--scope <scope>` | No | `all` to list all org tokens (admin only) |
-| `--search <term>` | No | Filter by user search term (implies `--scope all`) |
-| `-l, --limit <number>` | No | Items to return (default: 50) |
-| `--offset <number>` | No | Items to skip (default: 0) |
-
-**Output code:** `PatList`
-
-### `pat create`
-
-Create a personal access token. Token value returned only once.
-
-```bash
-uip admin pat create \
-  --description "CI/CD pipeline token" \
-  --expiration "2027-01-15" \
-  --scope "OR.Folders.Read,OR.Jobs.Read" \
-  --output json
-```
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--description <text>` | Yes | Token description |
-| `--expiration <date>` | Yes | Expiration date (ISO 8601: `YYYY-MM-DD`). Max 360 days (org default) |
-| `--scope <scopes>` | Yes | Comma-separated scope names |
-
-**Output code:** `PatCreated`
-
-### `pat revoke`
-
-Revoke a personal access token.
-
-```bash
-uip admin pat revoke <TOKEN_ID> --output json
-```
-
-**Output code:** `PatRevoked`
-
-### `pat regenerate`
-
-Regenerate a token with new expiration. New token value returned only once.
-
-```bash
-uip admin pat regenerate <TOKEN_ID> --expiration "2028-01-15" --output json
-```
-
-| Argument/Flag | Required | Description |
-|---------------|----------|-------------|
-| `<TOKEN_ID>` | Yes | Token ID (UUID) |
-| `--expiration <date>` | Yes | New expiration date (ISO 8601: `YYYY-MM-DD`) |
-
-**Output code:** `PatRegenerated`
+For `revoke` and `regenerate`, token ID is positional. Run `pat revoke <TOKEN_ID>`, not `pat revoke --token-id <TOKEN_ID>`.
 
----
+| Command | Usage | Arguments and flags | Output |
+|---|---|---|---|
+| `list` | `uip admin pat list --output json` | Lists your tokens by default; `--scope <scope>`: `all` lists all organization tokens (admin only); `--search <term>` filters by user and implies `--scope all`; `-l, --limit <number>` (default `50`); `--offset <number>` (default `0`) | `PatList` |
+| `create` | `uip admin pat create --description "<DESCRIPTION>" --expiration "<DATE>" --scope "<SCOPES>" --output json` | `--description <text>`, `--expiration <date>`, and `--scope <scopes>` required; date ISO 8601 `YYYY-MM-DD`; maximum 360 days (organization default); scopes comma-separated | `PatCreated` |
+| `revoke` | `uip admin pat revoke <TOKEN_ID> --output json` | `<TOKEN_ID>` required and positional | `PatRevoked` |
+| `regenerate` | `uip admin pat regenerate <TOKEN_ID> --expiration "<DATE>" --output json` | `<TOKEN_ID>` positional UUID; `--expiration <date>` required, ISO 8601 `YYYY-MM-DD` | `PatRegenerated` |
 
 ## SMTP — `uip admin smtp`
 
-### `smtp get`
-
-Get current SMTP settings.
-
-```bash
-uip admin smtp get --output json
-```
-
-**Output code:** `SmtpSettings`
-
-### `smtp update`
-
-Update SMTP settings. At least one field required.
-
-```bash
-uip admin smtp update \
-  --host "smtp.example.com" \
-  --port 587 \
-  --enable-ssl "true" \
-  --username "smtp-user" \
-  --password "smtp-pass" \
-  --from-address "noreply@example.com" \
-  --output json
-```
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--host <host>` | No | SMTP server hostname |
-| `--port <port>` | No | SMTP server port (1-65535) |
-| `--username <username>` | No | SMTP auth username |
-| `--password <password>` | No | SMTP auth password |
-| `--domain <domain>` | No | SMTP auth domain |
-| `--enable-ssl <value>` | No | Enable SSL/TLS: `true` or `false` |
-| `--use-default-credentials <value>` | No | Use Windows credentials: `true` or `false` |
-| `--from-address <email>` | No | Sender email address |
-| `--from-display-name <name>` | No | Sender display name |
-| `--connection-timeout <ms>` | No | Connection timeout in milliseconds (1-300000) |
-
-**Output code:** `SmtpSettingsUpdated`
-
-### `smtp delete`
-
-Delete all SMTP settings. Reverts to platform defaults.
-
-```bash
-uip admin smtp delete --output json
-```
-
-**Output code:** `SmtpSettingsDeleted`
-
-### `smtp test`
-
-Test SMTP by sending a test email. Uses saved settings by default. Pass SMTP options to test custom settings without saving (requires `--password` when using custom settings).
-
-```bash
-uip admin smtp test --recipient "admin@example.com" --output json
-```
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--recipient <email>` | Yes | Email address to send test to |
-| `--host <host>` | No | Custom SMTP host (test only) |
-| `--port <port>` | No | Custom SMTP port (test only) |
-| `--password <password>` | Conditional | Required when using custom settings |
-| *(other SMTP flags)* | No | Same as `smtp update` — used for testing only |
-
-**Output code:** `SmtpTestSent`
-
----
+| Command | Usage | Arguments and flags | Output |
+|---|---|---|---|
+| `get` | `uip admin smtp get --output json` | None | `SmtpSettings` |
+| `update` | `uip admin smtp update --host "<HOST>" --port <PORT> --enable-ssl "<true\|false>" --username "<USERNAME>" --password "<PASSWORD>" --from-address "<EMAIL>" --output json` | At least one required: `--host <host>`; `--port <port>` (1–65535); `--username <username>`; `--password <password>`; `--domain <domain>`; `--enable-ssl <value>` (`true`/`false`); `--use-default-credentials <value>` (`true`/`false`); `--from-address <email>`; `--from-display-name <name>`; `--connection-timeout <ms>` (1–300000) | `SmtpSettingsUpdated` |
+| `delete` | `uip admin smtp delete --output json` | Deletes all settings and reverts to platform defaults | `SmtpSettingsDeleted` |
+| `test` | `uip admin smtp test --recipient "<EMAIL>" --output json` | `--recipient <email>` required; `--host <host>`, `--port <port>`, `--password <password>`, and all other SMTP update flags optional. Uses saved settings by default; custom settings are test-only and require `--password`. | `SmtpTestSent` |
 
 ## Scopes — `uip admin scopes`
 
-### `scopes list`
-
-List all available OAuth2 scopes grouped by resource. Use to discover valid scope names for external apps and PATs.
-
-```bash
-uip admin scopes list --output json
-```
-
-**Output code:** `ScopesList`
-
----
+Run `uip admin scopes list --output json` to list available OAuth2 scopes grouped by resource for external apps and PATs. Output: `ScopesList`.
 
-## Output Etiquette — after any identity mutation
+## Output etiquette after identity mutations
 
-Applies to every identity-side mutation: `users create / update / invite / delete`, `groups create / update / delete`, `groups members add / revoke`, `robot-accounts create / update / delete`, `external-apps create / update / delete / generate-secret / delete-secret`.
+Apply these steps to `users create / update / invite / delete`, `groups create / update / delete`, `groups members add / revoke`, `robot-accounts create / update / delete`, and `external-apps create / update / delete / generate-secret / delete-secret`:
 
-1. Show the command result (success or failure).
-2. For creates: display the new resource ID.
-3. For `external-apps create` or `generate-secret`: **highlight the secret value and warn user to save it** — it appears only once in the creation response.
+1. Show the command result, success or failure.
+2. For creates, display the new resource ID.
+3. For `external-apps create` and `generate-secret`, highlight the secret value and warn the user to save it; it appears only once in the creation response.
 4. Offer logical next steps:
-   - After creating a robot account → "Assign to a group for role-based access?"
-   - After creating an external app → "Generate an additional secret?"
-   - After inviting a user → "Check user list to see when they accept?"
+   - After creating a robot account: “Assign to a group for role-based access?”
+   - After creating an external app: “Generate an additional secret?”
+   - After inviting a user: “Check user list to see when they accept?”