Skip to content

Update Cratis CLI

cratis update updates Cratis CLI through the detected installation method. Homebrew installations on macOS and .NET tool installations support automatic updates; other native binaries require manual updates. Use this procedure for an existing installation, not as part of your first connection check.

The update command can change more than the CLI executable:

  • Homebrew on macOS: runs brew update, then brew upgrade cratis.
  • .NET global tool: runs dotnet tool update -g Cratis.Cli.
  • Project templates: checks for and installs newer templates under ~/.cratis/templates. Pass --no-templates to skip this refresh. If the template check fails, existing templates remain in place.
  • Cratis Stage: if a Stage sandbox image already exists locally, checks for an update and can pull a newer image. It does not pull a Stage image when none is installed.
  • Builder images: for each packaged builder image already on your machine, such as cratis/builder or cratis/studio-axon-builder, pulls the newest version from Docker Hub. The images are released with Studio, so their versions follow Studio’s. It does not pull a builder image you have never used.

The native-binary path can still refresh templates, an existing Stage image and existing builder images, even though it cannot replace the CLI executable. Do not treat cratis update as a read-only version check.

  1. Run the command from a terminal where the installation’s package manager is available:

    Update to the latest version
    cratis update
  2. Read the result for the CLI, templates, and any Stage or builder image refresh. For a successful CLI upgrade, output includes the previous and installed versions. For example:

    Example update output
    Updating Cratis CLI... (current: 1.2.0)
    Updated from 1.2.0 to 1.3.0

    A builder image that was refreshed adds a line such as Updated the builder image cratis/builder from 1.4.0 to 1.5.0, or The builder image cratis/builder is already at the latest version (1.5.0). With --output json, the same results are in builderImages, one entry per image with repository, previousVersion, currentVersion and updated.

    These version numbers illustrate the output, not the current release. If the detected installed version is unchanged, the command reports Already at the latest version (...). Package-manager failures are reported as update failures.

  3. Run cratis again to use the installed version. When an upgrade succeeds, the update command shows the new release notes or offers to page through skipped releases. You can also run cratis release-notes; see the release notes reference.

Installation Update behavior
Homebrew on macOS Upgrades to the latest formula; --version is not supported.
Homebrew on Linux Prints manual Linux update instructions; run the Homebrew commands below directly.
.NET global tool Updates to the latest version, or a version selected with --version.
Native binary Prints manual update instructions; download and replace the executable yourself.

For a Homebrew installation on Linux, cratis update does not upgrade the executable. Update the package directly with:

Update Homebrew on Linux
brew update
brew upgrade cratis

For a .NET global tool installation, request a specific version with:

Install a specific version
cratis update --version 1.2.3

For the latest Linux native release, repeat the native binary installation procedure. A successful return from the manual-update path does not mean the executable was replaced.

Check the update report and start a new cratis invocation. If the package manager reports a failure, resolve that failure before retrying; do not infer an upgrade from an update-availability message alone.

If you generated AI command context with cratis init, run cratis init --refresh after upgrading to regenerate its snapshot. Return to Getting started to check a Chronicle connection, or continue with the Chronicle command reference.