Updating crystl · crystl Docs

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

Go back with one click. When an update installs, crystl keeps the version it replaced. The app menu then has roll back to … under check for updates…, and settings, general > startup, has the same button under UPDATES. Click it, confirm, and crystl quits and reopens on the earlier version. The newer build becomes the kept one, so you can return to it the same way. Automatic update checks stay quiet about the version you left until a newer one ships. check for updates… by hand still offers it.

The kept copy is made when an update installs, so the first update after 2.275.0 is the first one you can roll back from. Before that, or if nothing is kept, install the earlier version by hand, which takes a minute:

Find the version you want in the changelog. Releases are numbered 2.216.0, 2.215.0, and so on.
Download it directly, putting the version number in the URL:

https://crystl.dev/download/2.216.0

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

Your gems, shards, settings, and history are stored 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

Getting started if you are still setting up.
Licensing for activation and renewal.
Your agent can drive crystl to let your agent answer version questions for you.