difyctl CLI#

difyctl (@langgenius/difyctl) is the official command-line interface for Dify, built on TypeScript/Bun and compiled to self-contained native binaries. It lives in the cli/ directory of the main Dify monorepo. The current release is 1.17.1 on the stable channel 1.

A key design constraint is strict version compatibility between the CLI and the Dify server: both sides enforce that they speak the same API contract, and the CLI release pipeline is integrated with Dify's own GitHub Releases rather than being distributed separately.

Binary Distribution#

Five standalone binaries are built per release 2:

Binaries are compiled via bun build --compile using a Bun version pinned in cli/.bun-version for reproducible output 3. Each release also ships a difyctl-v<version>-checksums.txt manifest of SHA256 hashes 4.

difyctl assets are attached to the corresponding Dify GitHub Release — there is no separate CLI release. Stale assets from prior builds are pruned from that release automatically 5.

Automated Installers#

POSIX (Linux/macOS):

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

Windows (PowerShell):

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

Both installers share the same flow 3 7:

1. Detect target — uname -s/uname -m (POSIX) or environment detection (PowerShell) maps the host to one of the five build targets.
2. Resolve release — by priority: DIFY_VERSION env var → DIFYCTL_VERSION env var → latest Dify release via GitHub API.
3. Download — fetches the binary and checksums.txt directly from GitHub Releases. No authentication required.
4. Verify SHA256 — fail-closed: installation aborts if the checksum does not match.
5. Install — places the binary at $HOME/.local/bin/difyctl (POSIX) or $LOCALAPPDATA\difyctl\bin\difyctl.exe (Windows), overridable via DIFYCTL_PREFIX.

Version pinning environment variables:

• DIFY_VERSION=1.17.1 — download the difyctl bundled with that Dify release.
• DIFYCTL_VERSION=1.17.1 — search Dify releases to find the one containing that CLI version.

Release Pipeline#

The workflow is defined in .github/workflows/cli-release.yml. It is triggered by a Dify release event, workflow_dispatch, or workflow_call. A dry_run boolean input parameter (default: false) is available for workflow_dispatch and workflow_call triggers; when true, the workflow builds and checksums binaries but skips asset upload and stale-asset pruning.

Two-job structure:

• validate 8: reads cli/package.json, validates the release manifest schema (via release-naming.mjs), resolves the target Dify release tag, and runs a compat-check to confirm the CLI's declared minDify/maxDify bounds (both must be plain X.Y.Z versions with minDify ≤ maxDify) match the Dify release.
• release 9: cross-compiles all five targets, generates the SHA256 checksums file, uploads assets to the Dify GitHub Release (unless dry_run is true), and prunes stale assets (unless dry_run is true).

Key properties:

• Immutable: A published version is never overwritten. Fixes require a version bump in cli/package.json.
• Serialized: Concurrency group difyctl-release with cancel-in-progress: false prevents parallel or mid-flight-cancelled releases 10.
• Repository-guarded: The validate job only runs when github.repository == 'langgenius/dify' 11.

Version Compatibility Gating#

difyctl enforces a hard compatibility contract between the CLI and the Dify server via bidirectional version gates. This was introduced in PR #38367 alongside breaking /openapi/v1 path refactors.

The compatibility bounds are declared in cli/package.json:

"compat": { "minDify": "1.16.0", "maxDify": "1.17.1" }

Client-Side Gate#

Implemented in cli/src/version/enforce.ts. Before running any authenticated command, the CLI:

1. Probes GET /_version on the server (2-second timeout, no retries).
2. Evaluates the response using compat.ts, comparing the server version against minDify/maxDify.
3. If too_old → hard error with exit code 6 and an upgrade hint.
4. If compatible or too_new → caches the result per host for 1 hour via compat-store.ts.

Fail-open on probe errors: network flakiness never blocks a command. Only positive ("compatible") results are cached — a just-upgraded server is usable immediately without waiting for cache expiry 12.

Server-Side Gate#

Implemented in api/controllers/openapi/_version_gate.py. A Flask before_app_request hook on the /openapi/v1 blueprint 13:

• Parses User-Agent: difyctl/<semver> (<os>; <arch>; <channel>).
• Returns HTTP 426 Upgrade Required if the client version is below MIN_DIFYCTL_VERSION (currently 1.17.0).
• Ignores non-difyctl clients (curl, browsers, etc.) — only blocks requests with a difyctl User-Agent.
• Allowlist: /_version and /_health are always reachable, even for outdated clients 14, so an old CLI can still discover the server version.
• Because the hook is app-wide (not route-scoped), it fires even for paths that no longer exist — preventing a 404 from masking the real problem when an old CLI calls a removed endpoint 15.

Relationship to OpenAPI Path Changes#

The version gate was introduced alongside a breaking refactor of /openapi/v1 paths from verb-suffix style to resource-oriented AIP-136 style (e.g., /apps/{id}/run → /apps/{id}:run). The gate ensures older CLI versions fail fast with a clear upgrade message rather than receiving unexpected 404s 15.

Key Files#