#11. difyctl 命令行工具

#功能介绍

difyctl 是 Dify 官方在 v1.15.0 中推出的命令行客户端，让你无需打开网页控制台，直接在终端里运行应用和工作流。它把 Dify 的能力接到了命令行上，因此个人脚本、自动化任务和 CI/CD 流水线都可以直接调用 Dify 工作流，把 AI 能力嵌进已有的自动化链路中。

difyctl 是一个不依赖任何运行时的独立二进制程序，安装脚本会自动识别你的操作系统与架构、从 Dify 的 GitHub Releases 下载匹配的版本、校验哈希后放到位。它支持 macOS、Linux（x64 与 arm64）以及 Windows（x64）。

注意：difyctl 要求所连接的 Dify 服务为 v1.15.0 或更高版本。

#安装方式

在 macOS / Linux 上，执行一行安装命令即可（脚本会安装到 ~/.local/bin/difyctl，并提示该目录是否已在 PATH 中）：

curl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-cli.sh | sh

在 Windows（PowerShell）上：

irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install.ps1 | iex

安装完成后，验证是否可用：

difyctl version

若能看到包含版本号和平台信息的 Client: 段落，即表示安装成功。若提示 command not found，说明安装目录尚未加入 PATH，把 ~/.local/bin（Windows 为 %LOCALAPPDATA%\difyctl\bin）追加进去即可。

提示：当你的服务端不是最新版本时，可在安装命令前设置 DIFY_VERSION 环境变量，让 difyctl 的版本与服务端对齐，例如：curl -fsSL .../install-cli.sh | DIFY_VERSION=1.15.0 sh。

#使用方法

difyctl 采用「先登录、再运行」的流程：

1. 登录：首次使用先执行 difyctl auth login，按提示完成身份认证。difyctl 采用无访问令牌（access token）的授权方式，安装与登录都无需手动粘贴密钥。
2. 运行应用或工作流：登录后即可从终端直接触发已发布的应用或工作流，把输入参数传给它并取回结果。
3. 传入作用域环境变量：运行工具时可传入受限作用域的环境变量，便于在不同环境（开发 / 生产）间切换配置；difyctl 与 /openapi/v1 API 都提供了更清晰一致的错误提示，包括友好的限流处理。
4. 退出登录：不再使用时可执行 difyctl auth logout 注销。

#使用技巧

• difyctl 最适合的场景是自动化：把 Dify 工作流嵌进 CI/CD 流水线、定时脚本或个人 Agent 中，让它们在无人值守时也能调用 Dify。
• 更新 difyctl 只需重新执行一次安装脚本，它会原地替换二进制文件；要切换到特定 Dify 版本，设置 DIFY_VERSION 后重装即可。
• 团队协作时，建议让 difyctl 版本与服务端 Dify 版本保持一致，避免因版本差异导致的接口不兼容。
• 二进制文件通过公开 Release 分发并带哈希校验，下载后可自行比对 difyctl-v<version>-checksums.txt 中的 SHA-256，确认文件未被篡改。

#示例

示例一：在 CI 流水线中调用工作流

场景：代码合并后，自动触发一个"生成发布说明"的 Dify 工作流
配置：在 CI 环境中安装 difyctl，通过环境变量注入认证信息，登录后运行目标工作流
效果：每次合并自动产出发布说明，无需人工打开控制台

示例二：本地脚本批量运行

场景：本地有一批待处理的输入，想逐条跑同一个文本生成应用
配置：difyctl auth login 登录后，用脚本循环调用该应用并收集输出
效果：把网页端的手动操作变成可复用、可批处理的命令行任务