> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-docs-new-agent-experience.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> List your workspaces, switch the active one, and understand how difyctl resolves which workspace to use

`difyctl` works in one active workspace at a time, taken from a flag, an environment variable, or your stored default. For the order those take priority, see [How difyctl Picks a Workspace](#how-difyctl-picks-a-workspace).

* [`difyctl get workspace`](#list-your-workspaces) lists the workspaces you belong to
* [`use workspace`](#switch-your-workspace-cloud) switches the active one <Badge color="blue">Cloud</Badge>

Both accept the [global flags](/en/cli/reference/global-flags).

## List Your Workspaces

```text theme={null}
difyctl get workspace [flags]
```

### Flags

| Flag          | Type   | Default | Description                                                                            |
| :------------ | :----- | :------ | :------------------------------------------------------------------------------------- |
| `-o <format>` | string | none    | Output format: `json`, `yaml`, `name`, or `wide`. Omit the flag for the default table. |

### Examples

See your workspaces and which one is active:

```bash theme={null}
difyctl get workspace
```

Get the full list as JSON for scripts:

```bash theme={null}
difyctl get workspace -o json
```

Print workspace IDs only, one per line:

```bash theme={null}
difyctl get workspace -o name
```

### Output

| Format               | What stdout gets                                                                                       |
| :------------------- | :----------------------------------------------------------------------------------------------------- |
| default              | An aligned table. `CURRENT` marks your active workspace with `*`, and `ROLE` is your role in each one. |
| `-o wide`            | The same columns. Workspaces have no wide-only columns.                                                |
| `-o json`, `-o yaml` | A `workspaces` array, each entry carrying `id`, `name`, `role`, `status`, and `current`.               |
| `-o name`            | The workspace IDs, one per line.                                                                       |

Default table:

```text theme={null}
ID                                    NAME       ROLE    STATUS  CURRENT
b4e8d2a6-7c3f-4a1e-9d5b-8f2c6e0a4d7b  Acme Team  owner   normal  *
9c2f4e6a-8b1d-4f3e-a5c7-0d9e2b4f6a8c  Marketing  normal  normal
```

`-o json`:

```json theme={null}
{
  "workspaces": [
    {
      "id": "b4e8d2a6-7c3f-4a1e-9d5b-8f2c6e0a4d7b",
      "name": "Acme Team",
      "role": "owner",
      "status": "normal",
      "current": true
    },
    {
      "id": "9c2f4e6a-8b1d-4f3e-a5c7-0d9e2b4f6a8c",
      "name": "Marketing",
      "role": "normal",
      "status": "normal",
      "current": false
    }
  ]
}
```

### Exit Codes

| Code | Meaning                                        |
| :--- | :--------------------------------------------- |
| `0`  | Success                                        |
| `1`  | Network or server error                        |
| `2`  | Usage error, such as an unsupported `-o` value |
| `4`  | Authentication failure                         |
| `7`  | Rate limited (HTTP 429)                        |

See [Output Formats and Exit Codes](/en/cli/reference/output-formats-and-exit-codes) for the full scheme.

## Switch Your Workspace <Badge color="blue">Cloud</Badge>

```text theme={null}
difyctl use workspace [workspace-id] [flags]
```

`use workspace` switches your active workspace on the server first, then updates the stored default in `hosts.yml`. If the switch fails (the workspace doesn't exist, or you're not a member), your local state is left untouched.

<Tip>
  For the everyday invocation, see [Switch Your Workspace](/en/cli/common-tasks#switch-your-workspace-cloud) in Common Tasks.
</Tip>

### Arguments

* `workspace-id`: the workspace to switch to, from [`get workspace`](#list-your-workspaces). In a terminal, omit it to pick from your workspaces, the current one marked `*`. In a non-interactive session (script, CI, pipe), it's required.

### Flags

Only the [global flags](/en/cli/reference/global-flags).

### Examples

Pick interactively from your workspaces:

```bash theme={null}
difyctl use workspace
```

Or look up the target yourself, then switch by ID (the form that works in scripts):

```bash theme={null}
difyctl get workspace
difyctl use workspace 9c2f4e6a-8b1d-4f3e-a5c7-0d9e2b4f6a8c
```

For a single command against another workspace, skip switching and pass `--workspace` instead:

```bash theme={null}
difyctl get app --workspace 9c2f4e6a-8b1d-4f3e-a5c7-0d9e2b4f6a8c
```

### Output

On success, the new active workspace is confirmed on stdout:

```text theme={null}
✓ Switched to Marketing (9c2f4e6a-8b1d-4f3e-a5c7-0d9e2b4f6a8c)
```

The switch persists: every subsequent command runs against the new workspace until you switch again.

### Exit Codes

| Code | Meaning                                                                                  |
| :--- | :--------------------------------------------------------------------------------------- |
| `0`  | Success                                                                                  |
| `1`  | Workspace not found, or another server error                                             |
| `2`  | Usage error, such as omitting `workspace-id` where there's no terminal to pick in        |
| `4`  | Authentication failure, or no workspaces available when `use workspace` opens its picker |
| `7`  | Rate limited (HTTP 429)                                                                  |

See [Output Formats and Exit Codes](/en/cli/reference/output-formats-and-exit-codes) for the full scheme.

## How difyctl Picks a Workspace

Apps live in exactly one workspace, so every command that targets one needs a workspace to run against. `difyctl` resolves it in this order, taking the first value it finds:

1. The `--workspace <id>` flag on the command itself. Applies to that invocation only.
2. The [`DIFY_WORKSPACE_ID`](/en/cli/reference/environment-variables) environment variable.
3. Your stored default, written to `hosts.yml` in the config directory when you sign in and updated by [`use workspace`](#switch-your-workspace-cloud).

If none of these yields a workspace, the command fails with exit code `2`.

Workspace IDs are UUIDs, so pass an ID from [`get workspace`](#list-your-workspaces), not a workspace name. A value that isn't a UUID fails as a usage error.