add list command for external workspaces

coder · kacpersaw · Jul 23, 2025 · Jul 24, 2025 · Jul 28, 2025 · Jul 29, 2025
commit fd2458bcc25448d42a77be31f0cc3c856c85289b
diff --git a/cli/external_workspaces.go b/cli/external_workspaces.go
@@ -33,6 +33,7 @@ func (r *RootCmd) externalWorkspaces() *serpent.Command {
 		Children: []*serpent.Command{
 			r.externalWorkspaceCreate(),
 			r.externalWorkspaceAgentInstructions(),
+			r.externalWorkspaceList(),
 		},
 	}
 
@@ -138,9 +139,9 @@ func (r *RootCmd) externalWorkspaceAgentInstructions() *serpent.Command {
 			}
 
 			var output strings.Builder
-			output.WriteString(fmt.Sprintf("Please run the following commands to attach agent %s:\n", cliui.Keyword(agent.AgentName)))
-			output.WriteString(fmt.Sprintf("%s\n", pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("export CODER_AGENT_TOKEN=%s", agent.AuthToken))))
-			output.WriteString(pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("curl -fsSL %s | sh", agent.InitScript)))
+			_, _ = output.WriteString(fmt.Sprintf("Please run the following commands to attach agent %s:\n", cliui.Keyword(agent.AgentName)))
+			_, _ = output.WriteString(fmt.Sprintf("%s\n", pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("export CODER_AGENT_TOKEN=%s", agent.AuthToken))))
+			_, _ = output.WriteString(pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("curl -fsSL %s | sh", agent.InitScript)))
 
 			return output.String(), nil
 		}),
@@ -204,6 +205,71 @@ func (r *RootCmd) externalWorkspaceAgentInstructions() *serpent.Command {
 	return cmd
 }
 
+func (r *RootCmd) externalWorkspaceList() *serpent.Command {
+	var (
+		filter    cliui.WorkspaceFilter
+		formatter = cliui.NewOutputFormatter(
+			cliui.TableFormat(
+				[]workspaceListRow{},
+				[]string{
+					"workspace",
+					"template",
+					"status",
+					"healthy",
+					"last built",
+					"current version",
+					"outdated",
+				},
+			),
+			cliui.JSONFormat(),
+		)
+	)
+	client := new(codersdk.Client)
+	cmd := &serpent.Command{
+		Annotations: workspaceCommand,
+		Use:         "list",
+		Short:       "List external workspaces",
+		Aliases:     []string{"ls"},
+		Middleware: serpent.Chain(
+			serpent.RequireNArgs(0),
+			r.InitClient(client),
+		),
+		Handler: func(inv *serpent.Invocation) error {
+			baseFilter := filter.Filter()
+
+			if baseFilter.FilterQuery == "" {
+				baseFilter.FilterQuery = "has-external-agent:true"
+			} else {
+				baseFilter.FilterQuery += " has-external-agent:true"
+			}
+
+			res, err := queryConvertWorkspaces(inv.Context(), client, baseFilter, workspaceListRowFromWorkspace)
+			if err != nil {
+				return err
+			}
+
+			if len(res) == 0 && formatter.FormatID() != cliui.JSONFormat().ID() {
+				pretty.Fprintf(inv.Stderr, cliui.DefaultStyles.Prompt, "No workspaces found! Create one:\n")
+				_, _ = fmt.Fprintln(inv.Stderr)
+				_, _ = fmt.Fprintln(inv.Stderr, "  "+pretty.Sprint(cliui.DefaultStyles.Code, "coder external-workspaces create <name>"))
+				_, _ = fmt.Fprintln(inv.Stderr)
+				return nil
+			}
+
+			out, err := formatter.Format(inv.Context(), res)
+			if err != nil {
+				return err
+			}
+
+			_, err = fmt.Fprintln(inv.Stdout, out)
+			return err
+		},
+	}
+	filter.AttachOptions(&cmd.Options)
+	formatter.AttachOptions(&cmd.Options)
+	return cmd
+}
+
 // fetchExternalAgents fetches the external agents for a workspace.
 func fetchExternalAgents(inv *serpent.Invocation, client *codersdk.Client, workspace codersdk.Workspace, resources []codersdk.WorkspaceResource) ([]externalAgent, error) {
 	if len(resources) == 0 {
@@ -241,18 +307,18 @@ func fetchExternalAgents(inv *serpent.Invocation, client *codersdk.Client, works
 
 // printExternalAgents prints the instructions for an external agent.
 func printExternalAgents(inv *serpent.Invocation, workspaceName string, externalAgents []externalAgent) error {
-	fmt.Fprintf(inv.Stdout, "\nPlease run the following commands to attach external agent to the workspace %s:\n\n", cliui.Keyword(workspaceName))
+	_, _ = fmt.Fprintf(inv.Stdout, "\nPlease run the following commands to attach external agent to the workspace %s:\n\n", cliui.Keyword(workspaceName))
 
 	for i, agent := range externalAgents {
 		if len(externalAgents) > 1 {
-			fmt.Fprintf(inv.Stdout, "For agent %s:\n", cliui.Keyword(agent.AgentName))
+			_, _ = fmt.Fprintf(inv.Stdout, "For agent %s:\n", cliui.Keyword(agent.AgentName))
 		}
 
-		fmt.Fprintf(inv.Stdout, "%s\n", pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("export CODER_AGENT_TOKEN=%s", agent.AuthToken)))
-		fmt.Fprintf(inv.Stdout, "%s\n", pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("curl -fsSL %s | sh", agent.InitScript)))
+		_, _ = fmt.Fprintf(inv.Stdout, "%s\n", pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("export CODER_AGENT_TOKEN=%s", agent.AuthToken)))
+		_, _ = fmt.Fprintf(inv.Stdout, "%s\n", pretty.Sprint(cliui.DefaultStyles.Code, fmt.Sprintf("curl -fsSL %s | sh", agent.InitScript)))
 
 		if i < len(externalAgents)-1 {
-			fmt.Fprintf(inv.Stdout, "\n")
+			_, _ = fmt.Fprintf(inv.Stdout, "\n")
 		}
 	}
 

diff --git a/cli/testdata/coder_external-workspaces_--help.golden b/cli/testdata/coder_external-workspaces_--help.golden
@@ -8,6 +8,7 @@ USAGE:
 SUBCOMMANDS:
     agent-instructions    Get the instructions for an external agent
     create                Create a new external workspace
+    list                  List external workspaces
 
 OPTIONS:
   -O, --org string, $CODER_ORGANIZATION

diff --git a/cli/testdata/coder_external-workspaces_list_--help.golden b/cli/testdata/coder_external-workspaces_list_--help.golden
@@ -0,0 +1,24 @@
+coder v0.0.0-devel
+
+USAGE:
+  coder external-workspaces list [flags]
+
+  List external workspaces
+
+  Aliases: ls
+
+OPTIONS:
+  -a, --all bool
+          Specifies whether all workspaces will be listed or not.
+
+  -c, --column [favorite|workspace|organization id|organization name|template|status|healthy|last built|current version|outdated|starts at|starts next|stops after|stops next|daily cost] (default: workspace,template,status,healthy,last built,current version,outdated)
+          Columns to display in table output.
+
+  -o, --output table|json (default: table)
+          Output format.
+
+      --search string (default: owner:me)
+          Search for a workspace with a query.
+
+———
+Run `coder --help` for a list of global options.
diff --git a/cli/testdata/coder_list_--output_json.golden b/cli/testdata/coder_list_--output_json.golden
@@ -69,7 +69,8 @@
         "most_recently_seen": null
       },
       "template_version_preset_id": null,
