How to Update Goose to the Latest Version: CLI and Manual Methods

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 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, 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/<tag>/<asset> 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:

# 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:

# 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:

# 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 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/<tag>/ 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}