docs: add section on how to retrieve user list #17798
Conversation
docs/admin/users/index.md
Outdated
|
|
||
| ## 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 | ||
| ``` |
There was a problem hiding this comment.
coder users list > users.txtThis does the same thing
There was a problem hiding this comment.
We already have a documentation page for that. https://coder.com/docs/reference/cli/users_list
There was a problem hiding this comment.
I would rather update CLI command to add description
Line 25 in 64807e1
Short: "Prints the users list.", field
There was a problem hiding this comment.
An example use case is here:
Line 42 in 64807e1
There was a problem hiding this comment.
I'm happy to switch it to the Coder CLI command and can also PR to the CLI source docs, but I do want to keep the heading in this doc, where I think it's more likely to be found and we can explain the examples better
++ to including a better description of list in both:
There was a problem hiding this comment.
I think that with a better-described CLI command, our admin documentation could be pretty simple. We can demonstrate a single use case for exporting list to a CSV file. There is no need to cover all use cases in admin docs, as they are already covered in CLI docs.
WDYT?
There was a problem hiding this comment.
I'm torn - I agree, I don't think we need to catch every possibility from the same page.
but generally, I think if someone's looking for it, we should make it easy to find, and I think the CLI is almost that if someone already knows how they're trying to do it ("I want to use the CLI to get a list of users, what command do I use"), but in some cases, I think we want to catch people from web/docs search who just know they want to "list users" and don't know where they'd do that
it'd be really nice to check back on these pages in a few months to see if they're getting more traffic 🤔
|
looks great, thanks @EdwardAngert for filling this gap, and @matifali for the feedback. |
Co-authored-by: M Atif Ali <atif@coder.com>
Co-authored-by: M Atif Ali <atif@coder.com>
previews
followup to slack thread: