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.

• 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  CURRENT
b4e8d2a6-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.

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 workspace
difyctl 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:

1. The --workspace <id> flag on the command itself. Applies to that invocation only.
2. The DIFY_WORKSPACE_ID environment variable.
3. 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.