认证与上下文

登录、管理会话，并在已保存的主机和账户之间切换

本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。

difyctl 可同时保持对多个 Dify 主机和账户的登录状态。每一对主机和账户构成一个上下文：其元数据保存在 配置目录 下的 hosts.yml 中，其 bearer token 则保存在操作系统的凭据存储中（并以受保护文件作为回退方案）。

每项任务对应一条命令：

• difyctl auth login 登录到某个主机
• auth whoami 打印当前登录的身份
• auth list 列出已保存的上下文
• auth logout 退出当前主机的登录
• use host / use account 切换当前上下文
• auth devices list 列出活跃会话
• auth devices revoke 撤销你不认识的会话

分步登录的完整说明，详见 认证。

登录

difyctl auth login [flags]

auth login 会运行 OAuth 2.0 设备流程：它打印一个一次性验证码和一个验证 URL，在浏览器中打开该 URL，然后等待你在浏览器中批准登录。CLI 全程不会接触你的密码。

标志

标志	类型	默认值	说明
--host <url>	string	none	要登录的 Dify 主机： 使用 Dify Cloud 时，填写 https://cloud.dify.ai。 在自部署的 Dify 上，使用 控制台 API URL。 不带协议的 URL 会自动补上 https://。 在终端中可省略此标志，直接输入主机；在非交互式会话（脚本、CI、管道）中，此标志为必填。
--no-browser	boolean	false	不自动打开浏览器，仅打印验证 URL。
--insecure	boolean	false	允许 http:// 主机，并接受 TLS 证书为自签名或无效的 https:// 主机（仅限本地开发）。

示例

登录到你的 Dify 主机：

difyctl auth login --host https://cloud.dify.ai

从 SSH 会话登录，并在另一台设备上打开验证 URL：

difyctl auth login --no-browser

输出

代码提示输出到 stderr，随后用一个加载动画等待浏览器端的批准：

! Copy this one-time code: WDJP-XKLM
  Open: https://cloud.dify.ai/device

登录成功后，确认信息输出到 stdout：

✓ Logged in to cloud.dify.ai as <your-email> (<your-name>)
  Workspace: <your-workspace>

Workspace: 这一行是你的默认工作空间。

每次登录还会注册一个服务端会话，标签为 difyctl on <hostname>。运行 auth devices list 可查看你的所有会话。登录到一个已登录的主机，会刷新该上下文中存储的 token。

退出码

退出码	含义
0	已登录
1	网络或服务器错误
2	用法错误，例如在终端外缺少 --host，或非 https 主机未加 --insecure
4	登录被拒绝（access_denied），或代码在你批准前已过期（expired_token）
6	版本不匹配：服务器版本对此 difyctl 而言过旧（在保存会话之前进行检查），或此 difyctl 对服务器而言过旧（HTTP 426）。服务器没有设备流程登录端点（unsupported_endpoint）时也会如此
7	触发限流（HTTP 429）

完整的退出码方案，详见 输出格式与退出码。

查看当前身份

difyctl auth whoami [flags]

auth whoami 打印当前上下文所属的身份。它读取存储的上下文，不会联系服务器，因此回答的是「当前活跃的是哪个身份」，而不是「token 是否仍然有效」。即使会话已在服务端过期，它也会以 0 退出。

标志

标志	类型	默认值	说明
--json	boolean	false	输出 JSON，而非纯文本行。

示例

difyctl auth whoami

用于脚本：

difyctl auth whoami --json

输出

<your-email> (<your-name>)

--json 输出是包含 id、email 和 name 的单行内容：

{"id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","email":"<your-email>","name":"<your-name>"}

退出码

退出码	含义
0	存在活跃的上下文
4	未登录（not_logged_in）

列出已保存的上下文

difyctl auth list [flags]

auth list 显示所有已存储的主机和账户对，并标记出当前活跃的那一对。与 auth whoami 一样，它完全在本地运行，不会联系服务器。

标志

标志	类型	默认值	说明
-o <format>	string	none	输出格式：json、yaml 或 name。省略此标志则输出默认表格。

示例

difyctl auth list

输出

格式	stdout 输出的内容
默认	一张上下文表格：主机、账户和活跃标记。
-o json、-o yaml	一个 contexts 数组，每个条目包含 host、account、name 和 active。
-o name	账户邮箱，每行一个。

默认表格：

HOST                    ACCOUNT                      ACTIVE
cloud.dify.ai           [e-mail] (Your Name)  *
dify.internal.acme.com  [e-mail] (Your Name)

-o json：

{
  "contexts": [
    {
      "host": "cloud.dify.ai",
      "account": "[e-mail]",
      "name": "Your Name",
      "active": true
    },
    {
      "host": "dify.internal.acme.com",
      "account": "[e-mail]",
      "name": "Your Name",
      "active": false
    }
  ]
}

退出码

退出码	含义
0	成功，包括没有任何已存储上下文的情况
2	用法错误，例如不支持的 -o 取值

退出登录

difyctl auth logout

auth logout 会在服务端撤销当前上下文的会话，然后从本机删除其 token 和 hosts.yml 条目。其他已保存的上下文不受影响。

本地清理始终会执行。如果服务端撤销失败，difyctl 会在 stderr 打印一条警告，并照常清除你的凭据。

