[CLI-2354] Add confluent organization use command for org switching

internal/organization/command.go

@@ -23,6 +23,7 @@ func New(prerunner pcmd.PreRunner) *cobra.Command {
 	cmd.AddCommand(c.newDescribeCommand())
 	cmd.AddCommand(c.newListCommand())
 	cmd.AddCommand(c.newUpdateCommand())
+	cmd.AddCommand(c.newUseCommand())
 
 	return cmd
 }

internal/organization/command_use.go

@@ -0,0 +1,88 @@
+package organization
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	pcmd "github.com/confluentinc/cli/v4/pkg/cmd"
+	"github.com/confluentinc/cli/v4/pkg/errors"
+	"github.com/confluentinc/cli/v4/pkg/output"
+	"github.com/confluentinc/cli/v4/pkg/resource"
+)
+
+func (c *command) newUseCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:               "use <id>",
+		Short:             "Use a Confluent Cloud organization in subsequent commands.",
+		Long:              "Choose a Confluent Cloud organization to be used in subsequent commands. Switching organizations clears your active environment and Kafka cluster selections.",
+		Args:              cobra.ExactArgs(1),
+		ValidArgsFunction: pcmd.NewValidArgsFunction(c.validArgs),
+		RunE:              c.use,
+	}
+
+	return cmd
+}
+
+func (c *command) validArgs(cmd *cobra.Command, args []string) []string {
+	if len(args) > 0 {
+		return nil
+	}
+
+	if err := c.PersistentPreRunE(cmd, args); err != nil {
+		return nil
+	}
+
+	organizations, err := c.V2Client.ListOrgOrganizations()
+	if err != nil {
+		return nil
+	}
+
+	suggestions := make([]string, len(organizations))
+	for i, org := range organizations {
+		suggestions[i] = fmt.Sprintf("%s\t%s", org.GetId(), org.GetDisplayName())
+	}
+	return suggestions
+}
+
+func (c *command) use(_ *cobra.Command, args []string) error {
+	id := args[0]
+
+	// Use the list endpoint instead of get-by-ID because the org-scoped JWT
+	// only authorizes reading the *current* organization. The list endpoint
+	// returns every organization the user belongs to regardless of JWT scope.
+	organizations, err := c.V2Client.ListOrgOrganizations()
+	if err != nil {
+		return fmt.Errorf("failed to list organizations: %w", err)
+	}
+
+	found := false
+	for _, org := range organizations {
+		if org.GetId() == id {
+			found = true
+			break
+		}
+	}
+	if !found {
+		return errors.NewErrorWithSuggestions(
+			fmt.Sprintf(`organization "%s" not found or access forbidden`, id),
+			"List available organizations with `organization list`.",
+		)
+	}
+
+	if id == c.Context.GetCurrentOrganization() {
+		output.Printf(c.Config.EnableColor, errors.UsingResourceMsg, resource.Organization, id)
+		return nil
+	}
+
+	if err := c.Context.SwitchOrganization(c.Client, id); err != nil {
+		return fmt.Errorf("failed to switch to organization %q: %w", id, err)
+	}
+
+	if err := c.Config.Save(); err != nil {
+		return err
+	}
+
+	output.Printf(c.Config.EnableColor, errors.UsingResourceMsg, resource.Organization, id)
+	return nil
+}

pkg/config/context.go

@@ -112,6 +112,42 @@ func (c *Context) UpdateAuthTokens(token, refreshToken string) error {
 	return c.Save()
 }
 
