Update, roll back and uninstall

One command moves to a new release, and the dashboard and Terminal tell you when one is out. Rollback and uninstall both preview first.

Edit this page

Update

The dashboard and Terminal check for a new release every hour. When one is out, the dashboard opens a dialog with what will change, Update now and Later (asks again in an hour). To run it yourself, one command:

Move to the latest release

piagent-update

Restart the dashboard afterwards so the new interface takes effect.

What it does, in order

Resolves the target release and the Pi version it pins.
Installs that Pi host, then replaces the piagent-update helper.
Checks the version actually on disk before running the installer.
With --project: migrates the project's state and runs piagent-doctor --strict-share.

Not from a git checkout

piagent-update refuses to run when the global package is a link to a source repository, so it never overwrites code you are editing.

Common options

Command	Use when
`piagent-update --check`	You only want to know whether a release is out.
`piagent-update --dry-run`	You want to see what would be installed, changing nothing.
`piagent-update --version X.Y.Z`	You want exactly one release, newer or older.
`piagent-update --project .`	You want the current project migrated too.
`--no-host` · `--no-package` · `--no-migrate`	You want to skip a step.

Pin one release for a team

For a team rollout, install the exact Pi host and platform release, then run the installer in stable mode. The --dry-run step prints what would change.

Pinned install

npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.3.0
npm install -g --ignore-scripts @piagent/platform@1.47.0
piagent-install --stable --dry-run
piagent-install --stable

Installed from a package, .pi/settings.json records npm:@piagent/platform@<version>: the same value on every machine, so the team can commit it. The full procedure is in the release & install policy.

Roll back

Rolling back is deliberate, never automatic. Move to a specific release with the same update command:

Back to a previous release

piagent-update --version X.Y.Z --dry-run
piagent-update --version X.Y.Z

To change only the Pi package and keep the host: piagent-install --version vX.Y.Z --resolve-tag. Run piagent-doctor on the project afterwards.

Uninstall

piagent-uninstall only reports what it would remove and exits. It acts with --apply, because it edits Pi settings that other tools also write to.

Preview, then remove

piagent-uninstall
piagent-uninstall --apply
npm uninstall -g @piagent/platform

Add-ons, the Pi host and project state are opt-in: --with-addons, --with-host, --project <path>.

Never removed

Credentials, trust, sessions, todos and .pi/memory/ are kept under every combination of flags. Files generated from a template and then edited (AGENTS.md, .pi/settings.json) are only listed, for you to decide.

On Windows

Run the same PowerShell command you installed with: it updates WSL, Piagent and Agent Watch. See Windows.