token 存放在操作系统钥匙串中、而退出登录时又无法读取（已锁定，或没有桌面会话）时也是如此：跳过撤销，本地清理仍会执行。

标志

无。

示例

difyctl auth logout

输出

✓ Logged out of cloud.dify.ai

退出码

退出码	含义
0	已退出登录
4	未登录（not_logged_in）

切换当前主机

difyctl use host [flags]

use host 改变后续命令针对哪个已存储的主机运行。它在本地生效：仅在你已有的登录之间重新指向当前上下文。要添加新主机，请改用 auth login --host。

标志

标志	类型	默认值	说明
--domain <host>	string	none	要切换到的已存储主机，写作其裸域名（cloud.dify.ai），不带协议。 在终端中可省略此标志，从已存储的主机中选取。在非交互式会话（脚本、CI、管道）中，此标志为必填。

示例

按域名切换到一个已存储的主机：

difyctl use host --domain dify.internal.acme.com

输出

切换成功后，会确认新的当前主机：

✓ Active host is now dify.internal.acme.com

如果域名是你未曾登录过的，则会以用法错误失败，并列出已知的主机。

退出码

退出码	含义
0	已切换
2	用法错误：未知主机，或在终端外缺少 --domain
4	没有已存储的登录（not_logged_in）

切换当前账户

difyctl use account [flags]

use account 改变当前主机上活跃的是哪个已存储账户。与 use host 一样，它在本地生效，仅在你已有的登录之间切换。

标志

标志	类型	默认值	说明
--email <email>	string	none	要切换到的账户。 在终端中可省略此标志，从已存储的账户中选取；在非交互式会话（脚本、CI、管道）中，此标志为必填。

示例

在当前主机上切换到另一个账户：

difyctl use account --email [e-mail]

输出

切换成功后，会确认新的当前账户：

✓ Active account on cloud.dify.ai is now [e-mail]

如果某邮箱未存储在当前主机上，则会以用法错误失败，并列出已知的账户。如果某账户已存储的 token 不复存在（已撤销，或被 会话撤销 清除），则会以未登录错误失败，并提示你重新登录。

退出码

退出码	含义
0	已切换
2	用法错误：未知账户，或在终端外缺少 --email
4	此主机上没有已存储的登录，或所选账户没有凭据

列出活跃会话

difyctl auth devices list [flags]

每次设备流程登录都会注册一个服务端会话，默认标签为 difyctl on <hostname>。auth devices list 显示你账户下活跃的会话，便于你发现并 撤销 那些你不认识的会话。

标志

标志	类型	默认值	说明
--json	boolean	false	输出 JSON，而非表格。
--page <n>	integer	1	页码。
--limit <n>	integer	20	每页条数，范围 1 到 200。此标志优先，其次是 DIFY_LIMIT。

示例

列出你账户下活跃的会话：

difyctl auth devices list

输出

DEVICE                        CREATED               LAST USED             CURRENT
difyctl on Yours-MacBook-Pro  2026-06-02T09:14:31Z  2026-06-11T08:02:17Z  *
difyctl on build-runner-3     2026-05-28T11:40:09Z  2026-06-10T22:51:44Z

表格中用 * 标记你当前登录所使用的会话。如果某会话自登录以来一直未被使用，则 LAST USED 为空。

--json 打印单行 JSON：一个 data 数组，每个会话对应一个条目，外加分页字段 page、limit、total 和 has_more。每个条目包含 id、prefix、client_id、device_label、created_at、last_used_at 和 expires_at。

退出码

退出码	含义
0	成功
1	网络或服务器错误
2	用法错误，例如 --limit 0
4	认证失败
7	触发限流（HTTP 429）

撤销会话

difyctl auth devices revoke [<target>] [flags]

auth devices revoke 在服务端结束会话。目标的匹配顺序为：先按标签精确匹配，再按会话 ID 精确匹配，最后按不区分大小写的标签子串匹配。如果某个目标匹配到多个会话，则会失败并列出候选项，此时可传入精确的 ID 来消除歧义。

在终端中，difyctl 会先要求你确认；传入 -y/--yes 可跳过提示。在终端外（脚本或管道），它会直接撤销，不再提示。

如果你撤销的是当前登录所使用的会话，difyctl 还会清除该上下文的本地凭据：你在本机上将被退出登录。

参数

• <target>：来自 auth devices list 的设备标签或会话 ID。除非传入 --all，否则为必填。

标志

标志	类型	默认值	说明
--all	boolean	false	撤销除当前会话外的所有会话。
-y, --yes	boolean	false	跳过确认提示。

示例

按标签撤销单个会话：

difyctl auth devices revoke "difyctl on build-runner-3"

退出所有其他位置的登录，仅保留本机的会话：

difyctl auth devices revoke --all

输出

撤销成功后，difyctl 打印 ✓ Revoked <N> session(s)。如果某个命名目标没有匹配到任何会话，则会失败并提示 no session matches "<target>"。在没有其他会话时使用 --all，会打印 no sessions to revoke 并以 0 退出。

退出码

退出码	含义
0	已撤销，或在 --all 下没有可撤销的会话
1	网络或服务器错误
2	用法错误：没有目标且未加 --all、目标有歧义、没有匹配的会话，或拒绝了确认提示
4	认证失败
7	触发限流（HTTP 429）

完整的退出码方案，详见 输出格式与退出码。