> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-docs-new-agent-experience.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证与上下文

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

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/cli/reference/auth-and-contexts)。

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

每项任务对应一条命令：

* [`difyctl auth login`](#登录) 登录到某个主机
* [`auth whoami`](#查看当前身份) 打印当前登录的身份
* [`auth list`](#列出已保存的上下文) 列出已保存的上下文
* [`auth logout`](#退出登录) 退出当前主机的登录
* [`use host`](#切换当前主机) / [`use account`](#切换当前账户) 切换当前上下文
* [`auth devices list`](#列出活跃会话) 列出活跃会话
* [`auth devices revoke`](#撤销会话) 撤销你不认识的会话

分步登录的完整说明，详见 [认证](/zh/cli/authenticate)。

## 登录

```text theme={null}
difyctl auth login [flags]
```

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

### 标志

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

### 示例

登录到你的 Dify 主机：

```bash theme={null}
difyctl auth login --host https://cloud.dify.ai
```

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

```bash theme={null}
difyctl auth login --no-browser
```

### 输出

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

```text theme={null}
! Copy this one-time code: WDJP-XKLM
  Open: https://cloud.dify.ai/device
```

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

```text theme={null}
✓ 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` | 服务器没有设备流程登录端点（`unsupported_endpoint`）               |
| `7` | 触发限流（HTTP 429）                                      |

完整的退出码方案，详见 [输出格式与退出码](/zh/cli/reference/output-formats-and-exit-codes)。

## 查看当前身份

```text theme={null}
difyctl auth whoami [flags]
```

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

### 标志

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

### 示例

```bash theme={null}
difyctl auth whoami
```

用于脚本：

```bash theme={null}
difyctl auth whoami --json
```

### 输出

```text theme={null}
<your-email> (<your-name>)
```

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

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

### 退出码

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

## 列出已保存的上下文

```text theme={null}
difyctl auth list [flags]
```

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

### 标志

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

### 示例

```bash theme={null}
difyctl auth list
```

### 输出

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

默认表格：

```text theme={null}
HOST                    ACCOUNT                      ACTIVE
cloud.dify.ai           you@company.com (Your Name)  *
dify.internal.acme.com  you@acme.com (Your Name)
```

`-o json`：

```json theme={null}
{
  "contexts": [
    {
      "host": "cloud.dify.ai",
      "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` 取值 |

## 退出登录

```text theme={null}
difyctl auth logout
```

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

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

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

### 标志

无。

### 示例

```bash theme={null}
difyctl auth logout
```

### 输出

```text theme={null}
✓ Logged out of cloud.dify.ai
```

### 退出码

| 退出码 | 含义                   |
| :-- | :------------------- |
| `0` | 已退出登录                |
| `4` | 未登录（`not_logged_in`） |

## 切换当前主机

```text theme={null}
difyctl use host [flags]
```

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

### 标志

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

### 示例

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

```bash theme={null}
difyctl use host --domain dify.internal.acme.com
```

### 输出

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

```text theme={null}
✓ Active host is now dify.internal.acme.com
```

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

### 退出码

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

## 切换当前账户

```text theme={null}
difyctl use account [flags]
```

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

### 标志

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

### 示例

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

```bash theme={null}
difyctl use account --email teammate-bot@company.com
```

### 输出

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

```text theme={null}
✓ Active account on cloud.dify.ai is now teammate-bot@company.com
```

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

### 退出码

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

## 列出活跃会话

```text theme={null}
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`](/zh/cli/reference/environment-variables)。 |

### 示例

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

```bash theme={null}
difyctl auth devices list
```

### 输出

```text theme={null}
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）      |

## 撤销会话

```text theme={null}
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 | 跳过确认提示。        |

### 示例

按标签撤销单个会话：

```bash theme={null}
difyctl auth devices revoke "difyctl on build-runner-3"
```

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

```bash theme={null}
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）                              |

完整的退出码方案，详见 [输出格式与退出码](/zh/cli/reference/output-formats-and-exit-codes)。