cloudfoundry · duanemay · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/README.md b/README.md
@@ -2,6 +2,12 @@
 
 CLI for [UAA](https://github.com/cloudfoundry/uaa) written in golang. This is an alterntive to using uaac which is wirtten in Ruby.  At this time it performs a limited subset of the features provided by the [uaac](https://github.com/cloudfoundry/cf-uaac) gem.  The team plans to continue development on the golang CLI going forward, and once it's considered fully GA, intends to place it alongside uaac with a long-term intention of one day deprecating uaac.
 
+### Command Reference
+
+See the [Command Reference](docs/commands.md) for the full list of commands and their options.
+
+> **Migrating from uaac?** See the [Migrating from uaac](docs/migrating-from-uaac.md) guide for a side-by-side command reference.
+
 ### Goals
 
 - To provide a CLI which can be easily installed in environments without a functioning Ruby setup

diff --git a/docs/commands.md b/docs/commands.md
@@ -0,0 +1,68 @@
+# Command Reference
+
+All commands support `-v` / `--verbose` to print detailed HTTP request/response information.
+
+Each command name below links to a page with a full description, including all available flags and usage examples.
+
+## Getting Started
+
+| Command | Description |
+|---------|-------------|
+| [`target`](commands/target.md) | Set the URL of the UAA you'd like to target |
+| [`context`](commands/context.md) | See information about the currently active CLI context |
+| [`info`](commands/info.md) | See version and global configurations for the targeted UAA |
+| [`version`](commands/version.md) | Print CLI version |
+
+## Getting Tokens
+
+| Command | Description |
+|---------|-------------|
+| [`get-client-credentials-token`](commands/get-client-credentials-token.md) | Obtain an access token using the `client_credentials` grant type |
+| [`get-password-token`](commands/get-password-token.md) | Obtain an access token using the `password` grant type |
+| [`get-authcode-token`](commands/get-authcode-token.md) | Obtain an access token using the `authorization_code` grant type |
+| [`get-implicit-token`](commands/get-implicit-token.md) | Obtain an access token using the `implicit` grant type |
+| [`refresh-token`](commands/refresh-token.md) | Obtain a new access token using a refresh token |
+| [`get-token-key`](commands/get-token-key.md) | View the key for validating UAA's JWT token signatures |
+| [`get-token-keys`](commands/get-token-keys.md) | View all keys the UAA has used to sign JWT tokens |
+
+## Managing Clients
+
+| Command | Description |
+|---------|-------------|
+| [`create-client`](commands/create-client.md) | Create an OAuth client registration in the UAA |
+| [`update-client`](commands/update-client.md) | Update an OAuth client registration in the UAA |
+| [`delete-client`](commands/delete-client.md) | Delete a client registration |
+| [`get-client`](commands/get-client.md) | View a client registration |
+| [`list-clients`](commands/list-clients.md) | See all clients in the targeted UAA |
+| [`set-client-secret`](commands/set-client-secret.md) | Update the secret for a client |
+
+## Managing Users
+
+| Command | Description |
+|---------|-------------|
+| [`create-user`](commands/create-user.md) | Create a user |
+| [`get-user`](commands/get-user.md) | Look up a user by username |
+| [`list-users`](commands/list-users.md) | Search and list users with SCIM filters |
+| [`delete-user`](commands/delete-user.md) | Delete a user by username |
+| [`activate-user`](commands/activate-user.md) | Activate a user by username |
+| [`deactivate-user`](commands/deactivate-user.md) | Deactivate a user by username |
+
+## Managing Groups
+
+| Command | Description |
+|---------|-------------|
+| [`create-group`](commands/create-group.md) | Create a group |
+| [`get-group`](commands/get-group.md) | Look up a group by group name |
+| [`list-groups`](commands/list-groups.md) | Search and list groups with SCIM filters |
+| [`add-member`](commands/add-member.md) | Add a user to a group |
+| [`remove-member`](commands/remove-member.md) | Remove a user from a group |
+| [`map-group`](commands/map-group.md) | Map a UAA group to an external group from an identity provider |
+| [`unmap-group`](commands/unmap-group.md) | Remove a mapping between a UAA group and an external group |
+| [`list-group-mappings`](commands/list-group-mappings.md) | List all mappings between UAA groups and external groups |
+
+## Miscellaneous
+
+| Command | Description |
+|---------|-------------|
+| [`curl`](commands/curl.md) | Make an authenticated HTTP request to a UAA endpoint |
+| [`userinfo`](commands/userinfo.md) | See claims about the authenticated user |
diff --git a/docs/commands/activate-user.md b/docs/commands/activate-user.md
@@ -0,0 +1,32 @@
+# activate-user
+
+[← Command Reference](../commands.md)
+
+Activate a previously deactivated user account by username.
+
+## Usage
+
+```
+uaa activate-user USERNAME
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa activate-user bob
+```
+
+## See Also
+
+- [deactivate-user](deactivate-user.md)
+- [get-user](get-user.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/add-member.md b/docs/commands/add-member.md
@@ -0,0 +1,33 @@
+# add-member
+
+[← Command Reference](../commands.md)
+
+Add a user to a group.
+
+## Usage
+
+```
+uaa add-member GROUPNAME USERNAME
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa add-member cloud_controller.read bob
+```
+
+## See Also
+
+- [remove-member](remove-member.md)
+- [get-group](get-group.md)
+- [create-group](create-group.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/context.md b/docs/commands/context.md
@@ -0,0 +1,43 @@
+# context
+
+[← Command Reference](../commands.md)
+
+Display information about the currently active CLI context, including the cached access token and its metadata.
+
+## Usage
+
+```
+uaa context [flags]
+```
+
+A context represents a previously fetched access token and associated metadata such as the scopes that token contains. The uaa CLI caches these results in a local file so that they may be used when issuing requests that require an Authorization header.
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--access_token` | | `false` | Display the context's raw access token |
+| `--auth_header` | `-a` | `false` | Display the context's token type and access token (suitable for use as an Authorization header value) |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+# Show current context
+uaa context
+
+# Show the raw access token
+uaa context --access_token
+
+# Show the Authorization header value
+uaa context --auth_header
+```
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/create-client.md b/docs/commands/create-client.md
@@ -0,0 +1,80 @@
+# create-client
+
+[← Command Reference](../commands.md)
+
+Create an OAuth client registration in the UAA.
+
+## Usage
+
+```
+uaa create-client CLIENT_ID -s CLIENT_SECRET --authorized_grant_types GRANT_TYPES [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--client_secret` | `-s` | | Client secret |
+| `--authorized_grant_types` | | | Comma-separated list of grant types allowed for this client (e.g. `authorization_code`, `client_credentials`, `implicit`, `password`) |
+| `--scope` | | | Comma-separated scopes requested during `authorization_code`, `implicit`, or `password` grants |
+| `--authorities` | | | Comma-separated scopes requested during `client_credentials` grant |
+| `--redirect_uri` | | | Comma-separated callback URLs allowed for `authorization_code` and `implicit` grants |
+| `--display_name` | | | A human-readable name for this client |
+| `--access_token_validity` | | `0` | Seconds before issued access tokens expire |
+| `--refresh_token_validity` | | `0` | Seconds before issued refresh tokens expire |
+| `--clone` | | | Client ID of an existing client to clone configuration from |
+| `--zone` | `-z` | | Identity zone subdomain in which to create the client |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+# Authorization code client
+uaa create-client shinymail \
+    --client_secret secret \
+    --authorized_grant_types authorization_code \
+    --redirect_uri http://localhost:9090/*,https://shinymail.example.com/callback \
+    --scope mail.send,mail.read \
+    --display_name "Shinymail Web Mail Reader"
+
+# Client credentials (service-to-service) client
+uaa create-client background-emailer \
+    --client_secret secret \
+    --authorized_grant_types client_credentials \
+    --authorities notifications.write \
+    --display_name "Weekly newsletter email service"
+
+# Implicit (single-page app) client
+uaa create-client my-spa \
+    --authorized_grant_types implicit \
+    --redirect_uri http://localhost:9090/*,https://myapp.example.com/callback \
+    --scope openid,todo.read,todo.write \
+    --display_name "My Single-Page App"
+
+# Password grant client
+uaa create-client trusted-cli \
+    --client_secret mumstheword \
+    --authorized_grant_types password \
+    --scope cloud_controller.admin,uaa.admin
+
+# Clone an existing client
+uaa create-client trusted-cli-copy \
+    --clone trusted-cli \
+    --client_secret donttellanyone
+```
+
+## See Also
+
+- [update-client](update-client.md)
+- [delete-client](delete-client.md)
+- [get-client](get-client.md)
+- [list-clients](list-clients.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/create-group.md b/docs/commands/create-group.md
@@ -0,0 +1,42 @@
+# create-group
+
+[← Command Reference](../commands.md)
+
+Create a group (scope) in the UAA.
+
+## Usage
+
+```
+uaa create-group GROUPNAME [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--description` | `-d` | | A human-readable description of the group |
+| `--zone` | `-z` | | Identity zone subdomain in which to create the group |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa create-group cloud_controller.read
+uaa create-group cloud_controller.read --description "Read access to Cloud Controller resources"
+uaa create-group my-scope --zone my-zone
+```
+
+## See Also
+
+- [get-group](get-group.md)
+- [list-groups](list-groups.md)
+- [add-member](add-member.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/create-user.md b/docs/commands/create-user.md
@@ -0,0 +1,65 @@
+# create-user
+
+[← Command Reference](../commands.md)
+
+Create a user account in the UAA.
+
+## Usage
+
+```
+uaa create-user USERNAME [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--givenName` | | | Given (first) name (required) |
+| `--familyName` | | | Family (last) name (required) |
+| `--email` | | | Email address (required; flag may be specified multiple times) |
+| `--password` | `-p` | | User password (required for `uaa` origin) |
+| `--origin` | `-o` | `uaa` | Identity provider origin (e.g. `uaa`, `ldap`) |
+| `--phone` | | | Phone number (optional; flag may be specified multiple times) |
+| `--zone` | `-z` | | Identity zone subdomain in which to create the user |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+# Create a UAA-origin user
+uaa create-user bob \
+    --givenName Bob \
+    --familyName Smith \
+    --email bob@example.com \
+    --password s3cr3t
+
+# Create a user from an external identity provider
+uaa create-user alice \
+    --givenName Alice \
+    --familyName Jones \
+    --email alice@example.com \
+    --origin ldap
+
+# Create a user with multiple email addresses
+uaa create-user carol \
+    --givenName Carol \
+    --familyName White \
+    --email carol@example.com \
+    --email carol.white@work.example.com \
+    --password s3cr3t
+```
+
+## See Also
+
+- [get-user](get-user.md)
+- [list-users](list-users.md)
+- [delete-user](delete-user.md)
+
+---
+
+[← Command Reference](../commands.md)