From 22f636ca3d004d2e744439861f1be6fe07fa4fe7 Mon Sep 17 00:00:00 2001 From: woksin Date: Wed, 10 Jun 2026 21:09:04 +0200 Subject: [PATCH] Document cratis update in getting started Self-update detects the install method (Homebrew or .NET tool), supports --version on the .NET tool path, and the Linux binary prints manual steps. Install tabs now point at it. Co-Authored-By: Claude Fable 5 --- Documentation/getting-started/index.mdx | 37 +++++++++++++++++++++---- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/Documentation/getting-started/index.mdx b/Documentation/getting-started/index.mdx index bb0a963..0b18449 100644 --- a/Documentation/getting-started/index.mdx +++ b/Documentation/getting-started/index.mdx @@ -29,7 +29,7 @@ Pick the install that matches your machine. However you do it, you end up with t brew install cratis ``` - Upgrade later with `brew upgrade cratis`. + Upgrade later with a single `cratis update`. Download the pre-built native binary from the [latest release](https://github.com/Cratis/cli/releases/latest) and put it on your `PATH`: @@ -42,7 +42,7 @@ Pick the install that matches your machine. However you do it, you end up with t sudo mv cratis /usr/local/bin/cratis ``` - To upgrade, repeat with the newer release. + To upgrade, repeat with the newer release — `cratis update` prints these exact steps whenever a newer version is out. If you already have the [.NET SDK](https://dotnet.microsoft.com/download) (10 or newer), install it as a global tool — handy in CI and on Windows: @@ -51,7 +51,7 @@ Pick the install that matches your machine. However you do it, you end up with t dotnet tool install -g Cratis.Cli ``` - Upgrade with `dotnet tool update -g Cratis.Cli`. + Upgrade later with a single `cratis update`. @@ -73,9 +73,36 @@ Pick the install that matches your machine. However you do it, you end up with t +## Keep it up to date + +The CLI moves quickly, and "how did I install this again?" is a question you shouldn't have to answer every time a release lands. You don't — the CLI updates itself: + +```bash title="Update to the latest version" +cratis update +``` + +`cratis update` detects how this particular `cratis` got onto your machine and runs the right mechanism for it: on a Homebrew install it runs `brew update` followed by `brew upgrade cratis`; on a .NET tool install it runs `dotnet tool update -g Cratis.Cli`. Either way it ends by telling you exactly what happened: + +```text title="What you'll see" +Updating Cratis CLI... (current: 1.2.0) +Updated from 1.2.0 to 1.3.0 +``` + +If you're already current, it says so — `Already at the latest version (1.3.0)` — so the command is always safe to run. + +Need a specific version rather than the latest? Pass `--version`: + +```bash title="Install a specific version" +cratis update --version 1.2.3 +``` + + + ## How `cratis` decides where to connect -That worked with zero configuration, which is worth understanding rather than taking on faith. Every command needs one thing: a server to talk to. `cratis` resolves it by walking a short list of sources, top to bottom, and using the first one that's set: +`cratis get-started` connected with zero configuration, which is worth understanding rather than taking on faith. Every command needs one thing: a server to talk to. `cratis` resolves it by walking a short list of sources, top to bottom, and using the first one that's set: ```mermaid flowchart TD @@ -129,7 +156,7 @@ Refresh the embedded snapshot after a CLI upgrade with `cratis init --refresh`. ## Recap -In a couple of minutes you installed `cratis`, watched it find your local Chronicle through the `default` context, and confirmed the connection with `cratis get-started`. You also saw the one rule that governs every command — flag, then environment variable, then context, then the local default — so nothing about *where* it connects is a mystery anymore. +In a couple of minutes you installed `cratis`, watched it find your local Chronicle through the `default` context, and confirmed the connection with `cratis get-started`. Staying current is one command — `cratis update` — no matter how the CLI was installed. You also saw the one rule that governs every command — flag, then environment variable, then context, then the local default — so nothing about *where* it connects is a mystery anymore. ## Where to go next