---
title: Version
description: Check your difyctl build and its compatibility with your Dify server
---

Run [`difyctl version`](#check-client-and-server-versions) 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](#compatibility-verdicts).

In a script, [`--check-compat`](#gate-scripts-on-compatibility) turns that verdict into an exit code.

## Check Client and Server Versions

```text
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:

```bash
difyctl version
```

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

```bash
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: <ul><li>`client` (`version`, `commit`, `buildDate`, `channel`, `platform`, `arch`)</li><li>`server` (`endpoint`, `reachable`, and on success `version` and `edition`)</li><li>`compat` (`minDify`, `maxDify`, `status`, `detail`)</li></ul> |

The default `text` report:

```text
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:

```text
0.2.0-alpha
```

`-o json`:

```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](#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](/en/cli/reference/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`](/en/cli/reference/output-formats-and-exit-codes) 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](/en/cli/install)).
- **`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`](/en/cli/reference/auth-and-contexts) 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.

```bash
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.