用 difyctl 在终端驱动 Dify 应用：设备流登录、run app 与 Skills 接入编码智能体实操

Dify 应用建好之后的运行入口，长期只有两个：网页控制台点点点，或者自己包一层 API 调用。前者没法进脚本，后者每次集成都要重写胶水代码。Dify 1.15.0 把这块补齐了：官方命令行工具 difyctl 随版本发布，一套命令通吃 Cloud、Community、Enterprise 三种形态——登录一次，工作区里的每个应用、工作流、聊天流、Agent 都变成终端可调用的对象，脚本能跑、CI 能跑、编码智能体也能直接调。

本篇按 docs.dify.ai 的 CLI Reference 走通主线：设备流登录、摸清工作区与应用、run app 跑通、结构化输出接管道、skills install 把它交给编码智能体、最后是排错与运维面。读完你要能把「在 Dify 上点一下运行」这件事，变成任何自动化系统里的一行命令。

前置准备：一个 Dify 1.15.0 及以上版本的实例（Enterprise 需 EE 3.11.0+，社区版记得先完成该版本的数据库迁移再升级 CLI）；本地装有终端环境即可，无需额外依赖。

安装方式以 docs.dify.ai 的 CLI quickstart 页为准（Windows 用户可从官方 release artifact 直接下载 .exe），不要照搬第三方博客的安装命令——difyctl 名字太新，仿冒与过时教程已经在搜索结果里出现。版本不符时会报客户端与服务器兼容性问题，先跑 difyctl version 看两侧版本。

Step 1：设备流登录：不碰 API Key 也能接入

1 设备流登录：不碰 API Key 也能接入

difyctl 走 OAuth 设备流登录，全程不用手工创建和粘贴 API Key：

# 发起登录：终端给你一个设备码，浏览器里确认
difyctl auth login
# 输出类似：打开浏览器，输入设备码 XXXX-XXXX

# 确认身份与已存登录
difyctl auth whoami
difyctl auth list     # 列出全部已登录的 host + 账号组合

凭证默认进操作系统钥匙串（没有钥匙串的环境回退到密封文件），配置文件权限是 0600、目录 0700——这个安全基线别破坏。一台机器可以同时登录多个 Dify 主机（比如公司私有化部署 + 个人 Cloud），auth list 能看到全部组合，随用随切。

把日常常用的那个 host 用 use host 固定下来，之后所有命令都默认指向它，省得每条命令都带地址参数。多工作区的人再用 use workspace 切换。

Step 2：摸清工作区：run 之前先 describe

2 摸清工作区：run 之前先 describe

跑应用之前，先看清它要什么输入——这一步是脚本稳定性的根基：

# 看工作区里有哪些应用
difyctl get app

# 看单个应用的元数据与输入参数
difyctl describe app app-1

# 工作区清单
difyctl get workspace

describe app 的输出会列出应用类型（chatflow / workflow / agent / chatbot）与它声明的输入参数。chat 应用通常只要一个 query 字符串；workflow 应用的输入是键值对集合，名字和类型以 describe 的结果为准——直接抄进下一步的 --input 参数，不要凭记忆猜字段名。

Agent 类应用（agent-chat 模式或带 is_agent 标记）不接受阻塞式调用：Dify 后端会直接拒绝这类请求，必须走流式。这是后端行为不是 CLI 限制，遇到「Agent 应用 run 不动」先检查是不是用了阻塞模式。

Step 3：run app：从手工跑通到带参运行

3 run app：从手工跑通到带参运行

最短路径先跑通，再逐步加参数与格式：

# 阻塞式运行（简单对话/短任务）
difyctl run app app-1 "hello"

# JSON 输出 + jq 取答案
difyctl run app app-1 "hello" -o json | jq .answer

# workflow 应用带输入参数
difyctl run app app-1 --input name=world --input topic=cats

# 预计超过约 30 秒的长任务，改流式
difyctl run app app-1 "长任务描述" --stream

阻塞模式适合快速验证与短任务；自动化场景里，-o json 加 jq 是标准姿势——输出结构稳定，管道下游不用解析人类可读表格。长任务记得 --stream，否则命令会一直挂到超时。

落地场景上，官方博客给的画像很清晰：销售与客服让智能体拉客户记录、起草跟进、触发审批；市场与运营把乱表格变成干净指标；法务财务在受限权限里读敏感文档、标记异常、路由人工；研发与 CI 则把评测工作流的触发挂进构建流水线。共同点是——这些动作的目标应用都已经在 Dify 里建好了，difyctl 只是给它们补上了「被自动化系统调用」的那扇门，应用的逻辑零改动，接入成本就是学几条命令。

把 run 命令连同一个 describe 输出一起存进仓库的 scripts/ 目录，就是给团队的可执行文档：新人跑之前先看 describe 知道参数，再照抄 run 命令，上手成本趋近于零。

Step 4：结构化输出与重试语义：接进脚本与 CI

4 结构化输出与重试语义：接进脚本与 CI

difyctl 的机器接口设计得相当克制，接自动化前把三条语义记住：

