How to manage Workspaces

A Workspace is a named shortcut that connects the Radius CLI to a specific Radius control plane, selecting the kubectl context used to reach it along with the Radius Resource Group and Environment that rad commands target.

Workspaces are optional, but they save you from specifying the Resource Group and Environment on every rad command. When you install Radius with rad initialize, a Workspace named default is configured automatically, targeting the default Resource Group and default Environment. Most commands operate against the current Workspace, and you can switch between Workspaces or target a specific Workspace on a single command.

This guide explains how to create, inspect, select, replace, and delete Workspaces. For the configuration file format and storage location, see the local Workspace configuration reference.

Before you begin

Before creating a Workspace, verify that:

• The Radius control plane is installed and reachable through a context in your kubeconfig.
• The target Resource Group and Environment already exist on that control plane.

Create a Workspace

Use rad workspace create to save a Kubernetes context, Resource Group, and Environment as a named Workspace:

rad workspace create kubernetes my-workspace \
  --context my-context \
  --group my-group \
  --environment my-environment \
  --preview

The --context flag selects the Kubernetes context used to reach the Radius control plane. The --group and --environment flags set the default Resource Group and Environment for commands using the Workspace. Omit both defaults to select only the control plane, or omit --environment to select the control plane and Resource Group without a default Environment.

Most rad commands do not accept a Kubernetes context directly. To run commands against a specific context without changing the active kubectl context, create a Workspace for that context and pass its name through --workspace.

Creating a Workspace makes it the current Workspace.

List and inspect Workspaces

Use rad workspace list to display the saved Workspaces and identify the current one:

rad workspace list

Inspect the current Workspace or a named Workspace with rad workspace show:

rad workspace show
rad workspace show --workspace my-workspace

Switch the current Workspace

The current Workspace is the default target for rad commands. Use rad workspace switch to select another Workspace:

rad workspace switch my-workspace

Confirm the selection with rad workspace show. Subsequent commands use the selected control plane, Resource Group, and Environment unless the command overrides them.

Target a Workspace for one command

To use a different Workspace without changing the current one, pass --workspace (or -w) to the command:

rad deploy ./app.bicep --workspace my-workspace

This selects the Workspace’s control plane, Resource Group, and Environment for that command only.

Replace a Workspace

To change a Workspace’s context, Resource Group, or Environment, rerun rad workspace create with the same name and --force:

rad workspace create kubernetes my-workspace \
  --context another-context \
  --group another-group \
  --environment another-environment \
  --force \
  --preview

The replacement becomes the current Workspace. Specify every value the updated Workspace should retain.

Delete a Workspace

Delete a saved target with rad workspace delete:

rad workspace delete my-workspace

Deleting a Workspace removes only its local configuration. It does not delete the Radius control plane, Resource Group, Environment, or deployed resources. Use --yes to skip the confirmation prompt.