3.6 KiB
title
| title |
|---|
| workspaces |
workspaces
Implementation: see
cli/src/. Build & test: seecli/README.md.
Workspace discovery and context management for account users.
difyctl get workspace [flags]
difyctl auth use <workspace-id>
Companion: auth.md §Session model, server/endpoints.md §OpenAPI — workspaces.
Workspace model
An account user belongs to N workspaces (tenants). At login, default_workspace_id from /account becomes the active workspace, stored in hosts.yml. dfoa_-surface commands (get apps, get app, describe app, run app) scope to the active workspace unless overridden.
External SSO users (dfoe_) have no workspace concept. The get workspace, auth use, and --workspace flag are all command-level errors on a dfoe_ session (CLI rejects before any network call). Server-side, /openapi/v1/workspaces* returns 403 wrong_surface for dfoe_ (the surface gate rejects).
Resolution chain (account users)
Every resource command resolves workspace through:
| Priority | Source |
|---|---|
| 1 | --workspace <id> flag |
| 2 | DIFY_WORKSPACE_ID env var |
| 3 | current_workspace_id in hosts.yml (set by auth use) |
| 4 | default_workspace_id from last login response |
| 5 | Error: error: no workspace selected; run 'difyctl auth use <id>' or pass --workspace |
Env precedence is explicit. DIFY_WORKSPACE_ID (priority 2) wins over hosts.yml (priority 3 + 4) by design — env vars override on-disk state per config.md §Precedence. CLI does not validate ID syntax client-side; malformed IDs (e.g., random-string env value) hit the next resource command and surface server's 404 (workspace not found) → exit 1.
difyctl get workspace — list
$ difyctl get workspace
ID NAME ROLE
ws-abc123 Acme Corp owner
ws-def456 Side Project member
Flags:
| Flag | Purpose |
|---|---|
-o json|yaml|name |
Output format |
-o name → workspace IDs one per line.
Server: GET /openapi/v1/workspaces — bearer auth, dfoa_ only. dfoe_ → 403 wrong_surface at the surface gate.
Active workspace marked with * in the NAME column when stored current matches a row.
difyctl auth use <workspace-id> — switch active workspace
$ difyctl auth use ws-def456
Switched to workspace: Side Project (ws-def456)
Writes current_workspace_id to hosts.yml. Subsequent resource commands resolve to this workspace until changed.
External SSO subjects: error: workspace context unavailable for external SSO sessions. Exit 2.
Unknown ID: does not validate against server at write time (avoids extra RTT). Invalid IDs produce 404 on the next resource command.
Flags: none. No --yes needed — non-destructive state write.
--workspace flag
Every dfoa_-surface resource command (get apps, get app, describe app, run app, get workspace) accepts --workspace <id>. Overrides active workspace for that invocation only; does not persist.
External SSO sessions: flag rejected client-side with error: --workspace is not supported on external SSO sessions; the permitted-external-apps surface has no workspace concept. Exit 2.