Version

Check your difyctl build and its compatibility with your Dify server

Run difyctl version to see which difyctl build you have and whether it works with your Dify server. It prints the client build, probes your active host, and reports a compatibility verdict.

In a script, --check-compat turns that verdict into an exit code.

Check Client and Server Versions

difyctl version [flags]

Flags

Flag	Type	Default	Description
--short	boolean	false	Print only the client semver (no server probe) and exit.
--client	boolean	false	Skip the server probe, so the verdict reports unknown.
--check-compat	boolean	false	Exit 64 unless the verdict is compatible.
-o <format>	string	text	Output format: text, json, or yaml.

Examples

Print the full report:

difyctl version

Print just the client version, for scripts and bug reports:

difyctl version --short

Output

Format	What stdout gets
default (text)	The full report: a Client block, a Server block, and a one-line Compatibility verdict. Builds on any channel other than stable append a warning recommending the stable channel.
-o json, -o yaml	The same report as three objects: client (version, commit, buildDate, channel, platform, arch) server (endpoint, reachable, and on success version and edition) compat (minDify, maxDify, status, detail)

The default text report:

Client:
  Version:   0.2.0-alpha (channel: alpha)
  Commit:    9f3c2ab (built 2026-06-05)
  Platform:  darwin/arm64
  Compat:    dify >=1.16.0, <=1.16.0

Server:
  Endpoint:  https://cloud.dify.ai
  Version:   1.16.0 (cloud)

Compatibility: ok — server 1.16.0 in [1.16.0, 1.16.0]

--short prints only the client semver:

0.2.0-alpha

-o json:

{
  "client": {
    "version": "0.2.0-alpha",
    "commit": "9f3c2ab",
    "buildDate": "2026-06-05",
    "channel": "alpha",
    "platform": "darwin",
    "arch": "arm64"
  },
  "server": {
    "endpoint": "https://cloud.dify.ai",
    "reachable": true,
    "version": "1.16.0",
    "edition": "CLOUD"
  },
  "compat": {
    "minDify": "1.16.0",
    "maxDify": "1.16.0",
    "status": "compatible",
    "detail": "server 1.16.0 in [1.16.0, 1.16.0]"
  }
}

This command exits 0 even when the server is unreachable or incompatible: the verdict is the report, not an error. Pass --check-compat (below) to turn it into an exit code. Other commands act on the verdict; see How Commands React to an Incompatible Server.

Exit Codes

Code	Meaning
0	Report printed, whatever the verdict
64	With --check-compat: the verdict was not compatible

See Output Formats and Exit Codes for the full scheme.

Compatibility Verdicts

difyctl version compares your build against the server’s version and reports one of four verdicts. You don’t need to be signed in, but you do need a stored host to probe.

The text report prints the Shown as label on its Compatibility: line; -o json reports the verdict name in status.

Verdict	Shown as	Meaning
compatible	ok	The server version is inside the range this build supports.
too_old	incompatible (server too old)	The server is older than the minimum this build supports.
too_new	incompatible (server too new)	The server is newer than the maximum this build was tested against.
unknown	unknown	No verdict: no host configured, the server is unreachable, the probe was skipped with --client, or the server’s version didn’t parse.

The detail field spells out the case, for example server 1.14.0 is older than the minimum 1.16.0 or server 1.16.0 in [1.16.0, 1.16.0].

How Commands React to an Incompatible Server

difyctl version only reports the verdict. Every command that contacts the server acts on it before running, so a too_old server stops those commands until you resolve the mismatch:

• too_old: the command stops with exit 6 before doing its work, and tells you to upgrade the Dify server to at least the minimum this build supports (or install the difyctl that matches your server).
• too_new: the command runs; in an interactive terminal with text output, it also prints a throttled one-line warning to stderr.
• unknown: the command runs; there is nothing to gate on.

A server that clears the minimum version (compatible or too_new) is cached for about an hour per host, so the block check isn’t repeated on every command. A too_old server is never cached, so it’s re-checked each time and starts working as soon as you upgrade it.

Signing in with auth login runs the same check before it stores a session, so a mismatch surfaces at sign-in rather than on your first command.

The checks run in both directions: the verdicts above are difyctl judging your server, and your server also judges difyctl.

If your client is older than the server accepts, the server rejects the request with HTTP 426 and difyctl exits 6 with an upgrade message. This is why upgrading your Dify server can break an older difyctl: the server refuses the old client, even though that client’s own verdict on a newer server is only a warning.

So the reliable path is to keep difyctl matched to your server: a newer server is tolerated with a warning, but an older one is refused.

Gate Scripts on Compatibility

--check-compat makes the verdict scriptable: anything other than compatible, including every unknown case, exits 64. difyctl version always probes the server live and never reads the compatibility cache, so a scripted gate reflects the current version; the flag only turns that verdict into an exit code.

The full report still goes to stdout in your chosen format, and the one-line reason goes to stderr, so difyctl version -o json --check-compat | jq works the same on both outcomes.

difyctl version --check-compat || echo "difyctl and this Dify server are not a confirmed match"

Exit code 64 is specific to this flag. No other difyctl failure uses it.