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.
List Your Workspaces
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:
Get the full list as JSON for scripts:
Print workspace IDs only, one per line:
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. |
-o json:
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) |
Switch Your Workspace Cloud
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.
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:
Or look up the target yourself, then switch by ID (the form that works in scripts):
For a single command against another workspace, skip switching and pass --workspace instead:
Output
On success, the new active workspace is confirmed on stdout:
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) |
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.Last modified on July 2, 2026
