Upgrades

Use these steps for a source-installed Magistr CLI. You need a checkout of the source repository and the same build prerequisites as Installation.

Before updating, finish or close active sessions normally and make a backup. Keep uncommitted changes in the source checkout safe.

Update the executable

In the Magistr source checkout, run:

git pull --ff-only
cargo install --locked --path crates/magistr-cli --force
magistr --version

If Git cannot fast-forward, review the local branch and changes rather than discarding them. If the build fails, keep the error and confirm which executable command -v magistr selects before continuing.

The desktop is built separately. Rebuild it from the updated checkout using the desktop launcher, or install the intended new development package.

Check each connected project

In the project you use with Magistr:

magistr doctor .
magistr repair . --dry-run

Review the proposed repair and apply it with magistr repair . when needed. Open a fresh agent session afterward and confirm that it reads the expected project and saved work.

Repair refreshes eligible setup while preserving customizations. It is separate from automatic conversion of recognized older data.

Automatic conversion

When Magistr opens a project, it converts recognized older configuration, launch commands, and saved data into the current format. Successful routine conversions are quiet. Custom commands, other MCP connections, environment settings, and agent preferences are preserved.

Known conversions include older workflow configuration and launch registrations, project identity, supported workflow record formats, workspace configuration, and the source-change journal. Old indexes and process connections are rebuilt rather than treated as live current state.

A conversion is not a general import of arbitrary files. Unknown formats, unrecognized storage layouts, or conflicting records require review.

Recovery copies

Keep these with your backups. Interrupted conversions retry safely; unfinished work should be reported as unfinished rather than appearing as an empty project.

Resolve a conflict

If an older session still owns the project, close it normally and retry. Magistr does not terminate it or delete its lock to force an upgrade.

If two settings or records disagree, preserve both and use the specific error to identify the decision needed. Malformed data, unknown versions, and unsafe symbolic-link cases are refused rather than overwritten with defaults.

Do not edit storage files simply to imitate a current schema. Use an owner-supported conversion or get help with the original records intact. Customized instructions and intentionally removed setup are not automatically regenerated by a routine upgrade.

Success means the new version runs, the connection works, expected records are readable, and your custom settings remain in effect.