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

EdwardAngert · matifali · web-flow · commit f9817af11f09 · 2025-05-13T20:48:16.000Z
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>
diff --git a/cli/testdata/coder_users_--help.golden b/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
diff --git a/cli/testdata/coder_users_create_--help.golden b/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.
diff --git a/cli/testdata/coder_users_list_--help.golden b/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:
diff --git a/cli/usercreate.go b/cli/usercreate.go
@@ -28,7 +28,8 @@ func (r *RootCmd) userCreate() *serpent.Command {
 	)
 	client := new(codersdk.Client)
 	cmd := &serpent.Command{
-		Use: "create",
+		Use:   "create",
+		Short: "Create a new user.",
 		Middleware: serpent.Chain(
 			serpent.RequireNArgs(0),
 			r.InitClient(client),
diff --git a/cli/userlist.go b/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),
diff --git a/docs/admin/users/index.md b/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>
diff --git a/docs/manifest.json b/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"
 						},
 						{
diff --git a/docs/reference/cli/users.md b/docs/reference/cli/users.md
diff --git a/docs/reference/cli/users_create.md b/docs/reference/cli/users_create.md
diff --git a/docs/reference/cli/users_list.md b/docs/reference/cli/users_list.md

Original file line number	Diff line number	Diff line change
`@@ -1625,6 +1625,7 @@`
`1625`	`1625`	`},`
`1626`	`1626`	`{`
`1627`	`1627`	`"title": "users create",`
	`1628`	`+ "description": "Create a new user.",`
`1628`	`1629`	`"path": "reference/cli/users_create.md"`
`1629`	`1630`	`},`
`1630`	`1631`	`{`
`@@ -1639,6 +1640,7 @@`
`1639`	`1640`	`},`
`1640`	`1641`	`{`
`1641`	`1642`	`"title": "users list",`
	`1643`	`+ "description": "Prints the list of users.",`
`1642`	`1644`	`"path": "reference/cli/users_list.md"`
`1643`	`1645`	`},`
`1644`	`1646`	`{`