+// SwitchOrganization switches the context to a different Confluent Cloud
+// organization by minting a new org-scoped JWT using the existing user-scoped
+// refresh token. It clears all environment-scoped state (environments, Kafka
+// clusters) since those are org-scoped. The caller must call Config.Save()
+// after this method returns successfully.
+func (c *Context) SwitchOrganization(client *ccloudv1.Client, orgId string) error {
+	previousOrgId := c.LastOrgId
+	previousAuthToken := c.State.AuthToken
+	previousRefreshToken := c.State.AuthRefreshToken
+
+	// Set the target org before refreshing so RefreshSession picks it up
+	// via GetCurrentOrganization().
+	c.LastOrgId = orgId
+
+	if err := c.RefreshSession(client); err != nil {
+		c.LastOrgId = previousOrgId
+		c.State.AuthToken = previousAuthToken
+		c.State.AuthRefreshToken = previousRefreshToken
+		return err
+	}
+
+	// Clear all environment-scoped state: environments and Kafka clusters
+	// belong to a specific org, so stale IDs from the previous org must not
+	// leak into the new context.
+	c.CurrentEnvironment = ""
+	c.Environments = map[string]*EnvironmentContext{}
+	if c.KafkaClusterContext != nil {
+		c.KafkaClusterContext.ActiveKafkaCluster = ""
+		c.KafkaClusterContext.ActiveKafkaClusterEndpoint = ""
+		c.KafkaClusterContext.KafkaClusterConfigs = map[string]*KafkaClusterConfig{}
+		c.KafkaClusterContext.KafkaEnvContexts = map[string]*KafkaEnvContext{}
+	}
+
+	return nil
+}
+
 func (c *Context) IsCloud(isTest bool) bool {
 	if isTest && c.PlatformName == testserver.TestCloudUrl.String() {
 		return true

pkg/config/context_test.go

@@ -1,10 +1,14 @@
 package config
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/require"
+
+	ccloudv1 "github.com/confluentinc/ccloud-sdk-go-v1-public"
+	ccloudv1mock "github.com/confluentinc/ccloud-sdk-go-v1-public/mock"
 )
 
 var (
@@ -77,6 +81,123 @@
 	}
 }
 
