> ## 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]
>
> 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](https://docs.dify.ai/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.

## Install

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

**1. Run the Installer**

> [tab] 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 self-hosted server isn't on the latest release, 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`.

> [tab] 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 self-hosted server isn't on the latest release, 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`.

> [tab] Manual Download
>
> 1. On [Dify's GitHub Releases](https://github.com/langgenius/dify/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.
>
>    ```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](https://docs.dify.ai/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

**1. Start the Sign-In**

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

```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 `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](https://docs.dify.ai/en/cli/manage-sign-in#switch-your-workspace) once you've signed in.

To sign in again or sign out later, see [Manage Your Sign-In](https://docs.dify.ai/en/cli/manage-sign-in.md). If sign-in fails, see [Troubleshooting](#troubleshooting).

> [!TIP]
>
> A job or coding agent that only runs apps or sets up integrations can use a [personal access token](https://docs.dify.ai/en/cli/personal-access-tokens.md) instead of a sign-in.

## List Your Apps

Check that `difyctl` works by listing the apps in the workspace you signed in to:

```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 installs an integration, publishes an app, or runs a command that `help` [labels `destructive`](https://docs.dify.ai/en/cli/find-and-run-commands#run-a-command) or shows with no label. Whether it does depends on the AI model your agent runs on.

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

```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](https://docs.dify.ai/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](https://docs.dify.ai/en/cli/build-apps.md)
* [Run your apps](https://docs.dify.ai/en/cli/run-apps.md)
* [Create or update apps from DSL files](https://docs.dify.ai/en/cli/create-and-update-apps-from-dsl-files.md)
* [Use `difyctl` in CI and automation](https://docs.dify.ai/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. 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. |


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