coder · mtojek · Mar 25, 2025 · Mar 25, 2025 · Mar 25, 2025
diff --git a/cli/start.go b/cli/start.go
@@ -17,6 +17,8 @@ func (r *RootCmd) start() *serpent.Command {
 	var (
 		parameterFlags workspaceParameterFlags
 		bflags         buildFlags
+
+		noWait bool
 	)
 
 	client := new(codersdk.Client)
@@ -28,7 +30,15 @@ func (r *RootCmd) start() *serpent.Command {
 			serpent.RequireNArgs(1),
 			r.InitClient(client),
 		),
-		Options: serpent.OptionSet{cliui.SkipPromptOption()},
+		Options: serpent.OptionSet{
+			{
+				Flag:        "no-wait",
+				Description: "Return immediately after starting the workspace.",
+				Value:       serpent.BoolOf(&noWait),
+				Hidden:      false,
+			},
+			cliui.SkipPromptOption(),
+		},
 		Handler: func(inv *serpent.Invocation) error {
 			workspace, err := namedWorkspace(inv.Context(), client, inv.Args[0])
 			if err != nil {
@@ -80,6 +90,11 @@ func (r *RootCmd) start() *serpent.Command {
 				}
 			}
 
+			if noWait {
+				_, _ = fmt.Fprintf(inv.Stdout, "The %s workspace has been started in no-wait mode. Workspace is building in the background.\n", cliui.Keyword(workspace.Name))
+				return nil
+			}
+
 			err = cliui.WorkspaceBuild(inv.Context(), inv.Stdout, client, build.ID)
 			if err != nil {
 				return err

diff --git a/cli/start_test.go b/cli/start_test.go
@@ -441,3 +441,36 @@ func TestStart_Starting(t *testing.T) {
 
 	_ = testutil.RequireRecvCtx(ctx, t, doneChan)
 }
+
+func TestStart_NoWait(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	// Prepare user, template, workspace
+	client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+	owner := coderdtest.CreateFirstUser(t, client)
+	member, _ := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
+	version1 := coderdtest.CreateTemplateVersion(t, client, owner.OrganizationID, nil)
+	coderdtest.AwaitTemplateVersionJobCompleted(t, client, version1.ID)
+	template := coderdtest.CreateTemplate(t, client, owner.OrganizationID, version1.ID)
+	workspace := coderdtest.CreateWorkspace(t, member, template.ID)
+	coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, workspace.LatestBuild.ID)
+
+	// Stop the workspace
+	build := coderdtest.CreateWorkspaceBuild(t, member, workspace, database.WorkspaceTransitionStop)
+	coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, build.ID)
+
+	// Start in no-wait mode
+	inv, root := clitest.New(t, "start", workspace.Name, "--no-wait")
+	clitest.SetupConfig(t, member, root)
+	doneChan := make(chan struct{})
+	pty := ptytest.New(t).Attach(inv)
+	go func() {
+		defer close(doneChan)
+		err := inv.Run()
+		assert.NoError(t, err)
+	}()
+
+	pty.ExpectMatch("workspace has been started in no-wait mode")
+	_ = testutil.RequireRecvCtx(ctx, t, doneChan)
+}
diff --git a/cli/testdata/coder_start_--help.golden b/cli/testdata/coder_start_--help.golden
@@ -22,6 +22,9 @@ OPTIONS:
           Set the value of ephemeral parameters defined in the template. The
           format is "name=value".
 
+      --no-wait bool
+          Return immediately after starting the workspace.
+
       --parameter string-array, $CODER_RICH_PARAMETER
           Rich parameter value in the format "name=value".
 

diff --git a/docs/reference/cli/start.md b/docs/reference/cli/start.md