Get Started

Install difyctl, sign in, set up your coding agent with the difyctl skill, and find the commands to run yourself

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.

1. Run the Installer

   macOS / Linux

   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.

   Windows

   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.

   Manual Download

   1. 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)

   2. 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.

      macOS

      shasum -a 256 difyctl-v<version>-darwin-<arch>
      

   3. Put the binary on your PATH:

      macOS / Linux

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

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

2. Verify the Install

   difyctl version
   

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

   macOS / Linux

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

Sign In

1. 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.

2. 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 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 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:

• Build, change, and publish Workflow and Chatflow apps
• Run your apps
• Create or update apps from DSL files
• Use difyctl in CI and automation

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.