Get Started - Dify Docs

On Dify Cloud, follow the Cloud CLI docs instead.
If you used difyctl before your server moved to Dify 1.18.0, its commands and sign-in have changed, so start from Upgrade Across Dify 1.18.0.

To have your coding agent do this setup for you, point it to this page. You’ll still approve its sign-in in your browser.

Before You Start

Your Dify server runs version 1.18.0 or later. If it runs 1.17.x or earlier, use the docs for that Dify version.
OPENAPI_ENABLED and ENABLE_OAUTH_BEARER are set to true on your server.

Install

brew install dify gets you Dify’s plugin development CLI, not difyctl.

Run the Installer

macOS / Linux
Windows
Manual Download

Supported on x64 and arm64.

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

This installs the build from the latest Dify release. If your server runs an older one, set DIFY_VERSION to its version:

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

The script checks the download’s checksum and installs to ~/.local/bin/difyctl.

Supported platform: x64.

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

This installs the build from the latest Dify release. If your server runs an older one, first set DIFY_VERSION to its version:

# applies for the rest of this PowerShell session
$env:DIFY_VERSION = "1.18.0"
irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install.ps1 | iex

The script checks the download’s checksum and installs to %LOCALAPPDATA%\difyctl\bin\difyctl.exe.

From Dify’s GitHub Releases, pick the release that matches your server’s Dify version and download two assets:
- The binary for your platform (difyctl-v<version>-<os>-<arch>)
- The checksum manifest (difyctl-v<version>-checksums.txt)
Compute the binary’s SHA-256 hash and compare it with the matching entry in the checksums file. If the values differ, the download is corrupted or was tampered with; delete it and download again.
shasum -a 256 difyctl-v<version>-darwin-<arch>
sha256sum difyctl-v<version>-linux-<arch>
Get-FileHash difyctl-v<version>-windows-x64.exe

Put the binary on your PATH:

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

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"

To install into a different folder or change other install settings, see Configuration.

Verify the Install

difyctl version

If you get command not found, the install directory isn’t on your PATH. Add it:

# add to ~/.zshrc or ~/.bashrc; running it inline only lasts until the session ends
export PATH="$HOME/.local/bin:$PATH"

[Environment]::SetEnvironmentVariable('PATH', "$env:LOCALAPPDATA\difyctl\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')
# then open a new terminal

difyctl signs in through your browser. A sign-in lasts 14 days by default (adjustable with OAUTH_TTL_DAYS).

Start the Sign-In

Pass the address you open Dify at in your browser:

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

If no browser opens, for example over SSH, open the URL difyctl prints on any device.For a local server on http:// or with a self-signed certificate, add --insecure. It applies to every later command until you sign in again without it, so keep it to local development.

Approve in Your Browser

On the Authorize difyctl page, enter the code and click Continue. The code expires after 15 minutes.When the page shows your account, check it before you click Authorize. difyctl and your coding agent will act as this account and can do anything it can. If it’s not the account you want, click Cancel, sign in to Dify as the right one, and start the sign-in again.

To sign in again or sign out later, see Manage Your Sign-In. If sign-in fails, see Troubleshooting.

List Your Apps

Check that difyctl works by listing the apps in your workspace:

difyctl get console_app

Only apps with Service API access turned on are listed.

Set Up Your Coding Agent

The difyctl skill teaches your coding agent to use difyctl. Install it into the skills folder of each coding agent you use:

# Claude Code
difyctl install skills ~/.claude/skills

# Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and most other agents
difyctl install skills ~/.agents/skills

For any other agent, look up its skills folder in its documentation. If your agent doesn’t find the skill, restart it.

Keep Control of Commands and Keys

Keep your agent’s own approval for shell commands turned on: difyctl runs each command without asking first. The skill tells your agent to check with you before it deletes anything, installs an integration, or publishes an app. Whether it does depends on the AI model your agent runs on.

To let your agent look around without asking, allow difyctl get and difyctl describe, which only read from your server.

Anything you type into the chat, such as a model provider’s API key, passes through your agent’s model. To keep a key out of it, add the key in Dify yourself before the agent needs it, or tell the agent you’ll add it yourself when it asks.

Find Commands Yourself

Describe the job to help in a few words, and it lists the commands that match. For example, to find the command that publishes an app:

difyctl help publish app

To browse instead, run difyctl help. For how to pass values to a command and follow the hints in its results, see Find and Run Commands.

Next Steps

Ask your agent for any of these, or do them yourself:

Troubleshooting

Message	What to do
`only https:// hosts are accepted`	Use an `https://` address, or add `--insecure` for a local `http://` server.
`network error calling POST <server>/openapi/v1/oauth/device/code`	Check the server address and your network. A certificate `difyctl` can’t verify fails the same way. For a local server with a self-signed certificate, add `--insecure`.
`this Dify host does not implement the OAuth device flow`	Check the server address. If it’s right, set `OPENAPI_ENABLED` and `ENABLE_OAUTH_BEARER` to `true` on your server.
In the browser: `Something went wrong on our side. Try again in a moment.`	Set `ENABLE_OAUTH_BEARER` to `true` on your server.
`authorization denied`	Someone clicked Cancel in the browser. Run `login` again.
`code expired before authorization`	The code wasn’t approved within 15 minutes. Run `login` again.
`OS keychain is unreachable`	Sign in again with `--no-keyring` to keep the token in a file.

​Before You Start

​Install

​Sign In

​List Your Apps

​Set Up Your Coding Agent

​Keep Control of Commands and Keys

​Find Commands Yourself

​Next Steps

​Troubleshooting

Before You Start

Install

Sign In

List Your Apps

Set Up Your Coding Agent

Keep Control of Commands and Keys

Find Commands Yourself

Next Steps

Troubleshooting