feat(api,web,cli): difyctl v1.0 — OAuth device flow, /openapi/v1 auth pipeline, CLI client

2026-05-30 05:37:48 +08:00 · 2026-05-11 18:40:39 -07:00
parent 8f070f2190
commit 6779366dca
333 changed files with 28550 additions and 101 deletions
--- a/cli/docs/specs/workspaces.md
+++ b/cli/docs/specs/workspaces.md
@ -0,0 +1,87 @@
+---
+title: workspaces
+---
+
+# workspaces
+
+> Implementation: see [`cli/src/`](../../src/). Build & test: see [`cli/README.md`](../../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.
+