跳转到主要内容
本文档由 AI 自动翻译。如有任何不准确之处，请参考 英文原版。
difyctl 可同时保持对多个 Dify 主机和账户的登录状态。每一对主机和账户构成一个上下文：其元数据保存在 配置目录 下的 hosts.yml 中，其 bearer token 则保存在操作系统的凭据存储中（并以密封文件作为回退方案）。 每项任务对应一条命令： 分步登录的完整说明，详见 认证。

​
登录

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

​
标志

标志类型默认值说明
--host <url>stringnone要登录的 Dify 主机。在自部署的 Dify 上，使用 控制台 API URL，因为 difyctl 针对控制台 API 进行操作。不带协议的 URL 会自动补上 https://。在终端中可省略此标志，直接输入主机；在非交互式会话（脚本、CI、管道）中，此标志为必填。
--no-browserbooleanfalse不自动打开浏览器，仅打印验证 URL。
--insecurebooleanfalse允许 http:// 主机（仅限本地开发）。

​
示例

登录到你的 Dify 主机： 
difyctl auth login --host https://dify.example.com
从 SSH 会话登录，并在另一台设备上打开验证 URL： 
difyctl auth login --no-browser

​
输出

代码提示输出到 stderr，随后用一个加载动画等待浏览器端的批准： 
! Copy this one-time code: WDJP-XKLM
  Open: https://dify.example.com/device
登录成功后，确认信息输出到 stdout： 
✓ Logged in to dify.example.com 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服务器没有设备流程登录端点（unsupported_endpoint）
7触发限流（HTTP 429）
完整的退出码方案，详见 输出格式与退出码。

​
查看当前身份

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

​
标志

标志类型默认值说明
--jsonbooleanfalse输出 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>stringnone输出格式：json、yaml 或 name。省略此标志则输出默认表格。

​
示例

difyctl auth list

​
输出

格式stdout 输出的内容
默认一张上下文表格：主机、账户和活跃标记。
-o json、-o yaml一个 contexts 数组，每个条目包含 host、account、name 和 active。
-o name账户邮箱，每行一个。
默认表格： 
HOST                    ACCOUNT                      ACTIVE
dify.example.com        you@company.com (Your Name)  *
dify.internal.acme.com  you@acme.com (Your Name)
-o json： 
{
  "contexts": [
    {
      "host": "dify.example.com",
      "account": "you@company.com",
      "name": "Your Name",
      "active": true
    },
    {
      "host": "dify.internal.acme.com",
      "account": "you@acme.com",
      "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 dify.example.com

​
退出码

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

​
切换当前主机

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

​
标志

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

​
示例

在当前主机上切换到另一个账户： 
difyctl use account --email teammate-bot@company.com

​
输出

切换成功后，会确认新的当前账户： 
✓ Active account on dify.example.com is now teammate-bot@company.com
如果某邮箱未存储在当前主机上，则会以用法错误失败，并列出已知的账户。如果某账户已存储的 token 不复存在（已撤销，或被 会话撤销 清除），则会以未登录错误失败，并提示你重新登录。

​
退出码

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

​
列出活跃会话

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

​
标志

标志类型默认值说明
--jsonbooleanfalse输出 JSON，而非表格。
--page <n>integer1页码。
--limit <n>integer20每页条数，范围 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 会先要求你确认（Revoke <N> session(s)? [y/N]）；传入 -y/--yes 可跳过提示。在终端外（脚本或管道），它会直接撤销，不再提示。 如果你撤销的是当前登录所使用的会话，difyctl 还会清除该上下文的本地凭据：你在本机上将被退出登录。

​
参数

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

​
标志

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

​
示例

按标签撤销单个会话： 
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）
完整的退出码方案，详见 输出格式与退出码。
最后修改于 2026年6月25日