# How to Update Goose to the Latest Version: CLI and Manual Methods > Learn how to update Goose to the latest version using the CLI with `goose update` or `goose update --canary`. Get the newest features and security patches quickly. - Repository: [goose/goose](https://github.com/aaif-goose/goose) - Tags: how-to-guide - Published: 2026-04-07 --- **Run `goose update` in your terminal to automatically download, verify, and install the latest stable release, or use `goose update --canary` for development builds.** The Goose AI agent framework provides a built-in updater that handles the entire upgrade process securely. This guide covers both the automatic update mechanism implemented in [`crates/goose-cli/src/commands/update.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-cli/src/commands/update.rs) and manual installation steps for all supported platforms. ## Using the `goose update` Command The **`goose update`** sub-command performs a fully automated upgrade flow that downloads platform-specific binaries, verifies cryptographic signatures, and safely replaces the running executable. ### How the Automatic Updater Works According to the source code in [`crates/goose-cli/src/commands/update.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-cli/src/commands/update.rs), the updater executes an eight-step process: 1. **Asset selection** – The `asset_name()` function maps your current OS and CPU architecture (macOS-aarch64, Linux-x86_64, Windows-x86_64, etc.) to the correct archive file name (e.g., `goose-x86_64-apple-darwin.tar.bz2`). 2. **Download** – The tool fetches the archive from `https://github.com/aaif-goose/goose/releases/download//` using the GitHub Releases API. 3. **SLSA provenance verification** – The `verify_provenance()` function hashes the downloaded archive, fetches Sigstore attestations from the GitHub API, and validates the bundle against the production trust root. Failed verification aborts the update; missing attestations trigger a warning but allow continuation. 4. **Hardened extraction** – - On macOS/Linux, `extract_tar_bz2()` validates every entry path, rejecting absolute paths and `..` components to prevent directory traversal attacks. - On Windows, `extract_zip()` uses `enclosed_name()` to mitigate zip-slip vulnerabilities. 5. **Binary location** – `find_binary()` searches the extracted archive for the new executable, checking `goose-package/` subdirectories, top-level directories, or one level deeper. 6. **Atomic replacement** – - Unix systems copy the new binary over the current executable and reset the executable bit. - Windows renames the running file to `goose.exe.old`, copies the new binary into place, and uses `copy_dlls()` to move any accompanying `.dll` files. 7. **Optional reconfiguration** – Passing `--reconfigure` runs `goose configure` immediately after the binary swap. 8. **Status report** – The command outputs whether Sigstore verification succeeded. ### Update Command Options Use these flags to customize the update behavior: ```bash # Update to the latest stable release (default) goose update # Update to the latest canary (development) build goose update --canary # Update and immediately re-run the configuration wizard goose update --reconfigure ``` ## Manual Update Methods If you prefer not to use the CLI updater, download platform-specific assets directly from the GitHub Releases page. ### Manual Update on macOS and Linux Download the appropriate `.tar.bz2` archive for your architecture and replace the existing binary: ```bash # Download the macOS ARM64 asset (adjust URL for your platform) curl -L -o goose.tar.bz2 \ https://github.com/aaif-goose/goose/releases/download/stable/goose-aarch64-apple-darwin.tar.bz2 # Extract the archive tar -xjf goose.tar.bz2 # Replace the existing binary (typically in /usr/local/bin or ~/.local/bin) sudo mv goose /usr/local/bin/goose sudo chmod +x /usr/local/bin/goose ``` For Linux x86_64 systems, substitute `goose-x86_64-unknown-linux-gnu.tar.bz2` in the URL. ### Manual Update on Windows Download the Windows MSVC zip archive and perform the replacement: ```powershell # Download the Windows x86_64 asset Invoke-WebRequest -Uri ` "https://github.com/aaif-goose/goose/releases/download/stable/goose-x86_64-pc-windows-msvc.zip" ` -OutFile goose.zip # Extract to temporary location Expand-Archive -Path goose.zip -DestinationPath $env:TEMP\goose # Rename the current executable (close Goose Desktop first) Move-Item -Path "$env:LOCALAPPDATA\goose\goose.exe" ` -Destination "$env:LOCALAPPDATA\goose\goose.exe.old" -Force # Install the new binary Copy-Item -Path "$env:TEMP\goose\goose.exe" ` -Destination "$env:LOCALAPPDATA\goose\goose.exe" -Force # Copy any required DLLs Copy-Item -Path "$env:TEMP\goose\*.dll" -Destination "$env:LOCALAPPDATA\goose\" -Force ``` ## Security and Verification Features The Goose updater implements defense-in-depth measures to ensure binary integrity. The **`verify_provenance()`** function validates SLSA (Supply-chain Levels for Software Artifacts) attestations using Sigstore, ensuring the binary you download matches the code that was audited and built in GitHub Actions. Path traversal protection is enforced during extraction. The `validate_entry_path()` helper in the tar extractor and `enclosed_name()` in the zip extractor prevent malicious archives from writing files outside the intended directory, protecting against zip-slip and tar-slip attacks. ## Summary - **Automatic updates**: Run `goose update` to fetch, verify, and install the latest stable release with a single command. - **Development builds**: Use `goose update --canary` to test bleeding-edge features. - **Security validation**: All automatic updates verify SLSA provenance via Sigstore and validate archive integrity before extraction. - **Manual fallback**: Download platform-specific archives (`.tar.bz2` for Unix, `.zip` for Windows) from GitHub Releases when CLI updates are unavailable. - **Safe replacement**: The updater handles running-binary replacement atomically, including Windows DLL synchronization and Unix permission preservation. ## Frequently Asked Questions ### What is the difference between stable and canary updates? **Stable releases** are production-ready versions that have passed full testing and auditing cycles. **Canary builds** (`goose update --canary`) represent the latest development commits and may contain experimental features or unresolved bugs. The updater selects assets from different GitHub release tags based on this flag. ### Why does the update command verify SLSA provenance? SLSA verification ensures the binary was built from the official source code in a secure GitHub Actions environment and has not been tampered with during distribution. The `verify_provenance()` function in [`crates/goose-cli/src/commands/update.rs`](https://github.com/aaif-goose/goose/blob/main/crates/goose-cli/src/commands/update.rs) checks Sigstore bundles against the production trust root, providing cryptographic proof of the software supply chain integrity. ### What should I do if the automatic update fails? If `goose update` fails during download or verification, check your internet connection and GitHub API access. For extraction or permission errors, ensure you have write access to the directory containing the Goose binary. As a fallback, follow the manual download instructions for your platform, which bypass the automatic verifier while still allowing you to obtain the official release assets. ### Where does the update command download files from? The updater fetches releases from `https://github.com/aaif-goose/goose/releases/download//` using the GitHub Releases API. Asset selection is determined by `asset_name()`, which constructs filenames like `goose-aarch64-apple-darwin.tar.bz2` or `goose-x86_64-pc-windows-msvc.zip` based on the target platform detected at compile time.