Upgrade and Uninstall

2026-11-05Loading rating…

This page explains how to upgrade OPW to a new version and how to uninstall it.

Upgrade

An upgrade has two parts: update OPW on this computer with the new ZIP file, then sync the configuration in each existing project.

Check the Current Version

opw --version

Upgrade Steps

  1. Download the new OPW ZIP fileopen in new window from GitHub.

  2. Reinstall OPW with the new ZIP file. Letting the AI do it is recommended: start a new session in the AI tool, replace <ZIP file path> with the actual path of the new ZIP file, and enter:

    I have downloaded the new Open Pilot Wizard ZIP file to <ZIP file path>.
    Follow INSTALL_AGENT.md in the ZIP file to upgrade Open Pilot Wizard to this version for me. Ask for approval when permissions are needed.
    

    You can also extract the ZIP file and run the install script manually; see Install Manually. The installation upgrades OPW and syncs the global Skills, knowledge base, scripts, and project template. It does not modify your plugin projects.

  3. Restart the terminal and the AI tool.

  4. Enter the root of each existing project, sync the project configuration, and run a self-check:

    opw update  # Sync the content of the installed version to the current project
    opw doctor  # Check whether the project is ready after the sync
    

opw update does not download a new version of OPW. It only syncs the installed version's content into the current project, so install the new version first, then run opw update.

Options for opw update

You can add the following options when you run opw update:

OptionPurpose
--globalSync only the global Skills, knowledge base, scripts, and project template, without modifying OPW files in the current project
--tools <tools>Specify the AI tools to sync, comma-separated: claude, opencode, codex; detected automatically if omitted
--forceForce overwriting OPW-managed files that you have modified

Without --global, opw update updates only the following two directories in the current project and does not modify your plugin code:

  • openspec/: the workflow configuration used by AI development tasks. Your requirement specs and designs (openspec/specs/ and openspec/changes/) are not modified.
  • .open-pilot-wizard/: the file list and runtime logs that OPW records on this computer.

Caution: --force overwrites your changes to OPW-managed files. Back up anything you want to keep first.

Check After Upgrading

It is enough for opw doctor to pass. If it reports that the project has historical issues and needs repair, run opw doctor --fix and follow the prompts to let the AI complete the repair. See Troubleshooting.

If the Upgrade Fails

When the upgrade succeeds, the install script ends with "OPW <version> 安装及全局同步完成" (installation and global sync complete). If it ends with an error message that starts with !, the new OPW version is installed, but syncing the global Skills, knowledge base, scripts, and project template failed. If the AI performs the installation, it explains the cause in its report.

Handle it based on the error message:

Error messageWhat to do
Reports a sync conflict and lists the conflicting filesThese are OPW files you modified (such as Skills in the AI tool), and the script kept your changes. After you confirm you no longer need those changes, run opw update --global --force
Any other error, such as a network interruption or insufficient permissionsFix the problem and run the install script again

Uninstall

Uninstalling has two levels:

CommandPurposePlugin code
opw uninstallRemove the OPW-managed configuration in the current projectKept
opw self uninstallRemove OPW itself: delete the whole ~/.open-pilot-wizard/ directory and clean up activation configurationKept

If several projects use OPW, do it in this order: uninstall from each project first, and uninstall OPW itself last, because the opw command is no longer available after OPW is removed.

Remove OPW Configuration from a Project

Run the following in the project root, the directory that contains .open-pilot-wizard/:

opw uninstall

The command only processes the current directory. If you run it in a subdirectory or any other directory, it does not report an error but cleans up nothing.

The command cleans up only OPW-managed configuration you have not modified. It keeps files you have modified and the specs and change records in the project. With --force, it deletes every file OPW has recorded, even if you modified it.

Caution: Project uninstall removes the configuration block that OPW added to openspec/config.yaml. If you customized that part, back it up first. --force deletes OPW-managed files you have modified, so back up before using it.

Uninstall OPW Itself

Warning: This step cannot be undone. It deletes the whole ~/.open-pilot-wizard/ directory (%USERPROFILE%\.open-pilot-wizard\ on Windows), including templates, the knowledge base, caches, preferences, statistics, and any files you placed there. Back up what you want to keep first.

First view the deletion plan. Without --yes, the command only shows the plan and does not run it:

opw self uninstall

When you are sure, run:

opw self uninstall --yes

The scope of the uninstall is:

ItemBehavior
OPW CLIUninstalled
~/.open-pilot-wizard/Deleted entirely
OPW Skills and entries in AI tool directoriesDeleted only if they match the record; files you modified are kept and reported
macOS shell startup filesOnly the OPW activation lines added by the install script are removed; other configuration is kept
Windows user PATHEntries pointing to the OPW directory are cleaned up; other paths are kept
Plugin projects, specs, and change recordsKept
AI tool programs, system Node.js, JDK, Android SDK, and Android StudioKept

On Windows, if the bundled Node.js is in use by the running command, the uninstall first returns "pending" and finishes the cleanup after the command exits.

Confirm After Uninstalling

  1. Restart the terminal and the AI tool so environment variables take effect.
  2. Run opw --version and confirm the command is no longer available.
  3. Confirm that pilot-plugin-dev and the OPW Skills no longer appear in the AI tool.

Your plugin projects are not deleted. To use OPW again, reinstall it by following the Quick Start.

Last Updated: