Upgrade a source build

Rebuilding onto a newer version, and what does and does not need migrating.

Written By Dustin

Last updated About 3 hours ago

Upgrading a source build is a rebuild. There is no separate upgrade command and, today, no repository migration step.

The upgrade

git pull

cargo build --release -p tovio-cli

tovio --version

Copy the new binary over the old one wherever you put it. If you also installed git-credential-tovio, replace it at the same time — the two are built from one package and are expected to match.

Confirm the right binary is winning

The most common upgrade problem is not a failed build but a second copy earlier on your PATH. If tovio --version still reports the old version after a successful build, find out which one you are actually running — which tovio, or Get-Command tovio in PowerShell — before doing anything else.

Regenerate your completions

tovio completions bash > ~/.local/share/bash-completion/completions/tovio

Completion scripts are generated from the command surface at the version that produced them. A stale script silently fails to suggest new commands and flags. Regenerate after any upgrade that touched the CLI surface.

What happens to existing repositories

Nothing, in the normal case. The on-disk marker in .tovio/format currently reads tovio-format 1, and repositories created by earlier builds of the same format version are read directly by a newer binary.

Two related stability claims are worth stating precisely, because they are often collapsed into one:

Surface	Status
Wire protocol	Stable, version 1.0.0, and deliberately frozen. The frame set and canonical CBOR encodings are fixed; only additive, byte-compatible optional fields may be introduced.
Storage format	Format version 1, but the specification is still at Review status, not Stable. It is reconciled against the shipped implementation and the conformance corpus, and is not casually changed — but it does not carry the wire protocol's freeze guarantee.

So "the object format and the wire protocol are frozen" overstates it. The wire protocol is frozen. The storage format is versioned and stable in practice, and its specification is under review.

After upgrading

tovio status

tovio health

Run both in a repository you care about. status proves the store and working-copy scanner still read it; health reports whether the current lane is clean, landable, and how stale it is.

Back up the identity first on a Team repository

Upgrading does not touch key material. But before any maintenance on a machine that holds the only copy of an identity, take the portable backup:

tovio key export

It writes a passphrase-encrypted file that tovio key import can restore onto a new machine. It is the recovery path for the root device key, and it costs one command. (Adding a second machine is a different operation — tovio device enroll and tovio device approve, which give each machine its own key.)