> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 帮助

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

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

## 获取帮助

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

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

该概览列出每个命令及其简介、三个入门示例、[全局标志](/zh/3.13.x/develop/cli/reference/global-flags)，以及 [指南主题](#指南主题)。若想查看同样的清单并附带指向本参考文档的链接，参见 [命令索引](/zh/3.13.x/develop/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 所遵循的跨命令约定。 |
| `external` | 面向外部 SSO 用户的登录帮助。 |

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

## 机器可读帮助

每个帮助层面都接受 `-o json` 和 `-o yaml`。驱动 `difyctl` 的编码 Agent 主要用到其中两种：先用 [精简命令清单](#精简命令清单) 选定命令，再读取该命令的 [描述符](#单个命令的描述符) 获取参数和标志。[完整文档](#完整文档) 则把跨命令约定和主题列表一并给出。

### 精简命令清单

在顶层帮助上加 `--compact`，每个命令只输出三个字段：`command`（命令路径）、`description`（一句话描述）和 `effect` 标签（`read`、`write` 或 `destructive`）。不含其他内容，因此整份清单足够小，选定命令前可一次读完：

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

清单的开头几项：

```json theme={null}
{
  "commands": [
    {
      "command": "auth devices list",
      "description": "List active sessions for the current bearer",
      "effect": "read"
    },
    {
      "command": "auth devices revoke",
      "description": "Revoke one or all session devices",
      "effect": "destructive"
    },
    {
      "command": "auth list",
      "description": "List all authenticated contexts (host + account pairs)",
      "effect": "read"
    },
    {
      "command": "auth login",
      "description": "Sign in to Dify via OAuth device flow",
      "effect": "write"
    }
  ]
}
```

`--compact` 只适用于顶层帮助，且必须搭配 `-o json` 或 `-o yaml`。用在单个命令的帮助上，或未指定结构化格式时，会作为用法错误失败，退出码为 `2`。

### 单个命令的描述符

选定命令后，其描述符会补齐清单中省略的全部信息。两种单命令帮助写法都会返回它：

```bash theme={null}
difyctl help auth whoami -o json
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` 标签，以及在有的情况下提供的 `agentGuide` 字符串（面向 Agent 的命令专属指引）。

### 完整文档

不加 `--compact` 时，顶层帮助会在一份文档中输出完整的命令全貌：

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

该文档包含四个顶层键：

* `bin`：可执行文件名，即 `difyctl`
* `contract`：退出码、输出格式、错误输出的结构以及跨命令规则
* `commands`：每个命令一个完整描述符
* `topics`：各指南主题的名称和一句话摘要，正文通过 `difyctl help <topic>` 读取

## 退出码

| 退出码 | 含义 |
| :- | :- |
| `0` | 已打印帮助 |
| `1` | 未知的帮助主题或命令名称 |
| `2` | 在顶层 `-o json` 或 `-o yaml` 帮助之外使用 `--compact` |

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