Upgrades

CireilClaw applies configuration migrations automatically when a new version starts.

Migrations update configuration files and persisted session data to match the new version's schema.

Before upgrading

1. Back up the complete runtime root.
2. Read the release notes for the target version and note any manual steps.
3. Restore the backup to a scratch path and run cireilclaw --root <PATH> dry-run to confirm the pre-upgrade configuration is valid.

Using the published updater

Configure the public Forgejo repository in config/system.toml:

[updater]
repository = "https://git.example.test/owner/cireilclaw"

Use cireilclaw update check to see whether a newer stable release is available.

Use cireilclaw update latest to inspect the selected release, archive, size, and checksum.

Use cireilclaw update install to stage and verify the newest release, then confirm the replacement.

Pass --repository <URL> for a one-invocation source override, or pass an exact stable version to update install.

The updater is Linux x64-only and requires the invoking executable to be a writable published CireilClaw binary.

Stop all agents and channels before installing or rolling back, because run and every mutating command hold the shared runtime-root mutation lock. Published executable operations also hold an installation-scoped lock, so another runtime root cannot replace the same executable concurrently.

The updater retains exactly one previous executable at <executable>.old.

During upgrade

The updater does not run configuration migrations during installation.

Migrations run automatically when the new version starts, or can be applied explicitly with cireilclaw migrate.

Every file changed by a migration is backed up under config/backups/<migrationId>/ before it is modified.

Rollback

Use cireilclaw update rollback to atomically exchange the current executable with <executable>.old.

Executable rollback does not restore configuration files, migration markers, databases, agent data, or credentials.

If a new executable starts and migration fails, the new executable remains current and .old remains available for manual recovery.

After upgrading

Run cireilclaw --root <PATH> dry-run against a copy of the migrated runtime before activating it.

If a migration fails, diagnose from the logs and restore from backup before retrying.