Scenario: updates and rollback

An update to Cratis AI changes what your agent is told to do, so you want to see it coming and be able to undo it. How you do that depends on the channel you installed through.

Channel	What an update takes	How to go back
Managed install	The current main of Cratis/AI	Reinstall from a checkout of a known-good commit with --source, or revert the commit that updated it
@cratis/pi	A published npm version	Install the earlier version
Marketplace plugins	The current default branch of Cratis/AI	Uninstall the plugin

Managed install

cratis ai update is not pinned. It takes whatever the source holds when it runs. Preview first:

cratis ai status               # installed revision, available revision, local edits
cratis ai update --dry-run     # the actions an update would take, without writing
cratis ai update

Because the managed content is committed, an update arrives as a diff you can review in a pull request, run your gates against, and merge like any other change.

To stay on a specific revision, or to roll back after an update you do not want, point the CLI at a local checkout of that commit:

git clone https://github.com/Cratis/AI ../cratis-ai
git -C ../cratis-ai checkout <known-good-commit>
cratis ai update --source ../cratis-ai --dry-run
cratis ai update --source ../cratis-ai

The source commit of the current install is recorded in .cratis/ai.manifest.json. If the update is still an unmerged branch, discard it; if it was merged, reverting that commit restores the previous files as well.

Edited managed files block updates

If someone edited a managed file, update stops before changing anything. Decide whether the edit should be kept (and proposed to Cratis/AI) or replaced, then restore it or use --force.

@cratis/pi

The Pi package is the one channel with real version numbers:

pi install -l npm:@cratis/pi                    # latest release
pi install -l npm:@cratis/pi@<version>          # a specific release, pinned
npm view @cratis/pi versions                    # what has been published

To roll back, install the version you last trusted. A versioned source stays at that version until you change it.

Marketplace plugins

The Claude Code, Codex, GitHub Copilot, and Cursor plugins read the current default branch of Cratis/AI. There is no version to pin. Updating means updating the plugin in your harness; the only way back is to uninstall it. If you need a fixed version, use the managed install with --source instead.

Uninstalling

cratis ai uninstall removes unchanged Cratis-managed files and the adapters the CLI created. It never removes files you created yourself, such as your own .cratis/ai rules and skills or an AGENTS.md you wrote. Run it with --dry-run first to see the list.

See Cratis AI distribution for the channels and ownership rules.