feat(cli,api): difyctl use workspace + member management

[lin-snow]

Important

1. Make sure you have read our contribution guidelines
2. Ensure there is an associated issue and you have been assigned to it
3. Use the correct syntax to link this PR: Fixes #<issue number>.

Summary

Adds server-side workspace switching and full member management to difyctl, on parity with the console's /workspaces/current/members endpoints but bearer-authed and gated on the path's workspace_id.

Backend — five new /openapi/v1/ endpoints, all double-gated by @accept_subjects(ACCOUNT) + @require_workspace_role(...):

Method	Path	Min role
POST	/workspaces/<id>/switch	any member
GET	/workspaces/<id>/members	any member
POST	/workspaces/<id>/members	admin / owner
DELETE	/workspaces/<id>/members/<member_id>	admin / owner
PUT	/workspaces/<id>/members/<member_id>/role	admin / owner

The new require_workspace_role decorator returns 404 for non-members (matching the existing GET /workspaces/<id> convention to avoid tenant-id existence leaks) and 403 for members with insufficient role. Domain logic is reused as-is from TenantService / RegisterService; invites still go through invite_new_member so the Celery activation email fires for newly-invited addresses. Owner is intentionally not assignable through invite or role-update — ownership transfer remains console-only.

CLI — five new commands:

difyctl use workspace <id>            # server-side switch + refresh hosts.yml
difyctl get member [-w <id>] [-o ...]
difyctl create member --email <e> --role <r> [-w <id>]
difyctl delete member <member-id> [-w <id>]
difyctl set member <member-id> --role <r> [-w <id>]

use workspace strictly orders POST /switch → GET /workspaces → saveHosts; any failure aborts with no local mutation so hosts.yml never diverges from the server. get member flags the calling account row with * (matched via hosts.yml.bundle.account.id). --role is client-enum-validated to normal | admin before any HTTP call.

The old difyctl auth use (a pure-local workspace picker) is deleted — its semantics are incompatible with the new server-side switch, so keeping it would only confuse. The "no workspace selected" hint now points at difyctl use workspace <id>.

Tests: 11 cases for the role-gate decorator, 26 for the new endpoints + payload validation, 12 for MembersClient + WorkspacesClient.switch, 21 across the five CLI command runners (including the no-fallback-on-switch-failure invariant). Local: 229/229 backend openapi tests, 681/681 CLI tests, pnpm type-check and pnpm build clean.

Screenshots

N/A — CLI-only.

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran make lint && make type-check (backend) and cd web && pnpm exec vp staged (frontend) to appease the lint gods

[github-actions]

Pyrefly Diff

base → PR

--- /tmp/pyrefly_base.txt	2026-05-19 11:02:39.922857722 +0000
+++ /tmp/pyrefly_pr.txt	2026-05-19 11:02:30.357853380 +0000
@@ -2182,6 +2182,26 @@
   --> tests/unit_tests/controllers/openapi/test_workspaces.py:49:12
 ERROR `in` is not supported between `Literal['GET']` and `None` [not-iterable]
   --> tests/unit_tests/controllers/openapi/test_workspaces.py:50:12
+ERROR Object of class `FunctionType` has no attribute `view_class` [missing-attribute]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:114:12
+ERROR `in` is not supported between `Literal['POST']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:115:12
+ERROR Object of class `FunctionType` has no attribute `view_class` [missing-attribute]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:120:12
+ERROR `in` is not supported between `Literal['GET']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:121:12
+ERROR `in` is not supported between `Literal['POST']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:122:12
+ERROR Object of class `FunctionType` has no attribute `view_class` [missing-attribute]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:127:12
+ERROR `in` is not supported between `Literal['DELETE']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:128:12
+ERROR Object of class `FunctionType` has no attribute `view_class` [missing-attribute]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:133:12
+ERROR `in` is not supported between `Literal['PUT']` and `None` [not-iterable]
+   --> tests/unit_tests/controllers/openapi/test_workspaces_members.py:134:12
+ERROR Object of class `NoneType` has no attribute `json`
+ERROR Object of class `NoneType` has no attribute `json`
 ERROR Cannot index into `Iterable[bytes]` [bad-index]
    --> tests/unit_tests/controllers/service_api/app/test_audio.py:190:16
 ERROR Cannot index into `Response` [bad-index]

[github-actions]

Pyrefly Type Coverage

Metric	Base	PR	Delta
Type coverage	0.00%	44.40%	+44.40%
Strict coverage	0.00%	43.92%	+43.92%
Typed symbols	0	22,960	+22,960
Untyped symbols	0	29,064	+29,064
Modules	0	2646	+2,646