Upgrade and Uninstall
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
Download the new OPW ZIP file from GitHub.
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.
Restart the terminal and the AI tool.
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:
| Option | Purpose |
|---|---|
--global | Sync 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 |
--force | Force 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/andopenspec/changes/) are not modified..open-pilot-wizard/: the file list and runtime logs that OPW records on this computer.
Caution:
--forceoverwrites 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 message | What to do |
|---|---|
| Reports a sync conflict and lists the conflicting files | These 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 permissions | Fix the problem and run the install script again |
Uninstall
Uninstalling has two levels:
| Command | Purpose | Plugin code |
|---|---|---|
opw uninstall | Remove the OPW-managed configuration in the current project | Kept |
opw self uninstall | Remove OPW itself: delete the whole ~/.open-pilot-wizard/ directory and clean up activation configuration | Kept |
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.--forcedeletes 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:
| Item | Behavior |
|---|---|
| OPW CLI | Uninstalled |
~/.open-pilot-wizard/ | Deleted entirely |
| OPW Skills and entries in AI tool directories | Deleted only if they match the record; files you modified are kept and reported |
| macOS shell startup files | Only the OPW activation lines added by the install script are removed; other configuration is kept |
| Windows user PATH | Entries pointing to the OPW directory are cleaned up; other paths are kept |
| Plugin projects, specs, and change records | Kept |
| AI tool programs, system Node.js, JDK, Android SDK, and Android Studio | Kept |
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
- Restart the terminal and the AI tool so environment variables take effect.
- Run
opw --versionand confirm the command is no longer available. - Confirm that
pilot-plugin-devand 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.