+func TestSwitchOrganization(t *testing.T) {
+	cfg := AuthenticatedCloudConfigMock()
+	ctx := cfg.Context()
+
+	oldRefreshToken := "old-refresh-token"
+	ctx.State.AuthRefreshToken = oldRefreshToken
+
+	newOrgId := "org-new-id"
+	newToken := "new-auth-token"
+	newRefreshToken := "new-refresh-token"
+
+	auth := &ccloudv1mock.Auth{
+		LoginFunc: func(req *ccloudv1.AuthenticateRequest) (*ccloudv1.AuthenticateReply, error) {
+			require.Equal(t, newOrgId, req.OrgResourceId)
+			require.Equal(t, oldRefreshToken, req.RefreshToken)
+			return &ccloudv1.AuthenticateReply{
+				Token:        newToken,
+				RefreshToken: newRefreshToken,
+			}, nil
+		},
+	}
+	client := &ccloudv1.Client{Auth: auth}
+
+	err := ctx.SwitchOrganization(client, newOrgId)
+	require.NoError(t, err)
+
+	require.Equal(t, newOrgId, ctx.LastOrgId)
+	require.Equal(t, newToken, ctx.State.AuthToken)
+	require.Equal(t, newRefreshToken, ctx.State.AuthRefreshToken)
+}
+
+func TestSwitchOrganization_ClearsEnvironmentState(t *testing.T) {
+	cfg := AuthenticatedCloudConfigMock()
+	ctx := cfg.Context()
+	ctx.State.AuthRefreshToken = "refresh-token"
+
+	// Pre-populate environment and Kafka state
+	ctx.CurrentEnvironment = "env-123"
+	ctx.Environments["env-123"] = &EnvironmentContext{CurrentFlinkComputePool: "pool-1"}
+	ctx.KafkaClusterContext.KafkaEnvContexts["env-123"] = &KafkaEnvContext{
+		ActiveKafkaCluster:  "lkc-999",
+		KafkaClusterConfigs: map[string]*KafkaClusterConfig{"lkc-999": {ID: "lkc-999"}},
+	}
+
+	auth := &ccloudv1mock.Auth{
+		LoginFunc: func(_ *ccloudv1.AuthenticateRequest) (*ccloudv1.AuthenticateReply, error) {
+			return &ccloudv1.AuthenticateReply{Token: "t", RefreshToken: "r"}, nil
+		},
+	}
+	client := &ccloudv1.Client{Auth: auth}
+
+	err := ctx.SwitchOrganization(client, "org-other")
+	require.NoError(t, err)
+
+	require.Empty(t, ctx.CurrentEnvironment)
+	require.Empty(t, ctx.Environments)
+	require.Empty(t, ctx.KafkaClusterContext.ActiveKafkaCluster)
+	require.Empty(t, ctx.KafkaClusterContext.ActiveKafkaClusterEndpoint)
+	require.Empty(t, ctx.KafkaClusterContext.KafkaClusterConfigs)
+	require.Empty(t, ctx.KafkaClusterContext.KafkaEnvContexts)
+}
+
+func TestSwitchOrganization_RollbackOnFailure(t *testing.T) {
+	cfg := AuthenticatedCloudConfigMock()
+	ctx := cfg.Context()
+
+	oldOrgId := ctx.LastOrgId
+	oldToken := ctx.State.AuthToken
+	oldRefreshToken := "old-refresh-token"
+	ctx.State.AuthRefreshToken = oldRefreshToken
+
+	// Pre-populate environment state to verify it is NOT cleared on failure
+	ctx.CurrentEnvironment = "env-123"
+	ctx.Environments["env-123"] = &EnvironmentContext{}
+
+	auth := &ccloudv1mock.Auth{
+		LoginFunc: func(_ *ccloudv1.AuthenticateRequest) (*ccloudv1.AuthenticateReply, error) {
+			return nil, fmt.Errorf("auth failed")
+		},
+	}
+	client := &ccloudv1.Client{Auth: auth}
+
+	err := ctx.SwitchOrganization(client, "org-other")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "auth failed")
+
+	// Verify full rollback
+	require.Equal(t, oldOrgId, ctx.LastOrgId)
+	require.Equal(t, oldToken, ctx.State.AuthToken)
+	require.Equal(t, oldRefreshToken, ctx.State.AuthRefreshToken)
+
+	// Verify environment state was NOT touched
+	require.Equal(t, "env-123", ctx.CurrentEnvironment)
+	require.Contains(t, ctx.Environments, "env-123")
+}
+
+func TestSwitchOrganization_NilKafkaClusterContext(t *testing.T) {
+	cfg := AuthenticatedCloudConfigMock()
+	ctx := cfg.Context()
+	ctx.State.AuthRefreshToken = "refresh-token"
+	ctx.KafkaClusterContext = nil
+
+	auth := &ccloudv1mock.Auth{
+		LoginFunc: func(_ *ccloudv1.AuthenticateRequest) (*ccloudv1.AuthenticateReply, error) {
+			return &ccloudv1.AuthenticateReply{Token: "t", RefreshToken: "r"}, nil
+		},
+	}
+	client := &ccloudv1.Client{Auth: auth}
+
+	err := ctx.SwitchOrganization(client, "org-other")
+	require.NoError(t, err)
+
+	require.Equal(t, "org-other", ctx.LastOrgId)
+	require.Empty(t, ctx.CurrentEnvironment)
+	require.Nil(t, ctx.KafkaClusterContext)
+}
+
 func getBaseContext() *Context {
 	return AuthenticatedCloudConfigMock().Context()
 }

test/fixtures/output/organization/help.golden

@@ -10,6 +10,7 @@ Available Commands:
   describe    Describe the current Confluent Cloud organization.
   list        List Confluent Cloud organizations.
   update      Update the current Confluent Cloud organization.
+  use         Use a Confluent Cloud organization in subsequent commands.
 
 Global Flags:
   -h, --help            Show help for this command.

