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

# 帮助

> 在终端中获取帮助，包括各命令文档、指南主题以及机器可读的 JSON

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

`difyctl` 的帮助系统涵盖四个层面：[顶层概览](#获取帮助)、[单个命令或命令组的帮助](#查看单个命令或命令组的帮助)、[指南主题](#指南主题)，以及上述所有内容的 [机器可读形式](#机器可读帮助)。所有帮助内容均输出到 stdout，并以退出码 `0` 结束。

## 获取帮助

以下四种调用方式都会显示相同的顶层概览：

```bash theme={null}
difyctl
difyctl help
difyctl --help
difyctl -h
```

该概览列出每个命令及其简介、三个入门示例、[全局标志](/zh/cli/reference/global-flags)，以及 [指南主题](#指南主题)。若想查看同样的清单并附带指向本参考文档的链接，参见 [命令索引](/zh/cli/reference/command-index)。

## 查看单个命令或命令组的帮助

在任意命令后追加 `--help`，或在命令前加上 `help`：

```bash theme={null}
difyctl run app --help
difyctl help run app
```

单个命令的帮助会显示该命令的描述、用法行、参数、带默认值的标志以及示例。

指定命令组而非具体命令，可列出该组的子命令：

```bash theme={null}
difyctl auth --help
```

```text theme={null}
COMMANDS
  auth devices list    List active sessions for the current bearer
  auth devices revoke  Revoke one or all session devices
  auth list            List all authenticated contexts (host + account pairs)
  auth login           Sign in to Dify via OAuth device flow
  auth logout          Log out of the active Dify host
  auth whoami          Print the active subject's identity
```

若某个名称既不匹配命令、主题，也不匹配命令组，则会以 `unknown help topic: <name>` 报错，给出建议并返回退出码 `1`。

## 指南主题

长篇主题随 CLI 一同分发，通过 `difyctl help <topic>` 阅读：

| 主题            | 涵盖内容                              |
| :------------ | :-------------------------------- |
| `account`     | 上手引导。                             |
| `environment` | CLI 自身对 `DIFY_*` 环境变量的说明。         |
| `agent`       | 用于驱动 `difyctl` 的 Agent 所遵循的跨命令约定。 |

这些主题已内置于 CLI 中。要了解 `difyctl` 实际读取哪些变量，参见 [环境变量](/zh/cli/reference/environment-variables)。

## 机器可读帮助

每个帮助层面都接受 `-o json` 和 `-o yaml`。顶层形式会在一份文档中输出完整的命令全貌：

```bash theme={null}
difyctl help -o json
```

该文档包含四个顶层键：

* `bin`、`contract`：退出码、输出格式、错误输出的结构以及跨命令规则
* `commands`：每个命令一个描述符
* `topics`：按名称列出的可用指南主题，每个主题的正文通过 `difyctl help <topic>` 读取

JSON 形式的单个命令帮助仅返回该命令的描述符：

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

```json theme={null}
{
  "command": "auth whoami",
  "description": "Print the active subject's identity",
  "effect": "read",
  "args": [],
  "flags": [
    {
      "name": "json",
      "char": null,
      "type": "boolean",
      "default": false,
      "multiple": false,
      "options": null,
      "description": "emit JSON"
    }
  ],
  "examples": [
    "difyctl auth whoami",
    "difyctl auth whoami --json"
  ],
  "agentGuide": null
}
```

每个描述符都带有该命令的参数和标志（含类型与默认值）、一个 `effect` 标签（`read`、`write` 或 `destructive`），以及在有的情况下提供的 `agentGuide` 字符串。编码 Agent 正是通过这种方式发现 `difyctl`。

## 退出码

| 退出码 | 含义           |
| :-- | :----------- |
| `0` | 已打印帮助        |
| `1` | 未知的帮助主题或命令名称 |

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