Skip to content

Document cratis update in getting started #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
woksin merged 1 commit into from
Jun 10, 2026
Merged

Document cratis update in getting started #33

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 32 additions & 5 deletions Documentation/getting-started/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
</TabItem>
<TabItem label="Linux" icon="linux">
Download the pre-built native binary from the [latest release](https://github.com/Cratis/cli/releases/latest) and put it on your `PATH`:
Expand All @@ -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.
</TabItem>
<TabItem label=".NET tool" icon="seti:c-sharp">
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:
Expand All @@ -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`.
</TabItem>
</Tabs>

Expand All @@ -73,9 +73,36 @@ Pick the install that matches your machine. However you do it, you end up with t

</Steps>

## 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
```

<Aside type="note">
`--version` works on .NET tool installs only — Homebrew can only move to the latest formula, and the CLI tells you so rather than guess. The Linux native binary can't replace itself either; there, `cratis update` prints the same download-and-replace steps from the install tab above so you don't have to go looking for them.
</Aside>

## 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
Expand Down Expand Up @@ -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

Expand Down