From eda3705ef18f8746fd4ecb31a44e44e7dfc8a97e Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Tue, 13 May 2025 16:17:24 +0000 Subject: [PATCH 1/5] add retrieve user list --- docs/admin/users/index.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/admin/users/index.md b/docs/admin/users/index.md index af26f4bb62a2b..695cc7e9a29e8 100644 --- a/docs/admin/users/index.md +++ b/docs/admin/users/index.md @@ -206,3 +206,32 @@ 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 + +## Use the Coder API to retrieve a list of users + +Use the [Coder API](../../reference/api/users.md#get-users) to retrieve a full list of users on your Coder deployment: + +```shell +curl -X GET http://coder-server:8080/api/v2/users \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +You can also filter your results based on the `organization_id` with: + +```shell +curl -X GET 'http://coder-server:8080/api/v2/users?organization_id=Example-Org' \ + -H 'Accept: application/json' \ + -H 'Coder-Session-Token: API_KEY' +``` + +### Export a list of users to a CSV file + +You can use [jq](https://jqlang.org/) to process the JSON response and export the results to a CSV file: + +```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 +``` From ad8edd09e6a408d65b273c0a88a94823387e09a2 Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Tue, 13 May 2025 19:10:49 +0000 Subject: [PATCH 2/5] cli+api steps --- docs/admin/users/index.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/docs/admin/users/index.md b/docs/admin/users/index.md index 695cc7e9a29e8..21887dc21c4a1 100644 --- a/docs/admin/users/index.md +++ b/docs/admin/users/index.md @@ -207,31 +207,41 @@ The following filters are supported: 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 -## Use the Coder API to retrieve a list of users +## Retrieve your list of Coder users -Use the [Coder API](../../reference/api/users.md#get-users) to retrieve a full list of users on your Coder deployment: +
+ +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 -curl -X GET http://coder-server:8080/api/v2/users \ - -H 'Accept: application/json' \ - -H 'Coder-Session-Token: API_KEY' +coder users list > users.csv ``` -You can also filter your results based on the `organization_id` with: +Visit the [users list](../../reference/cli/users_list.md) documentation for more options. -```shell -curl -X GET 'http://coder-server:8080/api/v2/users?organization_id=Example-Org' \ +### API + +Use [get users](../../reference/api/users.md#get-users): + +```bash +curl -X GET http://coder-server:8080/api/v2/users \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` -### Export a list of users to a CSV file - -You can use [jq](https://jqlang.org/) to process the JSON response and export the results to a CSV file: +To export the results to a CSV file, you can use [jq](https://jqlang.org/) to process the JSON response: -```shell +```bash 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. + +
From 1eeae5ec9f54354fc60a4735b42cc86b30f571b7 Mon Sep 17 00:00:00 2001 From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Date: Tue, 13 May 2025 19:20:43 +0000 Subject: [PATCH 3/5] add short descriptions to users cli --- cli/testdata/coder_users_--help.golden | 4 ++-- cli/testdata/coder_users_create_--help.golden | 2 ++ cli/testdata/coder_users_list_--help.golden | 2 ++ cli/usercreate.go | 3 ++- cli/userlist.go | 1 + docs/manifest.json | 2 ++ docs/reference/cli/users.md | 4 ++-- docs/reference/cli/users_create.md | 2 ++ docs/reference/cli/users_list.md | 2 ++ 9 files changed, 17 insertions(+), 5 deletions(-) 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/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 From 425ca0ecd4bcd08925de538be57870a384eee314 Mon Sep 17 00:00:00 2001 From: Edward Angert Date: Tue, 13 May 2025 16:33:50 -0400 Subject: [PATCH 4/5] Update docs/admin/users/index.md Co-authored-by: M Atif Ali --- docs/admin/users/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/users/index.md b/docs/admin/users/index.md index 21887dc21c4a1..aa8fd5ef90996 100644 --- a/docs/admin/users/index.md +++ b/docs/admin/users/index.md @@ -235,7 +235,7 @@ curl -X GET http://coder-server:8080/api/v2/users \ To export the results to a CSV file, you can use [jq](https://jqlang.org/) to process the JSON response: -```bash +```shell curl -X GET http://coder-server:8080/api/v2/users \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' | \ From e485e6cae2ee865bbbeb49fc5ea8938e659d23dd Mon Sep 17 00:00:00 2001 From: Edward Angert Date: Tue, 13 May 2025 16:34:17 -0400 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: M Atif Ali --- docs/admin/users/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin/users/index.md b/docs/admin/users/index.md index aa8fd5ef90996..b7d98b919734c 100644 --- a/docs/admin/users/index.md +++ b/docs/admin/users/index.md @@ -227,13 +227,13 @@ Visit the [users list](../../reference/cli/users_list.md) documentation for more Use [get users](../../reference/api/users.md#get-users): -```bash +```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: +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 \