帮助 - Dify Docs

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

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

获取帮助

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

difyctl
difyctl help
difyctl --help
difyctl -h

该概览列出每个命令及其简介、三个入门示例、全局标志，以及指南主题。若想查看同样的清单并附带指向本参考文档的链接，参见命令索引。

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

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

difyctl run app --help
difyctl help run app

单个命令的帮助会显示该命令的描述、用法行、参数、带默认值的标志以及示例。指定命令组而非具体命令，可列出该组的子命令：

difyctl auth --help

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 实际读取哪些变量，参见环境变量。

机器可读帮助

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

difyctl help -o json

该文档包含四个顶层键：bin、contract（退出码、输出格式、错误输出的结构以及跨命令规则）、commands（每个命令一个描述符），以及 topics（按名称列出的可用指南主题，每个主题的正文通过 difyctl help <topic> 读取）。 JSON 形式的单个命令帮助仅返回该命令的描述符：

difyctl auth whoami --help -o json

{
  "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`	未知的帮助主题或命令名称

完整方案参见输出格式与退出码。

​获取帮助

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

​指南主题

​机器可读帮助

​退出码

获取帮助

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

指南主题

机器可读帮助

退出码