Workspaces - Dify Docs

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.

difyctl get workspace lists the workspaces you belong to
use workspace switches the active one Cloud

Both accept the global flags.

List Your Workspaces#

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:

difyctl get workspace

Get the full list as JSON for scripts:

difyctl get workspace -o json

Print workspace IDs only, one per line:

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:

ID                                    NAME       ROLE    STATUS  CURRENTb4e8d2a6-7c3f-4a1e-9d5b-8f2c6e0a4d7b  Acme Team  owner   normal  *9c2f4e6a-8b1d-4f3e-a5c7-0d9e2b4f6a8c  Marketing  normal  normal

-o json:

{  "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 for the full scheme.

Switch Your Workspace Cloud#

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 in Common Tasks.

Arguments#

workspace-id: the workspace to switch to, from get workspace. 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.

Examples#

Pick interactively from your workspaces:

difyctl use workspace

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

difyctl get workspacedifyctl use workspace 9c2f4e6a-8b1d-4f3e-a5c7-0d9e2b4f6a8c

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

difyctl get app --workspace 9c2f4e6a-8b1d-4f3e-a5c7-0d9e2b4f6a8c

Output#

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

✓ 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 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:

The --workspace <id> flag on the command itself. Applies to that invocation only.
The DIFY_WORKSPACE_ID environment variable.
Your stored default, written to hosts.yml in the config directory when you sign in and updated by use workspace.

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, not a workspace name. A value that isn’t a UUID fails as a usage error.