Add version mismatch warning to CLI command execution failures

Target component

• CLI
• SDK
• Something else
• Not sure

Overview

The oxide CLI built from main or a given tagged release may fail when communicating with a rack running an older Omicron release. For example:

dev-machine $ oxide disk import --project example --path /path/to/disk --disk example_disk --description example --snapshot example_snapshot --image example_image --image-description testing --image-os debian --image-version 13.4.0

Which gives the output:

creating the disk failed: Error Response: status: 400 Bad Request; headers: {"content-type": "application/json", "x-request-id": "a3c0fe14-32fd-49d8-99fa-e77f3e4d9a97", "content-length": "150", "date": "Tue, 01 Apr 2026 00:00:00 GMT"}; value: Error { error_code: None, message: "unable to parse JSON body: missing field `disk_source` at line 1 column 164", request_id: "a3c0fe14-32fd-49d8-99fa-e77f3e4d9a97" }

Checking oxide version, we see:

dev-machine $ oxide version
Oxide CLI 0.15.0+2026021301.0.0
Built from commit: 68f182d88832582b765f31e70ea17de97f70c4cd
Oxide API: 2026021301.0.0

The cause being a schema change where disk_source was renamed to disk_backend starting in CLI version 15, with racks on older releases still expecting the original field name. Downgrading the CLI to the previous tag (v14) resolves the issue.

Note: I've linked changes to test files that illustrate this change inline above as an example as they are public, but can link to the internal PR change if need be.

Desired behavior:

When the CLI detects an incompatibility with the rack's API version, it should surface a clear error message rather than failing opaquely. This could take the form:

Version mismatch
The CLI version you are using requires a newer API schema.
- Rack API version: <version>
- Compatible CLI version: <version>

Implementation details

I think that this could be done by adding a check that could be called by the run function in cmd_version.rs.

Rather than checking for complete validity between versions, an inexpensive option could be to check the distance between the API version that the CLI expects, which I think could be fetched at any time via target_release object in the system update status endpoint.

Anything else you would like to add?

No response

Start in cli/src/cmd_version.rs and review how the CLI obtains or reports its version. Read the system update status endpoint documentation, especially the target_release object, and use the disk import failure as the compatibility scenario. Done means an incompatible rack API produces a clear version-mismatch message with the rack and compatible CLI versions instead of an opaque schema error.