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

# Get Started

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

> [!NOTE]
>
> * On Dify Cloud, follow the [Cloud CLI docs](/en/cloud/cli/install.md) 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](/en/cli/upgrade-across-1-18.md).

> [!TIP]
>
> 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](https://github.com/langgenius/dify-docs/branches/all?query=release%2F).
* [`OPENAPI_ENABLED` and `ENABLE_OAUTH_BEARER`](/en/self-host/deploy/configuration/environments#dify-cli-and-programmatic-api) are set to `true` on your server.

## Install

> [!NOTE]
>
> `brew install dify` gets you [Dify's plugin development CLI](/en/develop-plugin/getting-started/cli.md), not `difyctl`.

**1. Run the Installer**

**macOS / Linux**

Supported on x64 and arm64.

```bash theme={null}
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:

```bash theme={null}
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.

```powershell theme={null}
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:

```powershell theme={null}
# 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. From [Dify's GitHub Releases](https://github.com/langgenius/dify/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`)

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.

   ```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. Put the binary on your `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]
>
> To install into a different folder or change other install settings, see [Configuration](/en/cli/reference/configuration.md).

**2. Verify the Install**

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

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

```bash macOS / Linux theme={null}
# add to ~/.zshrc or ~/.bashrc; running it inline only lasts until the session ends
export PATH="$HOME/.local/bin:$PATH"
```

```powershell Windows theme={null}
[Environment]::SetEnvironmentVariable('PATH', "$env:LOCALAPPDATA\difyctl\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')
# then open a new terminal
```

## Sign In

`difyctl` signs in through your browser. A sign-in lasts 14 days by default (adjustable with [`OAUTH_TTL_DAYS`](/en/self-host/deploy/configuration/environments#dify-cli-and-programmatic-api)).

**1. Start the Sign-In**

Pass the address you open Dify at in your browser:

```bash theme={null}
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 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](/en/cli/manage-sign-in.md). If sign-in fails, see [Troubleshooting](#troubleshooting).

## List Your Apps

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

```bash theme={null}
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:

```bash theme={null}
# 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.

> [!TIP]
>
> 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:

```bash theme={null}
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](/en/cli/find-and-run-commands.md).

## Next Steps

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

* [Build, change, and publish Workflow and Chatflow apps](/en/cli/build-apps.md)
* [Run your apps](/en/cli/run-apps.md)
* [Create or update apps from DSL files](/en/cli/create-and-update-apps-from-dsl-files.md)
* [Use `difyctl` in CI and automation](/en/cli/scripts-and-ci)

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


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