> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace operations

Workspaces provide a way to organize and manage resources within an IBM Cloud environment. A workspace represents an isolated context where resources such as agents, tools, and toolkits can be created, managed, and accessed. Each environment includes a global workspace by default, and more workspaces can be created to segment resources and control access.
All workspace operations are available through the orchestrate workspaces command group.

<Note>
  Workspaces are supported only for IBM Cloud environments.
</Note>

## Creating or updating a workspace

The orchestrate workspaces create command creates a new workspace or updates an existing one. If a workspace with the specified name exists, the command updates its description.

```Bash BASH theme={null}
orchestrate workspaces create \
--name workspace_name \
--description "Workspace description"
```

<Expandable title="command flags"> <ResponseField name="--name / -n" type="string" required> The name of the workspace. The value must be unique within the tenant. </ResponseField> <ResponseField name="--description / -d" type="string"> The description of the workspace. </ResponseField> </Expandable>

## Listing workspaces

The orchestrate workspaces list command lists all available workspaces and indicates which workspace is active.

```Bash BASH theme={null}
orchestrate workspaces list
```

<Expandable title="command flags"> <ResponseField name="--verbose / -v" type="boolean"> Displays full workspace details in JSON format. </ResponseField> </Expandable>

## Removing a workspace

The orchestrate workspaces remove command deletes a workspace. Artifact handling behavior is controlled through command flags.

```Bash BASH theme={null}
orchestrate workspaces remove \
--name workspace_name \
--delete-artifacts
```

<Expandable title="command flags"> <ResponseField name="--name / -n" type="string" required> The name of the workspace to remove. </ResponseField> <ResponseField name="--delete-artifacts" type="boolean"> Deletes all artifacts that are associated with the workspace. </ResponseField> <ResponseField name="--keep-artifacts" type="boolean"> Moves all artifacts to the global workspace instead of deleting them. </ResponseField> </Expandable>

## Activating a workspace

The orchestrate workspaces activate command sets a workspace as the active context. All subsequent operations are run within this workspace.

```Bash BASH theme={null}
orchestrate workspaces activate workspace_name
```

<Expandable title="command flags"> <ResponseField name="workspace_name" type="string" required> The name of the workspace to activate. </ResponseField> </Expandable>

## Deactivating a workspace

The orchestrate workspaces deactivate command resets the active context to the global workspace.

```Bash BASH theme={null}
orchestrate workspaces deactivate
```

## Exporting a workspace

The orchestrate workspaces export command exports all resources from a workspace into a ZIP file.

```Bash BASH theme={null}
orchestrate workspaces export \
--name workspace_name \
--output workspace_export.zip
```

<Expandable title="command flags"> <ResponseField name="--name / -n" type="string"> The name of the workspace to export. If not provided, the active workspace is used. </ResponseField> <ResponseField name="--output / -o" type="string" required> The path to the output ZIP file. </ResponseField> </Expandable>

## Managing workspace members

Workspace membership is managed by using the orchestrate workspaces members command group. These commands allow adding, listing, and removing users within a workspace.
If no workspace name is provided, the active workspace is used.

## Adding or updating a member

The orchestrate workspaces members add command adds a user to a workspace or updates their role.

```Bash BASH theme={null}
orchestrate workspaces members add \
--user user@example.com \
--role owner \
--name workspace_name
```

<Expandable title="command flags"> <ResponseField name="--user / -u" type="string" required> The email address of the user. </ResponseField> <ResponseField name="--role / -r" type="string" required> The role that is assigned to the user. Accepted values: `owner`, `editor`. </ResponseField> <ResponseField name="--name / -n" type="string"> The name of the workspace. If not provided, the active workspace is used. </ResponseField> </Expandable>

## Listing workspace members

The orchestrate workspaces members list command lists all members in a workspace.

```Bash BASH theme={null}
orchestrate workspaces members list \
--name workspace_name
```

<Expandable title="command flags"> <ResponseField name="--name / -n" type="string"> The name of the workspace. If not provided, the active workspace is used. </ResponseField> <ResponseField name="--verbose / -v" type="boolean"> Displays full member details in JSON format. </ResponseField> </Expandable>

## Removing a member

The orchestrate workspaces members remove command removes a user from a workspace.

```Bash BASH theme={null}
orchestrate workspaces members remove \
--user user@example.com \
--name workspace_name
```

<Expandable title="command flags"> <ResponseField name="--user / -u" type="string" required> The email address of the user to remove. </ResponseField> <ResponseField name="--name / -n" type="string"> The name of the workspace. If not provided, the active workspace is used. </ResponseField> </Expandable>

## Workspace context

When a workspace is active, all resource operations are scoped to that workspace. Commands such as create, list, update, and delete operate within the active workspace context. If no workspace is explicitly specified in a command, the active workspace is used automatically.

To copy agents from another workspace, see [Copy agents between workspaces](../agents/import_agent#copy-agents-between-workspaces).