-      "has_ai_task": false
+      "has_ai_task": false,
+      "has_external_agent": false
     },
     "latest_app_status": null,
     "outdated": false,

diff --git a/coderd/workspacebuilds.go b/coderd/workspacebuilds.go
@@ -1157,6 +1157,11 @@ func (api *API) convertWorkspaceBuild(
 		aiTasksSidebarAppID = &build.AITaskSidebarAppID.UUID
 	}
 
+	var hasExternalAgent *bool
+	if build.HasExternalAgent.Valid {
+		hasExternalAgent = &build.HasExternalAgent.Bool
+	}
+
 	apiJob := convertProvisionerJob(job)
 	transition := codersdk.WorkspaceTransition(build.Transition)
 	return codersdk.WorkspaceBuild{
@@ -1185,6 +1190,7 @@ func (api *API) convertWorkspaceBuild(
 		TemplateVersionPresetID: presetID,
 		HasAITask:               hasAITask,
 		AITaskSidebarAppID:      aiTasksSidebarAppID,
+		HasExternalAgent:        hasExternalAgent,
 	}, nil
 }
 

diff --git a/docs/manifest.json b/docs/manifest.json
@@ -1170,6 +1170,11 @@
 							"description": "Create a new external workspace",
 							"path": "reference/cli/external-workspaces_create.md"
 						},
+						{
+							"title": "external-workspaces list",
+							"description": "List external workspaces",
+							"path": "reference/cli/external-workspaces_list.md"
+						},
 						{
 							"title": "favorite",
 							"description": "Add a workspace to your favorites",

diff --git a/docs/reference/cli/external-workspaces.md b/docs/reference/cli/external-workspaces.md
diff --git a/docs/reference/cli/external-workspaces_list.md b/docs/reference/cli/external-workspaces_list.md