Get Started - Dify Docs

If you used difyctl before Dify 1.18.0, your old build stops working once your server runs 1.18.0 or later. The 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

On Dify Cloud, you’re ready to install. On a self-hosted server, check that:

It runs Dify 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.

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 self-hosted server isn’t on the latest release, 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 self-hosted server isn’t on the latest release, 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.

On Dify’s GitHub Releases, pick the release that matches your server’s Dify version. Download two assets from it:
- 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

Start the Sign-In

Pass the address you open Dify at in your browser (https://cloud.dify.ai on Dify Cloud):

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 difyctl printed and click Continue. The code expires after 15 minutes.When the page shows your account and workspace, check both 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.difyctl will work in the workspace the page shows. To use a different one, switch difyctl to it once you’ve signed in.

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 the workspace you signed in to:

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 installs an integration, publishes an app, or runs a command that help labels destructive or shows with no label. Whether it does depends on the AI model your agent runs on.

To let your agent look around without asking, allow the commands that only read from your server: difyctl get, difyctl describe, and difyctl knowledge_fs Cloud.

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. On Dify Cloud, use `https://cloud.dify.ai`. On a self-hosted server, if the address is right, make sure `OPENAPI_ENABLED` is set to `true`.
In the browser: `Something went wrong on our side. Try again in a moment.`	On a self-hosted server, make sure `ENABLE_OAUTH_BEARER` is set to `true`.
`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