feat: add organizations list command to coder cli (#21960)

follows on from #21940.

The API endpoints existed for this already, so this PR just adds CLI functionality which uses those API endpoints.

Generated with the help of Mux

cli/organization.go

@@ -23,6 +23,7 @@ func (r *RootCmd) organizations() *serpent.Command {
 		},
 		Children: []*serpent.Command{
 			r.showOrganization(orgContext),
+			r.listOrganizations(),
 			r.createOrganization(),
 			r.deleteOrganization(orgContext),
 			r.organizationMembers(orgContext),

cli/organization_test.go

@@ -1,6 +1,7 @@
 package cli_test
 
 import (
+	"bytes"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -58,6 +59,48 @@ func TestCurrentOrganization(t *testing.T) {
 	})
 }
 
+func TestOrganizationList(t *testing.T) {
+	t.Parallel()
+
+	t.Run("OK", func(t *testing.T) {
+		t.Parallel()
+
+		orgID := uuid.New()
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			switch {
+			case r.Method == http.MethodGet && r.URL.Path == "/api/v2/organizations":
+				_ = json.NewEncoder(w).Encode([]codersdk.Organization{
+					{
+						MinimalOrganization: codersdk.MinimalOrganization{
+							ID:          orgID,
+							Name:        "my-org",
+							DisplayName: "My Org",
+						},
+						CreatedAt: time.Now(),
+						UpdatedAt: time.Now(),
+					},
+				})
+			default:
+				t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+				w.WriteHeader(http.StatusNotFound)
+			}
+		}))
+		defer server.Close()
+
+		client := codersdk.New(must(url.Parse(server.URL)))
+		inv, root := clitest.New(t, "organizations", "list")
+		clitest.SetupConfig(t, client, root)
+
+		buf := new(bytes.Buffer)
+		inv.Stdout = buf
+
+		require.NoError(t, inv.Run())
+		require.Contains(t, buf.String(), "my-org")
+		require.Contains(t, buf.String(), "My Org")
+		require.Contains(t, buf.String(), orgID.String())
+	})
+}
+
 func TestOrganizationDelete(t *testing.T) {
 	t.Parallel()
 

cli/organizationlist.go

@@ -0,0 +1,53 @@
+package cli
+
+import (
+	"fmt"
+
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/serpent"
+)
+
+func (r *RootCmd) listOrganizations() *serpent.Command {
+	formatter := cliui.NewOutputFormatter(
+		cliui.TableFormat([]codersdk.Organization{}, []string{"name", "display name", "id", "default"}),
+		cliui.JSONFormat(),
+	)
+
+	cmd := &serpent.Command{
+		Use:     "list",
+		Short:   "List all organizations",
+		Long:    "List all organizations. Requires a role which grants ResourceOrganization: read.",
+		Aliases: []string{"ls"},
+		Middleware: serpent.Chain(
+			serpent.RequireNArgs(0),
+		),
+		Handler: func(inv *serpent.Invocation) error {
+			client, err := r.InitClient(inv)
+			if err != nil {
+				return err
+			}
+
+			organizations, err := client.Organizations(inv.Context())
+			if err != nil {
+				return err
+			}
+
+			out, err := formatter.Format(inv.Context(), organizations)
+			if err != nil {
+				return err
+			}
+
+			if out == "" {
+				cliui.Infof(inv.Stderr, "No organizations found.")
+				return nil
+			}
+
+			_, err = fmt.Fprintln(inv.Stdout, out)
+			return err
+		},
+	}
+
+	formatter.AttachOptions(&cmd.Options)
+	return cmd
+}

cli/testdata/coder_organizations_--help.golden

@@ -10,6 +10,7 @@ USAGE:
 SUBCOMMANDS:
     create      Create a new organization.
     delete      Delete an organization
+    list        List all organizations
     members     Manage organization members
     roles       Manage organization roles.
     settings    Manage organization settings.

cli/testdata/coder_organizations_list_--help.golden

@@ -0,0 +1,21 @@
+coder v0.0.0-devel
+
+USAGE:
+  coder organizations list [flags]
+
+  List all organizations
+
+  Aliases: ls
+
+  List all organizations. Requires a role which grants ResourceOrganization:
+  read.
+
+OPTIONS:
+  -c, --column [id|name|display name|icon|description|created at|updated at|default] (default: name,display name,id,default)
+          Columns to display in table output.
+
+  -o, --output table|json (default: table)
+          Output format.
+
+———
+Run `coder --help` for a list of global options.

docs/manifest.json

@@ -1637,6 +1637,11 @@
 							"description": "Delete an organization",
 							"path": "reference/cli/organizations_delete.md"
 						},
+						{
+							"title": "organizations list",
+							"description": "List all organizations",
+							"path": "reference/cli/organizations_list.md"
+						},
 						{
 							"title": "organizations members",
 							"description": "Manage organization members",

docs/reference/cli/organizations.md

@@ -20,6 +20,7 @@ coder organizations [flags] [subcommand]
 | Name                                                 | Purpose                                                                                                                                                        |
 |------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [<code>show</code>](./organizations_show.md)         | Show the organization. Using "selected" will show the selected organization from the "--org" flag. Using "me" will show all organizations you are a member of. |
+| [<code>list</code>](./organizations_list.md)         | List all organizations                                                                                                                                         |
 | [<code>create</code>](./organizations_create.md)     | Create a new organization.                                                                                                                                     |
 | [<code>delete</code>](./organizations_delete.md)     | Delete an organization                                                                                                                                         |
 | [<code>members</code>](./organizations_members.md)   | Manage organization members                                                                                                                                    |

docs/reference/cli/organizations_list.md

@@ -0,0 +1,40 @@
+<!-- DO NOT EDIT | GENERATED CONTENT -->
+# organizations list
+
+List all organizations
+
+Aliases:
+
+* ls
+
+## Usage
+
+```console
+coder organizations list [flags]
+```
+
+## Description
+
+```console
+List all organizations. Requires a role which grants ResourceOrganization: read.
+```
+
+## Options
+
+### -c, --column
+
+|         |                                                                                           |
+|---------|-------------------------------------------------------------------------------------------|
+| Type    | <code>[id\|name\|display name\|icon\|description\|created at\|updated at\|default]</code> |
+| Default | <code>name,display name,id,default</code>                                                 |
+
+Columns to display in table output.
+
+### -o, --output
+
+|         |                          |
+|---------|--------------------------|
+| Type    | <code>table\|json</code> |
+| Default | <code>table</code>       |
+
+Output format.