Updating crystl

Updated September 18, 2026

crystl updates itself. This page covers where to look, how to check on demand, and what to do on the rare occasion a release goes wrong.

How updates arrive

crystl checks for new versions automatically, against a signed feed at crystl.dev/appcast.xml. When it finds one, you are told rather than interrupted: nothing installs itself behind your back, and no agent is stopped mid-turn.

Updates are signed, and crystl verifies the signature before installing anything. A build that does not verify is not offered.

The version label and the update badge

Look at the bottom centre of the status bar. The version you are running is always there:

v2.217.0

When a newer build exists, an update available badge appears next to it. Click the badge to install.

The badge appears only once crystl has genuinely confirmed a newer build from the feed. It is never a guess, so if it is not there, you are on the current version as far as crystl can tell.

Check on demand

Do not want to wait for the next automatic check?

crystl → check for updates… in the app menu.

See what changed

Three ways, depending on where you are:

  • The changelog on the website, which is the full list.
  • crystl docs changelog in any terminal, which is the same content without leaving your shard.
  • Ask your agent. A shard carries the running version in CRYSTL_VERSION, so an agent can compare what you are on against what shipped and tell you whether the thing annoying you is already fixed. See your agent can drive crystl.

That last one is the quickest answer to “is this a bug or am I out of date”. Ask before filing.

The crystl docs CLI caches its index for six hours, so just after a release the terminal copy can trail the website slightly. The web changelog is always current.

After an update, a what’s new panel summarises the release once, on the version you just moved to.

If a release breaks something

There is no in-app rollback today. The recovery is to install the previous version by hand, which takes a minute:

  1. Find the version you want in the changelog. Releases are numbered 2.216.0, 2.215.0, and so on.

  2. Download it directly, putting the version number in the URL:

    https://crystl.dev/download/2.216.0

  3. Quit crystl, drag the downloaded app into Applications replacing the current one, and launch it.

Your gems, shards, settings, and history live outside the app bundle, so going back a version does not touch them.

Then tell me what broke, so the next release fixes it rather than repeating it:

crystl report bug "2.217.0 crashes on launch"

crystl report is free on every tier. It opens an editable draft on the desktop and you press send yourself, so nothing leaves your machine without you reading it first. Add --diagnostics for a performance problem to attach a numbers-only health snapshot, which you can detach in the panel.

Where to go next