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#
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:
Print just the client version, for scripts and bug reports:
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:
|
The default text report:
--short prints only the client semver:
-o json:
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 exit6before doing its work, and tells you to upgrade the Dify server to at least the minimum this build supports (or install thedifyctlthat 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.
Exit code 64 is specific to this flag. No other difyctl failure uses it.