> ## Documentation Index > Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt > Use this file to discover all available pages before exploring further. # Upgrading & Downgrading > Keep crewship current with a single command, and roll back safely when an upgrade goes wrong. # Upgrading & Downgrading Crewship is a single binary plus a `crewship-sidecar` runtime that ships alongside it. Upgrading swaps the binary; the database migrates itself on the next start, behind an automatic snapshot. Rolling back a **binary** is one step (`self-update` keeps a `.bak`), but once migrations have run, recovery **also** requires restoring that pre-migration snapshot — see [Rollback / downgrade](#rollback-downgrade) below. ## Upgrade: `crewship self-update` One command, whatever platform you're on: ```bash theme={null} crewship self-update # upgrade to the latest release crewship self-update --check # report whether a newer release exists, change nothing ``` `self-update` picks the right mechanism from how crewship was installed: | Install method | What `self-update` does | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Homebrew** (`brew install crewship-ai/tap/crewship`) | Runs `brew upgrade ` for you (`crewship` or `crewship-cli`, whichever you have). | | **Installer / tarball** (`install.sh`, or a downloaded archive) | Downloads the release asset for your OS/arch **and build variant** (full `crewship` vs `crewship-cli`), **verifies its SHA-256** against `checksums.txt`, backs up the current binary to `.bak`, then **atomically swaps** the running binary in place — plus the bundled `crewship-sidecar` and `entrypoint.sh` when they sit alongside it. It re-runs the new binary's `version` as a sanity check and **rolls back from the backup** if that fails. | | **System package / read-only path** (apt, rpm, a container image) | Refuses to overwrite a file it doesn't own, and prints the exact command to use instead (`apt-get install --only-upgrade crewship`, `dnf upgrade crewship`, `docker pull …`, or a reinstall via `install.sh`). | The download is checksum-verified before anything is swapped, and the swap is atomic (write-temp-then-rename), so an interrupted update never leaves a half-written binary. The previous binary is kept at `.bak` for a manual rollback. `self-update` only acts when a newer release actually exists — otherwise it reports you're already current and exits. The SHA-256 check confirms the download matches the published `checksums.txt`; it does **not** verify the file's cosign signature. To verify provenance end-to-end (Sigstore keyless signature), use `install.sh` with `cosign` installed, or verify manually per the release notes. `self-update` needs a released binary. A development build (`version` = `dev`, e.g. `go run ./cmd/crewship`) refuses — there's nothing to compare against. ### Migrations run on the next start `self-update` swaps the binary only. Schema migrations apply on the **next `crewship start`**, and Crewship takes a **pre-migration snapshot** first (`.pre-migrate-v-to-v-.bak`, next to your DB). So the upgrade flow is: ```bash theme={null} crewship self-update crewship start # migrations apply here, after an automatic snapshot ``` ## Rollback / downgrade Migrations are **forward-only**. An older binary will **refuse to start** against a database a newer binary already migrated — with an error naming both versions — rather than silently corrupt data it doesn't understand: ``` database schema is at v134 but this Crewship binary only understands up to v130: the database was migrated by a NEWER Crewship. … either upgrade this binary … or restore the pre-migration snapshot taken before the upgrade. ``` Do it in this order — **restore the snapshot with your CURRENT binary first, then reinstall the older one**. `crewship db restore-snapshot` was introduced alongside the version-skew guard, so the older binary you're rolling back to may not have the command; run it from the newer binary that's still installed, before you replace it: 1. **Stop `crewshipd`** (a running server holds the database open). 2. **Restore the matching pre-migration snapshot** with the current binary: ```bash theme={null} crewship db restore-snapshot --list # show snapshots (newest first, with v→v) crewship db restore-snapshot # restore the most recent, or crewship db restore-snapshot .bak # restore a specific one ``` 3. **Reinstall the older binary.** Homebrew: `brew install crewship-ai/tap/crewship@` (or `brew uninstall` + install the pinned tag). Installer: `CREWSHIP_VERSION=vX.Y.Z curl -fsSL …/install.sh | bash`. 4. **Start the older binary** — it boots against the restored schema. `restore-snapshot` probes for a local server and refuses if it finds one, but that check is best-effort — **stop `crewshipd` yourself first** regardless. It only accepts a genuine `*.pre-migrate-*.bak` snapshot of your database, and copies the current database aside to `.before-restore-` before the swap, so the restore is itself reversible. Skipping step 2 leaves the newer schema in place, which the older binary rejects on start (by design). See [Migrations](/guides/migrations) for the version-skew guard and snapshot naming. ## Related * [Migrations](/guides/migrations) — the forward-only guard + pre-migration snapshots. * [Backup & restore](/guides/backup) — full backup bundles vs. the automatic migration snapshots. * [`crewship doctor`](/cli/doctor) — reports when a newer release is available.