Backup, Migration, and Uninstall

Cola stores sessions, memory, settings, logs, task state, and output files on your Mac. Uninstalling the app does not necessarily delete that data. Deleting local data is also not the same as deleting your account.

Before migrating, reinstalling, or handing off a computer, decide what you want to keep and what you want to remove.

Where Local Data Lives

Cola's main local data is stored in:

~/.cola/

It can contain settings, account state, sessions, memory, tasks, logs, and plugin or channel state.

User-visible files generated by Cola are stored by default in:

~/cola/outputs/

If you use the Projects workspace, you may also have:

~/.cola/coding-cola/

Cola tidies ~/.cola/ into a fixed layout on every launch: data is filed into the subdirectory that matches its purpose, and anything left over from an older version or no longer used by Cola is archived under ~/.cola/legacy/. Backing up the whole of ~/.cola/ needs no knowledge of that split — but if you noted a specific path before, confirm where it lives after upgrading.

For more on these directories, see Privacy and Local Data.

Quit Cola Before Backup

Before backing up, fully quit Cola. This avoids copying sessions, logs, or task state while they are being written.

You can back up:

• ~/.cola/: full local state.
• ~/cola/outputs/: generated files and user-visible outputs.
• Project directories you authorized Cola to work on: these may not be inside Cola's data directory.

If you only need result files, backing up ~/cola/outputs/ and important project directories is usually enough.

Back up ~/.cola/ only if you want to preserve chat history, memory, settings, and local task state.

The Snapshot Cola Keeps for You

Separately from anything you back up yourself, the first launch of each day writes a compressed snapshot of ~/.cola/ in the background to:

~/cola-backup/

Files are named cola-backup-YYYY-MM-DD.tar.gz, one per day. Up to three snapshots are kept, with older ones pruned automatically; retention is based on the number of snapshots, not the last three calendar days. It runs in the background, so an ordinary launch is not slowed down by it.

The snapshot leaves out caches, machine-local runtime state, embedded browser data, and credentials. Treat it as a safety net for history, not as a replacement for your own full backup.

One case does make you wait: when Cola needs to migrate or rewrite existing data, it refreshes the day's snapshot first. If that takes more than half a second, a non-closable initialization window appears (Initializing, please wait…) and goes away on its own when the work is done. Don't force-quit while it is up — let it finish.

To restore from a snapshot:

1. Quit Cola completely.
2. Rename the existing ~/.cola/ to an unused backup directory name, such as ~/.cola-before-restore/, to preserve your current data.
3. Extract the chosen snapshot into a temporary directory. The archive contains a top-level .cola/ directory; enable hidden files in your file manager if you cannot see it.
4. Move that extracted .cola/ directory into your home directory so it becomes the new ~/.cola/. Do not merge it into the old directory or nest it at ~/.cola/.cola/: that can mix old files into the restored data or prevent Cola from finding it.
5. Reopen Cola, sign in if prompted, and check your chat history, memory, and settings. Keep the original data from step 2 until you have confirmed the restore worked.

Migrate to Another Mac

When moving to a new computer, use this order:

1. Quit Cola on the old computer.
2. Back up ~/.cola/ and ~/cola/outputs/.
3. Install and open Cola on the new computer.
4. Fully quit Cola on the new computer.
5. Copy the backup to the same locations on the new computer.
6. Reopen Cola and sign in.

After migration, check:

• Whether relevant project directories still exist.
• Whether old project paths match the new computer.
• Whether authorized directories still exist.
• Whether model tiers and Usage balance refresh normally.

If the old and new macOS usernames differ, some historical paths may point to the old location. In that case, point Cola at the new path or continue using only the new directories.

Reinstall Cola

If you are only reinstalling the app, you usually do not need to delete local data.

1. Quit Cola.
2. Remove or replace the app bundle.
3. Install the new version.
4. Reopen Cola and sign in.

As long as ~/.cola/ and ~/cola/outputs/ are not deleted, historical data and outputs usually remain on your Mac.

Reset with Doctor Mode

Cola's Doctor Mode provides three levels:

• Restart App: relaunch Cola without deleting local data.
• Reset App State: create a backup, remove session data, then relaunch.
• Factory Reset: create a backup, clear the entire ~/.cola/ directory, then relaunch.

Doctor Mode backups are stored in:

~/.cola-backups/

Factory Reset is high risk. It is meant for severely corrupted local state, not as a normal sign-out or cache-cleaning step.

Uninstall Cola

Removing the app bundle usually removes only the application. It may not delete local data.

If you want to fully uninstall and clean local data:

1. Sign out in Cola.
2. Fully quit Cola.
3. Back up output files you still need.
4. Delete the app bundle.
5. Delete local data directories you no longer need, such as ~/.cola/, ~/.cola-backups/, and ~/cola/outputs/.

Before deleting, confirm these directories do not contain sessions, memory, project files, generated files, or logs you still need.

What Does Not Migrate Automatically

You may need to handle these again:

• macOS microphone, notification, and other system permissions.
• Third-party account authorization.
• Authorized file-access directories on the new computer.
• Company network, proxy, certificate, or security gateway configuration.
• External dependencies and local environment inside original project directories.

Cloud state such as Cola account, balance, and orders follows the account. Local sessions, memory, logs, and outputs mainly live on the Mac.

Checklist Before Deleting Local Data

Before deleting local data, confirm:

• Whether you still need chat history.
• Whether you still need long-term preferences Cola remembered.
• Whether you still need task outputs, images, documents, or code changes.
• Whether you need to keep logs or feedback material.
• Whether you have signed out of Cola and third-party services.

If you are only troubleshooting, prefer Doctor Mode's Reset App State instead of deleting the whole local data directory.