diff --git a/cli/testdata/coder_users_--help.golden b/cli/testdata/coder_users_--help.golden
index 585588cbc6e18..949dc97c3b8d2 100644
--- 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
index 5f57485b52f3c..04f976ab6843c 100644
--- 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
index 563ad76e1dc72..22c1fe172faf5 100644
--- 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
index f73a3165ee908..643e3554650e5 100644
--- 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
index 48f27f83119a4..e24281ad76d68 100644
--- 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
index af26f4bb62a2b..b7d98b919734c 100644
--- 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
+
+
+
+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.
+
+
diff --git a/docs/manifest.json b/docs/manifest.json
index 4519767b071dd..c7d558b87bfd7 100644
--- 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
index d942699d6ee31..5f05375e8b13e 100644
--- a/docs/reference/cli/users.md
+++ b/docs/reference/cli/users.md
@@ -17,8 +17,8 @@ coder users [subcommand]
| Name | Purpose |
|--------------------------------------------------|---------------------------------------------------------------------------------------|
-| [create](./users_create.md) | |
-| [list](./users_list.md) | |
+| [create](./users_create.md) | Create a new user. |
+| [list](./users_list.md) | Prints the list of users. |
| [show](./users_show.md) | Show a single user. Use 'me' to indicate the currently authenticated user. |
| [delete](./users_delete.md) | Delete a user by username or user_id. |
| [edit-roles](./users_edit-roles.md) | Edit a user's roles by username or id |
diff --git a/docs/reference/cli/users_create.md b/docs/reference/cli/users_create.md
index 61768ebfdbbf8..646eb55ffb5ba 100644
--- a/docs/reference/cli/users_create.md
+++ b/docs/reference/cli/users_create.md
@@ -1,6 +1,8 @@
# users create
+Create a new user.
+
## Usage
```console
diff --git a/docs/reference/cli/users_list.md b/docs/reference/cli/users_list.md
index 9293ff13c923c..93122e7741072 100644
--- a/docs/reference/cli/users_list.md
+++ b/docs/reference/cli/users_list.md
@@ -1,6 +1,8 @@
# users list
+Prints the list of users.
+
Aliases:
* ls