Skip to main content
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. Both accept the global flags.
Workspaces apply to account users only. If you signed in through external SSO, you’re scoped to a single context with no workspace, and the commands here don’t apply. See Scope and Limitations for details.

​
List Your Workspaces

difyctl get workspace [flags]

​
Flags

FlagTypeDefaultDescription
-o <format>stringnoneOutput 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

FormatWhat stdout gets
defaultAn aligned table. CURRENT marks your active workspace with *, and ROLE is your role in each one.
-o wideThe same columns. Workspaces have no wide-only columns.
-o json, -o yamlA workspaces array, each entry carrying id, name, role, status, and current.
-o nameThe 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

CodeMeaning
0Success
1Network or server error
2Usage error, such as an unsupported -o value
4Authentication failure
7Rate limited (HTTP 429)
See Output Formats and Exit Codes for the full scheme.

​
Switch Your Workspace

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

CodeMeaning
0Success
1Workspace not found, or another server error
2Usage error, such as omitting workspace-id where there’s no terminal to pick in
4Authentication failure, or no workspaces available when use workspace opens its picker
7Rate 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.