test/fixtures/output/organization/use-already-active.golden

@@ -0,0 +1 @@
+Using organization "abc-123".

test/fixtures/output/organization/use-help.golden

@@ -0,0 +1,9 @@
+Choose a Confluent Cloud organization to be used in subsequent commands. Switching organizations clears your active environment and Kafka cluster selections.
+
+Usage:
+  confluent organization use <id> [flags]
+
+Global Flags:
+  -h, --help            Show help for this command.
+      --unsafe-trace    Equivalent to -vvvv, but also log HTTP requests and responses which might contain plaintext secrets.
+  -v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).

test/fixtures/output/organization/use-list-error.golden

@@ -0,0 +1 @@
+Error: failed to list organizations: Forbidden

test/fixtures/output/organization/use-not-found.golden

@@ -0,0 +1,4 @@
+Error: organization "org-dne" not found or access forbidden
+
+Suggestions:
+    List available organizations with `organization list`.

test/fixtures/output/organization/use.golden

@@ -0,0 +1 @@
+Using organization "abc-456".

test/organization_test.go

@@ -14,6 +14,8 @@ func (s *CLITestSuite) TestOrganization() {
 		{args: "organization list -o json", fixture: "organization/list-json.golden"},
 		{args: "organization update --name default-updated", fixture: "organization/update.golden"},
 		{args: "organization update --name default-updated -o json", fixture: "organization/update-json.golden"},
+		{args: "organization use abc-456", fixture: "organization/use.golden"},
+		{args: "organization use abc-123", fixture: "organization/use-already-active.golden"},
 	}
 
 	for _, test := range tests {
@@ -47,4 +49,29 @@ func (s *CLITestSuite) TestOrganization() {
 		}
 		s.runIntegrationTest(test)
 	})
+
+	s.T().Run("organization use list error", func(t *testing.T) {
+		testserver.TestOrgListError = true
+		defer func() { testserver.TestOrgListError = false }()
+
+		test := CLITest{
+			args:     "organization use abc-456",
+			fixture:  "organization/use-list-error.golden",
+			exitCode: 1,
+			login:    "cloud",
+		}
+		s.runIntegrationTest(test)
+	})
+
+	// The use command validates via the list endpoint, so org-dne simply
+	// won't appear in the returned list — no need for TestOrgNotFound.
+	s.T().Run("organization use not found", func(t *testing.T) {
+		test := CLITest{
+			args:     "organization use org-dne",
+			fixture:  "organization/use-not-found.golden",
+			exitCode: 1,
+			login:    "cloud",
+		}
+		s.runIntegrationTest(test)
+	})
 }

test/test-server/org_handlers.go

@@ -27,6 +27,8 @@ var (
 	}
 	// Test flag to control organization not found error
 	TestOrgNotFound = false
+	// Test flag to control organization list error
+	TestOrgListError = false
 )
 
 // Handler for: "/org/v2/environments/{id}"
@@ -145,6 +147,15 @@ func handleOrgOrganizations(t *testing.T) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		switch r.Method {
 		case http.MethodGet:
+			if TestOrgListError {
+				w.WriteHeader(http.StatusForbidden)
+				resp := errors.ErrorResponseBody{Errors: []errors.ErrorDetail{
+					{Detail: "Forbidden"},
+				}}
+				err := json.NewEncoder(w).Encode(resp)
+				require.NoError(t, err)
+				return
+			}
 			organizationList := &orgv2.OrgV2OrganizationList{Data: []orgv2.OrgV2Organization{
 				{Id: orgv2.PtrString("abc-123"), DisplayName: orgv2.PtrString("org1"), JitEnabled: orgv2.PtrBool(true)},
 				{Id: orgv2.PtrString("abc-456"), DisplayName: orgv2.PtrString("org2"), JitEnabled: orgv2.PtrBool(true)},