# 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 dry-run` to confirm the pre-upgrade configuration is valid. ## Using the published updater Configure the public Forgejo repository in `config/system.toml`: ```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 ` 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 `.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//` before it is modified. ## Rollback Use `cireilclaw update rollback` to atomically exchange the current executable with `.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 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.