# 输出格式一览
#   （无参数）人类表格 | -o wide 不截断 | -o json 稳定结构
#   -o yaml | -o name 仅 ID（可直接喂 xargs）| -o text 描述体

# 退出码确定性：0 成功，非 0 失败
#   -o json 模式下错误以 JSON 信封打到 stderr

# HTTP 重试语义（幂等设计）
#   GET / PUT / DELETE  -> 瞬态失败自动重试 3 次指数退避
#   POST / PATCH        -> 绝不重试（有副作用）
#   临时关闭：--http-retry 0  或环境变量 DIFYCTL_HTTP_RETRY

# CI 里的典型用法：失败即退出，成功则解析结果
difyctl run app app-1 "$PROMPT" -o json > result.json || exit 1
jq -r .answer result.json

POST 与 PATCH 绝不重试这条要特别记住：它意味着你的触发类调用（比如提交一次工作流运行）在网络抖动时不会重复执行——这通常是你要的正确行为；如果你的场景就是想重试，自己在外层做幂等键与去重，别指望 CLI 替你兜底。

help 系统本身就是给脚本与智能体准备的：difyctl help -o json --compact 输出全部命令的三字段清单（路径、一句话、read/write/destructive 效果标记），单命令 help -o json 给出完整参数描述——写自动化前先让脚本读这两样，比硬编码稳。

Step 5：skills install：把 Dify 交给编码智能体

5 skills install：把 Dify 交给编码智能体

这是 difyctl 最有想象力的一步：官方提供了一条命令，把 difyctl 的使用说明作为技能装进检测到的编码智能体（Claude Code、Codex、Cursor 等）：

# 安装 difyctl 技能到检测到的编码智能体
difyctl skills install

# 内置长文档主题（帮智能体理解用法）
difyctl help account      # 账号与登录引导
difyctl help environment  # DIFY_* 环境变量说明
difyctl help agent        # 智能体驱动 difyctl 的跨命令契约

装完技能后在 Claude Code 里直接说人话：「帮我列出工作区里的应用，然后跑一下 app-1 问问它支持什么输入」——编码智能体会按 agent 契约先读命令地图、再读单命令描述、然后执行。这比给它一段裸 API 文档靠谱得多：命令地图带效果标记，智能体能自己判断哪条命令是只读、哪条有副作用。

让编码智能体代跑 difyctl 时，记得它会拿到你当前登录身份的全部权限。给敏感工作区（含生产数据的应用）操作前，要么单独登一个权限受限的账号，要么对智能体的执行保持人工确认——别把生产环境的执行权完全交给自动循环。

Step 6：运维面：会话、导入导出与恢复

6 运维面：会话、导入导出与恢复

日常运维还剩四件事，都收敛在命令面里：

# 会话安全：查看与吊销登录设备
difyctl auth devices list
difyctl auth devices revoke

# DSL 导入导出（应用配置迁移与备份）
difyctl export studio-app app-1 -o app-1-dsl.yaml
difyctl import studio-app app-1-dsl.yaml

# 恢复被人工输入节点暂停的工作流
difyctl resume app app-1

# 环境变量与版本
difyctl env list
difyctl version

auth devices 是安全兜底：设备丢了、token 疑似泄露，一条 revoke 吊销。export 与 import 管应用配置的迁移与备份——改大版本配置前先 export 一份 DSL，改坏了能回。resume app 处理的是带人工审核节点的工作流：流程停在等输入的位置，你用命令把审核结果喂回去，流程继续走，不用回网页控制台点按钮。

配置目录默认在 ~/.config/difyctl/（Windows 为 APPDATA 下的 difyctl 目录），可用 DIFY_CONFIG_DIR 覆盖——CI 容器里给每条流水线独立配置目录，是隔离多套凭证的干净做法，也顺便规避了并发构建互相覆盖登录态的问题。

预期效果自查：difyctl auth whoami 报出你的身份；describe app 能列出目标应用的输入参数；一条 run app 命令在终端拿到答案（或 CI 里拿到结构化 JSON）；skills install 之后编码智能体能听懂「跑一下我的 Dify 应用」这类指令。四条全过，你的 Dify 就正式接入终端与自动化体系了。

常见问题 FAQ

和直接调 Dify API 比有什么区别？difyctl 帮你处理了认证（设备流 + 钥匙串）、重试语义、输出格式与错误信封，还带机器可读的命令地图——这些用裸 API 都得自己写。API 适合深度集成进你的服务；difyctl 适合脚本、CI、编码智能体这类「调用方本身是个终端环境」的场景，两者不冲突。

社区版能用吗？要升级吗？能。difyctl 覆盖 Cloud、Community、Enterprise 三种形态，前提是服务端升到 1.15.0+（社区版该版本带数据库迁移，先迁移再装 CLI）。老版本服务端配新 CLI 会在 version 检查处报兼容问题。

token 存在哪里，安全吗？默认进操作系统钥匙串，无钥匙串环境回退到密封文件；配置文件 0600、目录 0700。共享主机上多人使用时，用 DIFY_CONFIG_DIR 给每人独立配置目录，避免凭证混放。