> ## Documentation index
> Fetch the complete documentation index at: https://dify-docs.docs7.io/llms.txt
> Ask it with GET https://dify-docs.docs7.io/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.

# 快速开始

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

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

<Info>
  如果在 Dify 1.18.0 之前就用过 `difyctl`，服务器升级到 1.18.0 或更高版本后，旧版本将无法使用。`difyctl` 的命令和登录方式都已有变化，先从 [Dify 1.18.0 升级指南](/zh/cli/upgrade-across-1-18) 开始。
</Info>

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

## 开始之前

使用 Dify Cloud 时，可直接开始安装。

使用自部署的服务器时，先确认：

- 服务器为 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`。

## 安装

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

<Steps>
  <Step title="运行安装程序">
    <Tabs>
      <Tab title="macOS / Linux">

        支持 x64 和 arm64 架构。

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

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

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

        脚本会核对下载文件的校验和，再安装到 `~/.local/bin/difyctl`。
      </Tab>
      <Tab title="Windows">

        支持的平台：x64。

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

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

        ```powershell
        # 在当前 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`。

      </Tab>
      <Tab title="手动下载">

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

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

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

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

            <CodeGroup>

            ```bash macOS
            shasum -a 256 difyctl-v<version>-darwin-<arch>
            ```

            ```bash Linux
            sha256sum difyctl-v<version>-linux-<arch>
            ```

            ```powershell Windows
            Get-FileHash difyctl-v<version>-windows-x64.exe
            ```

            </CodeGroup>

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

            <CodeGroup>

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

            ```powershell Windows
            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"
            ```

            </CodeGroup>
      </Tab>
    </Tabs>

    <Tip>
    如需安装到其他目录或修改其他安装设置，详见 [配置](/zh/cli/reference/configuration)。
    </Tip>
  </Step>
  <Step title="验证安装">

    ```bash
    difyctl version
    ```

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

    <CodeGroup>

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

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

    </CodeGroup>
  </Step>
</Steps>

## 登录

<Steps>
  <Step title="发起登录">
    传入你在浏览器中打开 Dify 时用的地址（Dify Cloud 为 `https://cloud.dify.ai`）：

    ```bash
    difyctl login --server https://dify.example.com
    ```

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

    本地服务器使用 `http://` 或自签名证书时，加上 `--insecure`。此后的命令都会沿用这个选项，直到不带它重新登录为止，所以只在本地开发时使用。
  </Step>
  <Step title="在浏览器中批准">
    在 **授权 difyctl** 页面输入 `difyctl` 打印出的验证码，点击 **继续**。验证码 15 分钟后过期。

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

    `difyctl` 将使用页面上显示的工作空间。要换成其他工作空间，登录后 [切换 `difyctl` 的工作空间](/zh/cli/manage-sign-in#switch-your-workspace) 即可。
  </Step>
</Steps>

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

## 列出应用

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

```bash
difyctl get console_app
```

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

## 配置编码 Agent

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

```bash
# 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` 和 `difyctl knowledge_fs` <Badge color="blue" size="sm">Cloud</Badge>。
</Tip>

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

## 自行查找命令

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

```bash
difyctl help publish app
```

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

## 后续步骤

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

- [构建、修改和发布 Workflow 与 Chatflow 应用](/zh/cli/build-apps)
- [运行应用](/zh/cli/run-apps)
- [通过 DSL 文件创建或更新应用](/zh/cli/create-and-update-apps-from-dsl-files)
- [在 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` | 检查服务器地址和网络。<br/><br/>`difyctl` 无法校验服务器证书时，也会报这个错误。本地服务器使用自签名证书时，加上 `--insecure`。 |
| `this Dify host does not implement the OAuth device flow` | 检查服务器地址。使用 Dify Cloud 时，地址应为 `https://cloud.dify.ai`。<br/><br/>使用自部署的服务器时，如果地址无误，确认 `OPENAPI_ENABLED` 已设为 `true`。 |
| 浏览器中：`我们这边出现了问题，请稍后重试。` | 使用自部署的服务器时，确认 `ENABLE_OAUTH_BEARER` 已设为 `true`。 |
| `authorization denied` | 有人在浏览器中点击了 **取消**。重新运行 `login`。 |
| `code expired before authorization` | 验证码在 15 分钟内未获批准。重新运行 `login`。 |
| `OS keychain is unreachable` | 加上 `--no-keyring` 重新登录，把令牌保存到文件中。 |