Skip to content

Upgrading Whittl

Whittl is format-stable across versions. Your projects, settings, skills, and templates carry forward unchanged. This page covers exactly what to expect and the few edge cases that need attention.

The happy path

  1. New version arrives (Help → Check for Updates in v2.4+, or browser download in v2.3 and earlier)
  2. Old version is uninstalled, new version installs over it
  3. Launch new Whittl
  4. Everything is where you left it

No data migration step. No manual import. Projects at ~/.whittl/projects/ are read by every Whittl version.

In-app updates (v2.4 and later)

Help → Check for Updates:

  1. Dialog shows "Whittl v2.X.X is available" with a Download button
  2. Click Download — progress bar appears, downloads happen in-app
  3. SHA256 verifies on completion
  4. "Restart to install" button appears
  5. Click it — Whittl closes, installer runs silently over existing install, new Whittl launches automatically

No browser, no Downloads folder hunt, no UAC prompt (per-user install).

If you quit Whittl between download and install, the downloaded installer persists. Next launch offers "Install v2.X.X now" without re-downloading.

Browser updates (v2.3 and earlier)

The pre-v2.4 flow:

  1. Check for Updates → opens your browser to the R2 download URL
  2. Download the installer manually
  3. Close Whittl
  4. Run the installer (click through SmartScreen "Run anyway")
  5. Relaunch Whittl

Users upgrading from v2.3 to v2.4 go through this flow one last time. Every upgrade after is in-app.

What auto-migrates

  • Projects — no change, same format
  • API keys — encrypted same way, forward-compatible
  • Settings — new settings default to sensible values, old settings preserved
  • Skills — read the same regardless of version
  • Templates — forward-compatible
  • Archives — not touched
  • Favorites — OpenRouter favorites preserved

Historically, one migration was needed (v2.0 → v2.1 OpenRouter model naming). It ran automatically on first launch of v2.1; nothing for users to do.

What doesn't carry across

  • Recent file list — rebuilt as you open files in the new version
  • Window position / size — resets on first launch of a major version
  • Cached model lists — OpenRouter refreshes on first use

Nothing user-meaningful.

Downgrading

Going BACK to an older version:

  1. Uninstall current version (Control Panel → Programs)
  2. Download the older installer from https://pub-573d835c3fa144b4943659b8717d7fd1.r2.dev/Whittl/v2.X.X/
  3. Install

Caveat: if you opened a project in a NEWER Whittl that wrote new metadata fields, the OLDER Whittl might not read them cleanly. Generally Whittl is forward-compatible both ways, but forward-then-backward is the riskiest case. Keep backups via ~/.whittl/projects/ copies if you plan to downgrade.

If an upgrade breaks something

  1. Check the release notes for the new version for behavior changes
  2. Check Common Issues — version-transition bugs show up there first
  3. Reinstall the previous version (see Downgrading above)
  4. Report the bug with the error message + OS + both Whittl versions (old and new)

Rare but possible. Upgrade paths are tested on a fresh VM before each release, but your workflow might exercise edge cases the test suite doesn't.

Backup checklist before a major upgrade

Paranoid upgraders can make this pre-upgrade routine:

  1. Copy ~/.whittl/ to ~/.whittl.backup-v2.X/
  2. Upgrade
  3. Verify a project opens and Test Run works
  4. Delete the backup when you're confident

~/.whittl/ is usually under 100 MB — the copy takes seconds.

What's next

  • Privacy — what the update check sends (nothing beyond the version query)
  • Folder Structure — what's under ~/.whittl/ and whether it survives upgrades