docs: add section on how to retrieve user list (#17798)

previews
- [admin/users](https://coder.com/docs/@export-coder-users/admin/users)
-
[reference/cli/users](https://coder.com/docs/@export-coder-users/reference/cli/users)

followup to slack thread:

> Tim
> what's the best way for customers to export a list of Coder users?
>
> @ericpaulsen
> the `/api/v2/users` API route returns all users in the deployment
(along with other information - email, status, username, etc.). from
<https://coder.com/docs/reference/api/users#get-users>


- adds an easy-to-find section to the admin/users doc
- updates the cli commands with short descriptions

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: M Atif Ali <atif@coder.com>

cli/testdata/coder_users_--help.golden

@@ -10,10 +10,10 @@ USAGE:
 SUBCOMMANDS:
     activate      Update a user's status to 'active'. Active users can fully
                   interact with the platform
-    create        
+    create        Create a new user.
     delete        Delete a user by username or user_id.
     edit-roles    Edit a user's roles by username or id
-    list          
+    list          Prints the list of users.
     show          Show a single user. Use 'me' to indicate the currently
                   authenticated user.
     suspend       Update a user's status to 'suspended'. A suspended user cannot

cli/testdata/coder_users_create_--help.golden

@@ -3,6 +3,8 @@ coder v0.0.0-devel
 USAGE:
   coder users create [flags]
 
+  Create a new user.
+
 OPTIONS:
   -O, --org string, $CODER_ORGANIZATION
           Select which organization (uuid or name) to use.

cli/testdata/coder_users_list_--help.golden

@@ -3,6 +3,8 @@ coder v0.0.0-devel
 USAGE:
   coder users list [flags]
 
+  Prints the list of users.
+
   Aliases: ls
 
 OPTIONS:

cli/usercreate.go

@@ -29,6 +29,7 @@ func (r *RootCmd) userCreate() *serpent.Command {
 	client := new(codersdk.Client)
 	cmd := &serpent.Command{
 		Use:   "create",
+		Short: "Create a new user.",
 		Middleware: serpent.Chain(
 			serpent.RequireNArgs(0),
 			r.InitClient(client),

cli/userlist.go

@@ -23,6 +23,7 @@ func (r *RootCmd) userList() *serpent.Command {
 
 	cmd := &serpent.Command{
 		Use:     "list",
+		Short:   "Prints the list of users.",
 		Aliases: []string{"ls"},
 		Middleware: serpent.Chain(
 			serpent.RequireNArgs(0),

docs/admin/users/index.md

@@ -206,3 +206,42 @@ The following filters are supported:
 - `created_before` and `created_after` - The time a user was created. Uses the
   RFC3339Nano format.
 - `login_type` - Represents the login type of the user. Refer to the [LoginType documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#LoginType) for a list of supported values
+
+## Retrieve your list of Coder users
+
+<div class="tabs">
+
+You can use the Coder CLI or API to retrieve your list of users.
+
+### CLI
+
+Use `users list` to export the list of users to a CSV file:
+
+```shell
+coder users list > users.csv
+```
+
+Visit the [users list](../../reference/cli/users_list.md) documentation for more options.
+
+### API
+
+Use [get users](../../reference/api/users.md#get-users):
+
+```shell
+curl -X GET http://coder-server:8080/api/v2/users \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+To export the results to a CSV file, you can use [`jq`](https://jqlang.org/) to process the JSON response:
+
+```shell
+curl -X GET http://coder-server:8080/api/v2/users \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY' | \
+  jq -r '.users | (map(keys) | add | unique) as $cols | $cols, (.[] | [.[$cols[]]] | @csv)' > users.csv
+```
+
+Visit the [get users](../../reference/api/users.md#get-users) documentation for more options.
+
+</div>

docs/manifest.json

@@ -1625,6 +1625,7 @@
 						},
 						{
 							"title": "users create",
+							"description": "Create a new user.",
 							"path": "reference/cli/users_create.md"
 						},
 						{
@@ -1639,6 +1640,7 @@
 						},
 						{
 							"title": "users list",
+							"description": "Prints the list of users.",
 							"path": "reference/cli/users_list.md"
 						},
 						{

docs/reference/cli/users.md

@@ -17,8 +17,8 @@ coder users [subcommand]
 
 | Name                                             | Purpose                                                                               |
 |--------------------------------------------------|---------------------------------------------------------------------------------------|
-| [<code>create</code>](./users_create.md)         |                                                                                       |
+| [<code>create</code>](./users_create.md)         | Create a new user.                                                                    |
-| [<code>list</code>](./users_list.md)             |                                                                                       |
+| [<code>list</code>](./users_list.md)             | Prints the list of users.                                                             |
 | [<code>show</code>](./users_show.md)             | Show a single user. Use 'me' to indicate the currently authenticated user.            |
 | [<code>delete</code>](./users_delete.md)         | Delete a user by username or user_id.                                                 |
 | [<code>edit-roles</code>](./users_edit-roles.md) | Edit a user's roles by username or id                                                 |

docs/reference/cli/users_create.md

@@ -1,6 +1,8 @@
 <!-- DO NOT EDIT | GENERATED CONTENT -->
 # users create
 
+Create a new user.
+
 ## Usage
 
 ```console

docs/reference/cli/users_list.md

@@ -1,6 +1,8 @@
 <!-- DO NOT EDIT | GENERATED CONTENT -->
 # users list
 
+Prints the list of users.
+
 Aliases:
 
 * ls