diff --git a/README.md b/README.md
index 0e2d91f..c23768a 100644
--- 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
new file mode 100644
index 0000000..37b5d3a
--- /dev/null
+++ 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
new file mode 100644
index 0000000..6eeb09c
--- /dev/null
+++ 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
new file mode 100644
index 0000000..18d1ba2
--- /dev/null
+++ 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
new file mode 100644
index 0000000..152e331
--- /dev/null
+++ 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
new file mode 100644
index 0000000..8b314f5
--- /dev/null
+++ 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
new file mode 100644
index 0000000..b631b58
--- /dev/null
+++ 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
new file mode 100644
index 0000000..d32df51
--- /dev/null
+++ 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)
diff --git a/docs/commands/curl.md b/docs/commands/curl.md
new file mode 100644
index 0000000..dd5f35a
--- /dev/null
+++ b/docs/commands/curl.md
@@ -0,0 +1,50 @@
+# curl
+
+[← Command Reference](../commands.md)
+
+Make an authenticated HTTP request to a UAA endpoint.
+
+## Usage
+
+```
+uaa curl PATH [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--method` | `-X` | `GET` | HTTP method (GET, POST, PUT, DELETE, PATCH, etc.) |
+| `--data` | `-d` | | HTTP request body |
+| `--header` | `-H` | | Custom request header (flag may be specified multiple times) |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+# GET request
+uaa curl /info
+
+# POST with a JSON body
+uaa curl /oauth/clients \
+    -X POST \
+    -H "Content-Type: application/json" \
+    -d '{"client_id":"test","client_secret":"secret","authorized_grant_types":["client_credentials"]}'
+
+# DELETE
+uaa curl /oauth/clients/my-app -X DELETE
+
+# Multiple custom headers
+uaa curl /Users \
+    -H "Accept: application/json" \
+    -H "X-Identity-Zone-Id: my-zone"
+```
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/deactivate-user.md b/docs/commands/deactivate-user.md
new file mode 100644
index 0000000..242a20d
--- /dev/null
+++ b/docs/commands/deactivate-user.md
@@ -0,0 +1,39 @@
+# deactivate-user
+
+[← Command Reference](../commands.md)
+
+Deactivate a user account by username. The account is suspended but not deleted.
+
+## Usage
+
+```
+uaa deactivate-user USERNAME [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--zone` | `-z` | | Identity zone subdomain from which to deactivate the user |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa deactivate-user bob
+uaa deactivate-user bob --zone my-zone
+```
+
+## See Also
+
+- [activate-user](activate-user.md)
+- [delete-user](delete-user.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/delete-client.md b/docs/commands/delete-client.md
new file mode 100644
index 0000000..33b04a0
--- /dev/null
+++ b/docs/commands/delete-client.md
@@ -0,0 +1,39 @@
+# delete-client
+
+[← Command Reference](../commands.md)
+
+Delete an OAuth client registration from the UAA.
+
+## Usage
+
+```
+uaa delete-client CLIENT_ID [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--zone` | `-z` | | Identity zone subdomain in which to delete the client |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa delete-client my-app
+uaa delete-client my-app --zone my-zone
+```
+
+## See Also
+
+- [create-client](create-client.md)
+- [list-clients](list-clients.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/delete-user.md b/docs/commands/delete-user.md
new file mode 100644
index 0000000..6ce227d
--- /dev/null
+++ b/docs/commands/delete-user.md
@@ -0,0 +1,39 @@
+# delete-user
+
+[← Command Reference](../commands.md)
+
+Delete a user account by username.
+
+## Usage
+
+```
+uaa delete-user USERNAME [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--origin` | `-o` | `uaa` | Identity provider origin of the user to delete |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa delete-user bob
+uaa delete-user bob --origin ldap
+```
+
+## See Also
+
+- [get-user](get-user.md)
+- [deactivate-user](deactivate-user.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/get-authcode-token.md b/docs/commands/get-authcode-token.md
new file mode 100644
index 0000000..5cd9deb
--- /dev/null
+++ b/docs/commands/get-authcode-token.md
@@ -0,0 +1,52 @@
+# get-authcode-token
+
+[← Command Reference](../commands.md)
+
+Obtain an access token using the `authorization_code` grant type and save it to the active context. Opens a browser window for the user to authenticate.
+
+## Usage
+
+```
+uaa get-authcode-token CLIENT_ID -s CLIENT_SECRET --port REDIRECT_URI_PORT [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--client_secret` | `-s` | | Client secret |
+| `--port` | | | Port on which to run the local callback server. Must match a `localhost` redirect URI in the client registration. |
+| `--scope` | | `openid` | Comma-separated scopes to request in the token |
+| `--format` | | `jwt` | Token format. Available values: `jwt`, `opaque` |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa target https://uaa.example.com
+uaa get-client-credentials-token admin -s admin-secret
+uaa create-client my-app \
+    --authorized_grant_types authorization_code \
+    --redirect_uri http://localhost:9090/** \
+    --scope openid,cloud_controller.read
+uaa get-authcode-token my-app -s my-secret --port 9090
+uaa context
+```
+
+## Troubleshooting
+
+**Unknown redirect_uri error after signing in:**
+- The `--port` value must match a `http://localhost:PORT` entry in the client's `redirect_uri` list. Run `uaa get-client CLIENT_ID` to inspect the registration.
+
+**Token does not have expected scopes:**
+- Check the `scope` field of the client registration.
+- Verify the user has the correct group memberships.
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/get-client-credentials-token.md b/docs/commands/get-client-credentials-token.md
new file mode 100644
index 0000000..c2b928c
--- /dev/null
+++ b/docs/commands/get-client-credentials-token.md
@@ -0,0 +1,53 @@
+# get-client-credentials-token
+
+[← Command Reference](../commands.md)
+
+Obtain an access token using the `client_credentials` grant type and save it to the active context.
+
+## Usage
+
+```
+uaa get-client-credentials-token CLIENT_ID -s CLIENT_SECRET [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--client_secret` | `-s` | | Client secret |
+| `--format` | | `jwt` | Token format. Available values: `jwt`, `opaque` |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Background
+
+The client credentials grant type is used by clients performing actions on their own behalf, without the involvement of a user. It is one of the four authorization flows described in RFC 6749.
+
+After successfully running this command, the token is added to the CLI's current context and will be attached to subsequent requests to UAA endpoints requiring authorization.
+
+This flow is typically used for service-to-service operations. The `authorities` field of the client registration (not `scope`) determines what permissions are included in the token.
+
+## Examples
+
+```bash
+uaa target https://uaa.example.com
+uaa get-client-credentials-token my-client -s my-secret
+uaa context
+```
+
+## Troubleshooting
+
+**Unable to get a token:**
+- Verify the `client_id` and `client_secret` are correct and you are targeting the right UAA.
+- Ensure `client_credentials` is listed in the client's `authorized_grant_types`.
+
+**Token does not have expected scopes:**
+- Check the `authorities` field of the client registration — this controls scopes in `client_credentials` tokens, not the `scope` field.
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/get-client.md b/docs/commands/get-client.md
new file mode 100644
index 0000000..22a8a9e
--- /dev/null
+++ b/docs/commands/get-client.md
@@ -0,0 +1,40 @@
+# get-client
+
+[← Command Reference](../commands.md)
+
+View the registration details for an OAuth client.
+
+## Usage
+
+```
+uaa get-client CLIENT_ID [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--zone` | `-z` | | Identity zone subdomain in which to look up the client |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa get-client my-app
+uaa get-client my-app --zone my-zone
+```
+
+## See Also
+
+- [list-clients](list-clients.md)
+- [create-client](create-client.md)
+- [update-client](update-client.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/get-group.md b/docs/commands/get-group.md
new file mode 100644
index 0000000..8a4490b
--- /dev/null
+++ b/docs/commands/get-group.md
@@ -0,0 +1,41 @@
+# get-group
+
+[← Command Reference](../commands.md)
+
+Look up a group by group name.
+
+## Usage
+
+```
+uaa get-group GROUPNAME [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--attributes` | `-a` | | Comma-separated attributes to include in the response (improves query performance) |
+| `--zone` | `-z` | | Identity zone subdomain in which to look up the group |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa get-group cloud_controller.read
+uaa get-group cloud_controller.read --attributes id,displayName,members
+```
+
+## See Also
+
+- [list-groups](list-groups.md)
+- [create-group](create-group.md)
+- [add-member](add-member.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/get-implicit-token.md b/docs/commands/get-implicit-token.md
new file mode 100644
index 0000000..4396f6b
--- /dev/null
+++ b/docs/commands/get-implicit-token.md
@@ -0,0 +1,55 @@
+# get-implicit-token
+
+[← Command Reference](../commands.md)
+
+Obtain an access token using the `implicit` grant type and save it to the active context. Opens a browser window for the user to authenticate.
+
+## Usage
+
+```
+uaa get-implicit-token CLIENT_ID --port REDIRECT_URI_PORT [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--port` | | | Port on which to run the local callback server. Must match a `localhost` redirect URI in the client registration. |
+| `--scope` | | `openid` | Comma-separated scopes to request in the token |
+| `--format` | | `jwt` | Token format. Available values: `jwt`, `opaque` |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Background
+
+The implicit grant type is most commonly used for single-page web applications ("public clients") that cannot maintain a client secret. After the user authorizes, the access token is transmitted as part of the URI fragment. Because implicit clients have no secret, they are not issued refresh tokens.
+
+## Examples
+
+```bash
+uaa target https://uaa.example.com
+uaa get-client-credentials-token admin -s admin-secret
+uaa create-client my-spa \
+    --authorized_grant_types implicit \
+    --redirect_uri http://localhost:9090/**,https://myapp.example.com/** \
+    --scope openid,todo.read
+uaa get-implicit-token my-spa --port 9090
+uaa context
+```
+
+## Troubleshooting
+
+**Unknown redirect_uri error after signing in:**
+- The `--port` value must match a `http://localhost:PORT` entry in the client's `redirect_uri` list.
+
+**Token does not have expected scopes:**
+- Check the `scope` field of the client registration.
+- Verify the user has the correct group memberships.
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/get-password-token.md b/docs/commands/get-password-token.md
new file mode 100644
index 0000000..5ee2958
--- /dev/null
+++ b/docs/commands/get-password-token.md
@@ -0,0 +1,54 @@
+# get-password-token
+
+[← Command Reference](../commands.md)
+
+Obtain an access token using the resource owner password credentials (`password`) grant type and save it to the active context.
+
+## Usage
+
+```
+uaa get-password-token CLIENT_ID -s CLIENT_SECRET -u USERNAME -p PASSWORD [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--client_secret` | `-s` | | Client secret |
+| `--username` | `-u` | | Username |
+| `--password` | `-p` | | User password |
+| `--format` | | `jwt` | Token format. Available values: `jwt`, `opaque` |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Background
+
+The password grant type is used by highly trusted client applications (such as CLIs) where the user provides their credentials directly to the client. The client then exchanges those credentials for a token at the UAA.
+
+After successfully running this command, the token is added to the CLI's current context and will be attached to subsequent requests to UAA endpoints requiring authorization.
+
+## Examples
+
+```bash
+uaa target https://uaa.example.com
+uaa get-password-token cf -s "" -u admin -p admin-secret
+uaa context
+```
+
+## Troubleshooting
+
+**Unable to get a token:**
+- Verify `client_id`, `client_secret`, `username`, and `password` are all correct.
+- Ensure `password` is listed in the client's `authorized_grant_types`.
+
+**Token does not have expected scopes:**
+- Check the `scope` field of the client registration.
+- Verify the user has the correct group memberships. Token scopes are the intersection of the client's `scope` and the user's group memberships.
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/get-token-key.md b/docs/commands/get-token-key.md
new file mode 100644
index 0000000..e199b50
--- /dev/null
+++ b/docs/commands/get-token-key.md
@@ -0,0 +1,34 @@
+# get-token-key
+
+[← Command Reference](../commands.md)
+
+View the key the UAA uses to sign JWT tokens.
+
+## Usage
+
+```
+uaa get-token-key
+```
+
+Aliases: `token-key`
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa target https://uaa.example.com
+uaa get-token-key
+```
+
+## See Also
+
+- [get-token-keys](get-token-keys.md) — view all signing keys the UAA has used
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/get-token-keys.md b/docs/commands/get-token-keys.md
new file mode 100644
index 0000000..6b8291b
--- /dev/null
+++ b/docs/commands/get-token-keys.md
@@ -0,0 +1,32 @@
+# get-token-keys
+
+[← Command Reference](../commands.md)
+
+View all keys the UAA has used to sign JWT tokens.
+
+## Usage
+
+```
+uaa get-token-keys
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa target https://uaa.example.com
+uaa get-token-keys
+```
+
+## See Also
+
+- [get-token-key](get-token-key.md) — view the current (single) signing key
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/get-user.md b/docs/commands/get-user.md
new file mode 100644
index 0000000..0d05fa9
--- /dev/null
+++ b/docs/commands/get-user.md
@@ -0,0 +1,43 @@
+# get-user
+
+[← Command Reference](../commands.md)
+
+Look up a user account by username.
+
+## Usage
+
+```
+uaa get-user USERNAME [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--origin` | `-o` | | Identity provider to search (e.g. `uaa`, `ldap`). Searches all origins if omitted. |
+| `--attributes` | `-a` | | Comma-separated list of user attributes to return (improves query performance) |
+| `--zone` | `-z` | | Identity zone subdomain in which to find the user |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa get-user bob
+uaa get-user bob --origin ldap
+uaa get-user bob --attributes id,userName,emails
+```
+
+## See Also
+
+- [list-users](list-users.md)
+- [create-user](create-user.md)
+- [delete-user](delete-user.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/info.md b/docs/commands/info.md
new file mode 100644
index 0000000..343b16c
--- /dev/null
+++ b/docs/commands/info.md
@@ -0,0 +1,27 @@
+# info
+
+[← Command Reference](../commands.md)
+
+Display version and global configuration information for the targeted UAA.
+
+## Usage
+
+```
+uaa info
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa info
+```
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/list-clients.md b/docs/commands/list-clients.md
new file mode 100644
index 0000000..01edf1d
--- /dev/null
+++ b/docs/commands/list-clients.md
@@ -0,0 +1,39 @@
+# list-clients
+
+[← Command Reference](../commands.md)
+
+List all client registrations in the targeted UAA.
+
+## Usage
+
+```
+uaa list-clients [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--zone` | `-z` | | Identity zone subdomain in which to list clients |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa list-clients
+uaa list-clients --zone my-zone
+```
+
+## See Also
+
+- [get-client](get-client.md)
+- [create-client](create-client.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/list-group-mappings.md b/docs/commands/list-group-mappings.md
new file mode 100644
index 0000000..e65f752
--- /dev/null
+++ b/docs/commands/list-group-mappings.md
@@ -0,0 +1,32 @@
+# list-group-mappings
+
+[← Command Reference](../commands.md)
+
+List all mappings between UAA groups (scopes) and external groups from identity providers.
+
+## Usage
+
+```
+uaa list-group-mappings
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa list-group-mappings
+```
+
+## See Also
+
+- [map-group](map-group.md)
+- [unmap-group](unmap-group.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/list-groups.md b/docs/commands/list-groups.md
new file mode 100644
index 0000000..441d572
--- /dev/null
+++ b/docs/commands/list-groups.md
@@ -0,0 +1,52 @@
+# list-groups
+
+[← Command Reference](../commands.md)
+
+Search and list groups using SCIM filters.
+
+## Usage
+
+```
+uaa list-groups [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--filter` | | | A SCIM filter expression, e.g. `'id eq "a5e3f9fb-65a0-4033-a86c-11f4712e1fed"'` |
+| `--attributes` | `-a` | | Comma-separated attributes to include in results (improves query performance) |
+| `--sortBy` | `-b` | | Attribute to sort results by (e.g. `created`, `displayName`) |
+| `--sortOrder` | `-o` | | Sort direction: `ascending` or `descending` |
+| `--zone` | `-z` | | Identity zone subdomain from which to list groups |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+# List all groups
+uaa list-groups
+
+# Find a group by display name
+uaa list-groups --filter 'displayName eq "cloud_controller.read"'
+
+# List groups sorted by name
+uaa list-groups --sortBy displayName --sortOrder ascending
+
+# Return only id and displayName
+uaa list-groups --attributes id,displayName
+```
+
+## See Also
+
+- [get-group](get-group.md)
+- [create-group](create-group.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/list-users.md b/docs/commands/list-users.md
new file mode 100644
index 0000000..36c4bf5
--- /dev/null
+++ b/docs/commands/list-users.md
@@ -0,0 +1,65 @@
+# list-users
+
+[← Command Reference](../commands.md)
+
+Search and list user accounts using SCIM filters.
+
+## Usage
+
+```
+uaa list-users [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--filter` | | | A SCIM filter expression, e.g. `'userName eq "bob@example.com"'` |
+| `--attributes` | `-a` | | Comma-separated attributes to include in results (improves query performance) |
+| `--sortBy` | `-b` | | Attribute to sort results by (e.g. `created`, `userName`) |
+| `--sortOrder` | `-o` | | Sort direction: `ascending` or `descending` |
+| `--zone` | `-z` | | Identity zone subdomain in which to list users |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Background
+
+SCIM (System for Cross-Domain Identity Management) filters provide a limited query interface for searching users. Fetching group membership data requires SQL joins on the UAA side, so use `--attributes` to limit fields when querying large user sets.
+
+## Examples
+
+```bash
+# List all users
+uaa list-users
+
+# Find users with a gmail.com address
+uaa list-users --filter 'userName co "gmail.com"' --attributes id,emails
+
+# Find users from a specific identity provider
+uaa list-users --filter 'userName eq "bob@example.com" and origin eq "ldap"'
+
+# Find unverified users
+uaa list-users --filter 'verified eq false' --attributes id,userName,name,emails
+
+# Find users whose username starts with "z"
+uaa list-users --filter 'userName sw "z"'
+
+# See client approvals for a specific user
+uaa list-users --filter 'userName eq "bob@example.com"' --attributes approvals
+
+# See full details including group memberships
+uaa list-users --filter 'userName eq "bob@example.com"'
+```
+
+## See Also
+
+- [get-user](get-user.md)
+- [create-user](create-user.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/map-group.md b/docs/commands/map-group.md
new file mode 100644
index 0000000..68b833d
--- /dev/null
+++ b/docs/commands/map-group.md
@@ -0,0 +1,44 @@
+# map-group
+
+[← Command Reference](../commands.md)
+
+Map a UAA group (scope) to an external group defined within an external identity provider.
+
+## Usage
+
+```
+uaa map-group EXTERNAL_GROUPNAME GROUPNAME [flags]
+```
+
+Note the argument order: the external group name comes first, followed by the UAA group name.
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--origin` | | `ldap` | Identity provider origin for the external group mapping |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+# Map an LDAP group to a UAA scope (defaults to ldap origin)
+uaa map-group "cn=developers,ou=groups,dc=example,dc=com" cloud_controller.read
+
+# Map to a specific origin
+uaa map-group "developers" cloud_controller.read --origin okta
+```
+
+## See Also
+
+- [unmap-group](unmap-group.md)
+- [list-group-mappings](list-group-mappings.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/refresh-token.md b/docs/commands/refresh-token.md
new file mode 100644
index 0000000..3be73c4
--- /dev/null
+++ b/docs/commands/refresh-token.md
@@ -0,0 +1,49 @@
+# refresh-token
+
+[← Command Reference](../commands.md)
+
+Obtain a new access token using the `refresh_token` grant type and update the active context.
+
+## Usage
+
+```
+uaa refresh-token -s CLIENT_SECRET [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--client_secret` | `-s` | | Client secret |
+| `--format` | | `jwt` | Token format. Available values: `jwt`, `opaque` |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Background
+
+Refresh tokens are long-lived credentials issued alongside access tokens for `authorization_code` and `password` grant clients. Use this command to exchange a refresh token for a new, unexpired access token without requiring the user to re-authenticate.
+
+## Examples
+
+```bash
+uaa target https://uaa.example.com
+uaa get-password-token cf -s "" -u admin -p admin-secret
+uaa context                          # note the refresh_token
+uaa refresh-token -s ""
+uaa context                          # access_token should now be updated
+```
+
+## Troubleshooting
+
+**No refresh_token in active context:**
+- **Implicit grant:** Implicit clients cannot maintain secrets and are never issued refresh tokens.
+- **Authorization code / password grant:** The client must include `refresh_token` in its `authorized_grant_types`. Run `uaa get-client CLIENT_ID` to verify.
+- **Client credentials grant:** Refresh tokens are never issued for `client_credentials`. Re-authenticate using `get-client-credentials-token` at any time.
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/remove-member.md b/docs/commands/remove-member.md
new file mode 100644
index 0000000..01cc355
--- /dev/null
+++ b/docs/commands/remove-member.md
@@ -0,0 +1,32 @@
+# remove-member
+
+[← Command Reference](../commands.md)
+
+Remove a user from a group.
+
+## Usage
+
+```
+uaa remove-member GROUPNAME USERNAME
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa remove-member cloud_controller.read bob
+```
+
+## See Also
+
+- [add-member](add-member.md)
+- [get-group](get-group.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/set-client-secret.md b/docs/commands/set-client-secret.md
new file mode 100644
index 0000000..bf08a77
--- /dev/null
+++ b/docs/commands/set-client-secret.md
@@ -0,0 +1,39 @@
+# set-client-secret
+
+[← Command Reference](../commands.md)
+
+Update the secret for an OAuth client registration.
+
+## Usage
+
+```
+uaa set-client-secret CLIENT_ID -s CLIENT_SECRET [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--client_secret` | `-s` | | New client secret |
+| `--zone` | `-z` | | Identity zone subdomain where the client resides |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa set-client-secret my-app -s new-secret
+uaa set-client-secret my-app -s new-secret --zone my-zone
+```
+
+## See Also
+
+- [update-client](update-client.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/target.md b/docs/commands/target.md
new file mode 100644
index 0000000..979f0a8
--- /dev/null
+++ b/docs/commands/target.md
@@ -0,0 +1,45 @@
+# target
+
+[← Command Reference](../commands.md)
+
+Set the URL of the UAA you'd like to target, or display the current target.
+
+## Usage
+
+```
+uaa target UAA_URL [flags]
+uaa target
+```
+
+Aliases: `api`
+
+When called with no arguments, displays the currently targeted UAA URL and its status.
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--skip-ssl-validation` | `-k` | `false` | Disable SSL certificate validation for requests to this target |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+# Set a target
+uaa target https://uaa.example.com
+
+# Set a target, skipping SSL validation
+uaa target https://uaa.example.com --skip-ssl-validation
+
+# Display the current target
+uaa target
+```
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/unmap-group.md b/docs/commands/unmap-group.md
new file mode 100644
index 0000000..e290f89
--- /dev/null
+++ b/docs/commands/unmap-group.md
@@ -0,0 +1,44 @@
+# unmap-group
+
+[← Command Reference](../commands.md)
+
+Remove the mapping between an external group and a UAA group (scope).
+
+## Usage
+
+```
+uaa unmap-group EXTERNAL_GROUPNAME GROUPNAME [flags]
+```
+
+Note the argument order: the external group name comes first, followed by the UAA group name.
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--origin` | | `ldap` | Identity provider origin for the external group mapping |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+# Unmap an LDAP group from a UAA scope
+uaa unmap-group "cn=developers,ou=groups,dc=example,dc=com" cloud_controller.read
+
+# Unmap from a specific origin
+uaa unmap-group "developers" cloud_controller.read --origin okta
+```
+
+## See Also
+
+- [map-group](map-group.md)
+- [list-group-mappings](list-group-mappings.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/update-client.md b/docs/commands/update-client.md
new file mode 100644
index 0000000..7b94573
--- /dev/null
+++ b/docs/commands/update-client.md
@@ -0,0 +1,49 @@
+# update-client
+
+[← Command Reference](../commands.md)
+
+Update an existing OAuth client registration in the UAA.
+
+## Usage
+
+```
+uaa update-client CLIENT_ID [flags]
+```
+
+## Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--authorized_grant_types` | | | Comma-separated list of grant types allowed for this client |
+| `--scope` | | | Comma-separated scopes for `authorization_code`, `implicit`, or `password` grants |
+| `--authorities` | | | Comma-separated scopes for `client_credentials` grant |
+| `--redirect_uri` | | | Comma-separated callback URLs 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 |
+| `--zone` | `-z` | | Identity zone subdomain in which to update the client |
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Examples
+
+```bash
+uaa update-client my-app --scope openid,profile,email
+uaa update-client my-app --access_token_validity 3600
+```
+
+> To change a client's secret, use [`set-client-secret`](set-client-secret.md) — `update-client` does not support secret rotation.
+
+## See Also
+
+- [create-client](create-client.md)
+- [get-client](get-client.md)
+- [set-client-secret](set-client-secret.md)
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/userinfo.md b/docs/commands/userinfo.md
new file mode 100644
index 0000000..f53c1f9
--- /dev/null
+++ b/docs/commands/userinfo.md
@@ -0,0 +1,39 @@
+# userinfo
+
+[← Command Reference](../commands.md)
+
+Display claims about the currently authenticated user by calling the UAA's `/userinfo` endpoint.
+
+## Usage
+
+```
+uaa userinfo
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Print additional info on HTTP requests |
+
+## Background
+
+The `userinfo` command calls the UAA's `/userinfo` endpoint, which is implemented in accordance with the OpenID Connect Core 1.0 spec. It returns claims about the authenticated user using the access token saved in the current context.
+
+## Examples
+
+```bash
+uaa target https://uaa.example.com
+uaa get-password-token cf -s "" -u admin -p admin-secret
+uaa userinfo
+```
+
+## Troubleshooting
+
+**Got a token but `userinfo` returns an error:**
+- Verify your token is still valid by running another authenticated command.
+- Check that `openid` appears in the scopes listed by `uaa context`. The `/userinfo` endpoint requires the `openid` scope. Update your client registration to include `openid` in its `scope` list if needed.
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/commands/version.md b/docs/commands/version.md
new file mode 100644
index 0000000..0e1e47c
--- /dev/null
+++ b/docs/commands/version.md
@@ -0,0 +1,21 @@
+# version
+
+[← Command Reference](../commands.md)
+
+Print the CLI version.
+
+## Usage
+
+```
+uaa version
+```
+
+## Examples
+
+```bash
+uaa version
+```
+
+---
+
+[← Command Reference](../commands.md)
diff --git a/docs/migrating-from-uaac.md b/docs/migrating-from-uaac.md
new file mode 100644
index 0000000..7a53a6e
--- /dev/null
+++ b/docs/migrating-from-uaac.md
@@ -0,0 +1,149 @@
+# Migrating from uaac
+
+This guide helps users of the Ruby-based [cf-uaac](https://github.com/cloudfoundry/cf-uaac) (`uaac`) CLI transition to the Go-based `uaa` CLI.
+See the [UAA-CLI Command Reference](docs/commands.md) for the full list of `uaa` commands and their options.
+
+## Key Differences
+
+| | uaac (Ruby) | uaa (Go) |
+|---|---|---|
+| **Command style** | Hierarchical topic/verb: `uaac token client get` | Flat VERB-NOUN with hyphens: `uaa get-client-credentials-token` |
+| **Output format** | Human-readable text | Machine-parseable JSON by default |
+| **SSL validation** | `uaac target URL --skip-ssl-validation` | `uaa target URL --skip-ssl-validation` |
+| **Identity zones** | `-z` / `--zone` global flag | `-z` / `--zone` flag on most commands |
+| **Verbose/trace** | `-t` / `--trace` for verbose debug output | `-v` / `--verbose` on all commands |
+
+---
+
+## Command Reference
+
+### Targeting & Context
+
+| uaac | uaa | Notes |
+|------|-----|-------|
+| `uaac target [uaa_url]` | [`uaa target UAA_URL`](commands/target.md) | |
+| `uaac targets` | *(no equivalent)* | |
+| `uaac context [name]` | [`uaa context`](commands/context.md) | |
+| `uaac contexts` | `uaa contexts` | |
+| `uaac version` | [`uaa version`](commands/version.md) | |
+
+### System Information
+
+| uaac | uaa | Notes |
+|------|-----|-------|
+| `uaac info` | [`uaa info`](commands/info.md) | |
+| `uaac me` | [`uaa userinfo`](commands/userinfo.md) | |
+| `uaac signing key` | [`uaa get-token-key`](commands/get-token-key.md) | uaa-cli splits this into two commands |
+| `uaac signing key` | [`uaa get-token-keys`](commands/get-token-keys.md) | Returns all signing keys |
+| `uaac prompts` | *(no equivalent)* | Use `uaa curl /info` to inspect prompts |
+| `uaac password strength [password]` | *(no equivalent)* | Use `uaa curl /password/score -X POST -d 'password=...'` |
+
+### Tokens
+
+| uaac | uaa | Notes |
+|------|-----|-------|
+| `uaac token client get [id]` | [`uaa get-client-credentials-token CLIENT_ID -s SECRET`](commands/get-client-credentials-token.md) | |
+| `uaac token owner get [client] [user]` | [`uaa get-password-token CLIENT_ID -s SECRET -u USER -p PASS`](commands/get-password-token.md) | |
+| `uaac token authcode get` | [`uaa get-authcode-token CLIENT_ID -s SECRET --port PORT`](commands/get-authcode-token.md) | |
+| `uaac token implicit get` | [`uaa get-implicit-token CLIENT_ID --port PORT`](commands/get-implicit-token.md) | |
+| `uaac token refresh [refreshtoken]` | [`uaa refresh-token -s SECRET`](commands/refresh-token.md) | |
+| `uaac token get [credentials...]` | *(no equivalent)* | Use `uaa get-password-token` for password grant |
+| `uaac token sso get [client]` | *(no equivalent)* | Passcode/SSO grant not yet supported |
+| `uaac token decode [token] [tokentype]` | *(no equivalent)* | Decode manually: `uaa context --access_token \| cut -d. -f2 \| base64 -d` |
+| `uaac token delete [contexts...]` | *(no equivalent)* | Delete `~/.uaa/config.json` to clear all contexts |
+
+### Users
+
+| uaac | uaa | Notes |
+|------|-----|-------|
+| `uaac user add [name]` | [`uaa create-user USERNAME --givenName G --familyName F -p PASS --email EMAIL`](commands/create-user.md) | |
+| `uaac user get [name]` | [`uaa get-user USERNAME`](commands/get-user.md) | |
+| `uaac users [filter]` | [`uaa list-users --filter '...'`](commands/list-users.md) | |
+| `uaac user delete [name]` | [`uaa delete-user USERNAME`](commands/delete-user.md) | |
+| `uaac user activate [name]` | [`uaa activate-user USERNAME`](commands/activate-user.md) | |
+| `uaac user deactivate [name]` | [`uaa deactivate-user USERNAME`](commands/deactivate-user.md) | |
+| `uaac user update [name]` | *(no equivalent)* | Use `uaa curl /Users/USER_ID -X PUT -d '{...}'` |
+| `uaac user ids [username\|id...]` | *(no equivalent)* | Use `uaa get-user USERNAME` for individual lookups |
+| `uaac user unlock [name]` | *(no equivalent)* | Use `uaa curl /Users/USER_ID/status -X PATCH -d '{"locked":false}'` |
+| `uaac password set [name]` | *(no equivalent)* | Use `uaa curl /Users/USER_ID/password -X PUT -d '{"password":"NEW"}'` |
+| `uaac password change` | *(no equivalent)* | Use `uaa curl /Users/USER_ID/password -X PUT -d '{"oldPassword":"OLD","password":"NEW"}'` |
+
+### Clients
+
+| uaac | uaa | Notes |
+|------|-----|-------|
+| `uaac client add [id]` | [`uaa create-client CLIENT_ID -s SECRET ...`](commands/create-client.md) | uaac supports `--interactive` / `-i` to prompt for each field; uaa-cli does not |
+| `uaac client get [id]` | [`uaa get-client CLIENT_ID`](commands/get-client.md) | |
+| `uaac clients [filter]` | [`uaa list-clients`](commands/list-clients.md) | |
+| `uaac client update [id]` | [`uaa update-client CLIENT_ID ...`](commands/update-client.md) | uaac supports `--interactive` / `-i`; uaa-cli does not |
+| `uaac client delete [id]` | [`uaa delete-client CLIENT_ID`](commands/delete-client.md) | |
+| `uaac secret set [id]` | [`uaa set-client-secret CLIENT_ID -s SECRET`](commands/set-client-secret.md) | |
+| `uaac secret change` | *(no equivalent)* | Use `uaa curl /oauth/clients/CLIENT_ID/secret -X PUT -d '{"oldSecret":"OLD","secret":"NEW"}'` |
+| `uaac client jwt add [id]` | *(no equivalent)* | Use `uaa curl /oauth/clients/CLIENT_ID/clientjwt -X PUT -d '{...}'` |
+| `uaac client jwt update [id]` | *(no equivalent)* | Use `uaa curl /oauth/clients/CLIENT_ID/clientjwt -X PUT -d '{...}'` |
+| `uaac client jwt delete [id]` | *(no equivalent)* | Use `uaa curl /oauth/clients/CLIENT_ID/clientjwt -X DELETE` |
+
+### Groups
+
+| uaac | uaa | Notes |
+|------|-----|-------|
+| `uaac group add [name]` | [`uaa create-group GROUPNAME`](commands/create-group.md) | |
+| `uaac group get [name]` | [`uaa get-group GROUPNAME`](commands/get-group.md) | |
+| `uaac groups [filter]` | [`uaa list-groups --filter '...'`](commands/list-groups.md) | |
+| `uaac group delete [name]` | *(no equivalent)* | Use `uaa curl /Groups/GROUP_ID -X DELETE` |
+| `uaac member add [name] [users...]` | [`uaa add-member GROUPNAME USERNAME`](commands/add-member.md) | uaa-cli adds one user at a time |
+| `uaac member delete [name] [users...]` | [`uaa remove-member GROUPNAME USERNAME`](commands/remove-member.md) | uaa-cli removes one user at a time |
+| `uaac group map [external_group]` | [`uaa map-group EXTERNAL_GROUPNAME GROUPNAME`](commands/map-group.md) | See argument order note below |
+| `uaac group unmap [group_name] [external_group]` | [`uaa unmap-group EXTERNAL_GROUPNAME GROUPNAME`](commands/unmap-group.md) | See argument order note below |
+| `uaac group mappings` | [`uaa list-group-mappings`](commands/list-group-mappings.md) | |
+
+### Miscellaneous
+
+| uaac | uaa | Notes |
+|------|-----|-------|
+| `uaac curl [path]` | [`uaa curl PATH`](commands/curl.md) | |
+
+---
+
+## Notable Argument Differences
+
+### Group mapping argument order
+
+The `map-group` and `unmap-group` commands take arguments in a different order than uaac:
+
+```bash
+# uaac: UAA group name first (via --name flag), external group as positional arg
+uaac group map --name cloud_controller.read "cn=devs,ou=groups,dc=example,dc=com"
+
+# uaa: external group name first, UAA group name second
+uaa map-group "cn=devs,ou=groups,dc=example,dc=com" cloud_controller.read
+```
+
+### `member add` / `member delete` — one user at a time
+
+uaac accepts multiple usernames in a single call; uaa-cli accepts one at a time:
+
+```bash
+# uaac: add multiple users at once
+uaac member add my-group alice bob carol
+
+# uaa: one user per call
+uaa add-member my-group alice
+uaa add-member my-group bob
+uaa add-member my-group carol
+```
+
+---
+
+## Using `uaa curl` as a Fallback
+
+For uaac commands that have no direct equivalent, `uaa curl` provides authenticated access to any UAA API endpoint. First obtain a token, then use `curl` with the active context's credentials:
+
+```bash
+uaa target https://uaa.example.com
+uaa get-client-credentials-token admin -s admin-secret
+
+# Example: delete a group by ID
+GROUP_ID=$(uaa get-group my-group | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+uaa curl /Groups/$GROUP_ID -X DELETE
+```
diff --git a/help/root.go b/help/root.go
index ffa2fb8..8249387 100644
--- a/help/root.go
+++ b/help/root.go
@@ -6,7 +6,6 @@ func Root(version string) string {
 	return fmt.Sprintf(`UAA Command Line Interface, version %v
 
 Feedback:
-  Email cf-identity-eng@pivotal.io with your thoughts on the experience of using this
-  tool. Bugs or other issues can be filed on github.com/cloudfoundry-incubator/uaa-cli
+  Bugs or other issues can be filed on github.com/cloudfoundry/uaa-cli
   `, version)
 }