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

# 快速开始

> 安装 difyctl 并登录，用 difyctl Skill 配置编码 Agent，再查找你自己要运行的命令

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

> [!NOTE]
>
> * 使用 Dify Cloud 时，改为参阅 [Cloud CLI 文档](/zh/cloud/cli/install.md)。
> * 如果在服务器升级到 Dify 1.18.0 之前就用过 `difyctl`，它的命令和登录方式都已有变化，先从 [Dify 1.18.0 升级指南](/zh/cli/upgrade-across-1-18.md) 开始。

> [!TIP]
>
> 要让编码 Agent 替你完成这些配置，把这个页面发给它即可。它的登录仍需你在浏览器中批准。

## 开始之前

* Dify 服务器为 1.18.0 或更高版本。如果是 1.17.x 或更早的版本，改为参阅 [该 Dify 版本对应的文档](https://github.com/langgenius/dify-docs/branches/all?query=release%2F)。
* 服务器已将 [`OPENAPI_ENABLED` 和 `ENABLE_OAUTH_BEARER`](/zh/self-host/deploy/configuration/environments#dify-cli-与编程-api) 设为 `true`。

## 安装

> [!NOTE]
>
> `brew install dify` 装上的是 [Dify 的插件开发 CLI](/zh/develop-plugin/getting-started/cli.md)，而非 `difyctl`。

**1. 运行安装程序**

**macOS / Linux**

支持 x64 和 arm64 架构。

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-cli.sh | sh
```

该命令会安装最新 Dify 版本附带的 difyctl。如果服务器运行的是更早的版本，将 `DIFY_VERSION` 设为服务器的版本号：

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-cli.sh | DIFY_VERSION=1.18.0 sh
```

脚本会核对下载文件的校验和，再安装到 `~/.local/bin/difyctl`。

**Windows**

支持的平台：x64。

```powershell theme={null}
irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install.ps1 | iex
```

该命令会安装最新 Dify 版本附带的 difyctl。如果服务器运行的是更早的版本，先将 `DIFY_VERSION` 设为服务器的版本号：

```powershell theme={null}
# 在当前 PowerShell 会话中持续有效
$env:DIFY_VERSION = "1.18.0"
irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install.ps1 | iex
```

脚本会核对下载文件的校验和，再安装到 `%LOCALAPPDATA%\difyctl\bin\difyctl.exe`。

**手动下载**

1. 在 [Dify 的 GitHub Releases](https://github.com/langgenius/dify/releases) 中找到与服务器 Dify 版本匹配的发布版本，下载以下两个资源文件：

   * 适用于你所用平台的二进制文件（`difyctl-v<version>-<os>-<arch>`）
   * 校验和清单（`difyctl-v<version>-checksums.txt`）

2. 计算二进制文件的 SHA-256 哈希值，并与校验和清单中对应的条目比对。

   如果两者不一致，说明下载的文件已损坏或遭到篡改，删除后重新下载。

   ```bash macOS theme={null}
   shasum -a 256 difyctl-v<version>-darwin-<arch>
   ```

   ```bash Linux theme={null}
   sha256sum difyctl-v<version>-linux-<arch>
   ```

   ```powershell Windows theme={null}
   Get-FileHash difyctl-v<version>-windows-x64.exe
   ```

3. 将二进制文件加入 `PATH`：

   ```bash macOS / Linux theme={null}
   chmod +x difyctl-v<version>-<os>-<arch>
   mkdir -p ~/.local/bin
   mv difyctl-v<version>-<os>-<arch> ~/.local/bin/difyctl
   ```

   ```powershell Windows theme={null}
   New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\difyctl\bin" | Out-Null
   Move-Item difyctl-v<version>-windows-x64.exe "$env:LOCALAPPDATA\difyctl\bin\difyctl.exe"
   ```

> [!TIP]
>
> 如需安装到其他目录或修改其他安装设置，详见 [配置](/zh/cli/reference/configuration.md)。

**2. 验证安装**

```bash theme={null}
difyctl version
```

如果提示 `command not found`，说明安装目录不在你的 `PATH` 中。按以下方式加入：

```bash macOS / Linux theme={null}
# 添加到 ~/.zshrc 或 ~/.bashrc；直接运行只在当前会话中有效
export PATH="$HOME/.local/bin:$PATH"
```

```powershell Windows theme={null}
[Environment]::SetEnvironmentVariable('PATH', "$env:LOCALAPPDATA\difyctl\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')
# 然后打开一个新的终端
```

## 登录

`difyctl` 借助浏览器完成登录。每次登录默认有效 14 天（可通过 [`OAUTH_TTL_DAYS`](/zh/self-host/deploy/configuration/environments#dify-cli-与编程-api) 调整）。

**1. 发起登录**

传入你在浏览器中打开 Dify 时用的地址：

```bash theme={null}
difyctl login --server https://dify.example.com
```

如果浏览器没有自动打开（例如通过 SSH 连接时），在任意设备上打开 `difyctl` 打印出的 URL。

本地服务器使用 `http://` 或自签名证书时，加上 `--insecure`。它会一直生效到你不带它重新登录为止，所以只在本地开发时使用。

**2. 在浏览器中批准**

在 **授权 difyctl** 页面输入验证码，点击 **继续**。验证码 15 分钟后过期。

页面显示你的账户时，先核对无误，再点击 **授权**。`difyctl` 和你的编码 Agent 都会以这个账户的身份操作，这个账户能做的事，它们都能做。如果账户不对，点击 **取消**，换成正确的账户登录 Dify，再重新发起登录。

之后要重新登录或退出登录，详见 [管理登录](/zh/cli/manage-sign-in.md)。如果登录失败，详见 [故障排查](#故障排查)。

## 列出应用

列出工作空间中的应用，确认 `difyctl` 能正常使用：

```bash theme={null}
difyctl get console_app
```

只有开启了服务 API 访问的应用才会列出。

## 配置编码 Agent

`difyctl` Skill 用来教编码 Agent 使用 `difyctl`。把它安装到你所用的每个编码 Agent 的 Skill 目录中：

```bash theme={null}
# Claude Code
difyctl install skills ~/.claude/skills

# Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode 及大多数其他 Agent
difyctl install skills ~/.agents/skills
```

其他 Agent 的 Skill 目录可在各自的文档中查到。如果 Agent 没有找到这个 Skill，重启它即可。

### 掌控命令和密钥

不要关闭 Agent 自带的 Shell 命令审批：`difyctl` 执行每条命令前都不会先征求同意。Skill 会要求 Agent 在删除任何内容、安装集成或发布应用之前先问过你。它是否照做，取决于 Agent 所用的 AI 模型。

> [!TIP]
>
> 想让 Agent 无需询问就能随意查看，可放行 `difyctl get` 和 `difyctl describe`，这两类命令只读取服务器上的数据。

你在对话中输入的任何内容，包括模型供应商的 API 密钥，都会经过 Agent 所用的模型。不想让密钥经过模型，可在 Agent 用到之前自己在 Dify 中添加好，或等 Agent 索要时，告诉它你会自己添加。

## 自行查找命令

在 `help` 后面用几个词描述要做的事，它会列出匹配的命令。例如，查找发布应用的命令：

```bash theme={null}
difyctl help publish app
```

如果想直接浏览，就运行 `difyctl help`。如何给命令传值、如何按结果中的提示继续操作，详见 [查找并运行命令](/zh/cli/find-and-run-commands.md)。

## 后续步骤

以下各项都可交给编码 Agent 来做，也可自己动手：

* [构建、修改和发布 Workflow 与 Chatflow 应用](/zh/cli/build-apps.md)
* [运行应用](/zh/cli/run-apps.md)
* [通过 DSL 文件创建或更新应用](/zh/cli/create-and-update-apps-from-dsl-files.md)
* [在 CI 和自动化中使用 `difyctl`](/zh/cli/scripts-and-ci)

## 故障排查

| 错误信息 | 处理方法 |
| :- | :- |
| `only https:// hosts are accepted` | 改用 `https://` 地址。本地服务器使用 `http://` 时，加上 `--insecure`。 |
| `network error calling POST <server>/openapi/v1/oauth/device/code` | 检查服务器地址和网络。 `difyctl` 无法校验服务器证书时，也会报这个错误。本地服务器使用自签名证书时，加上 `--insecure`。 |
| `this Dify host does not implement the OAuth device flow` | 检查服务器地址。如果地址无误，在服务器上将 `OPENAPI_ENABLED` 和 `ENABLE_OAUTH_BEARER` 设为 `true`。 |
| 浏览器中：`我们这边出现了问题，请稍后重试。` | 在服务器上将 `ENABLE_OAUTH_BEARER` 设为 `true`。 |
| `authorization denied` | 有人在浏览器中点击了 **取消**。重新运行 `login`。 |
| `code expired before authorization` | 验证码在 15 分钟内未获批准。重新运行 `login`。 |
| `OS keychain is unreachable` | 加上 `--no-keyring` 重新登录，把令牌保存到文件中。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.