Export & import

Every dashboard can be downloaded as a single JSON file: layout, mode, theme choices, plus per-widget content like Todo lists and Scratchpad text. The file is portable across devices and Chrome profiles — drop it into another butter install via Import and you're back where you started.

How to export

Press , to open Settings. Scroll to the Layout section and click Export. butter packages the current state into JSON and triggers a download — file named butter-YYYY-MM-DD.json with today's date.

What's inside

The file has a small wrapper plus two payload sections:

{
  "version": 1,
  "exportedAt": 1731340800000,
  "sync": {
    "layout": [...],   // widgets, position, size, settings
    "theme":  "dark",  // mode: light / dark / system
    "dashboard-themes": { "light": "linen", "dark": "tokyo-night" }
  },
  "local": {
    "todos:abc123":        [...],     // a Todo widget's tasks
    "scratchpad:def456":   "...",     // a Scratchpad's text
    "ai-inbox-cache":      { ... }    // last AI Inbox triage
  }
}

The sync section mirrors what's in chrome.storage.sync — the cross-device-portable bits. The local section captures everything butter writes to chrome.storage.local that's worth keeping. Two prefixes are excluded from the export:

• cache:* — transient network responses. Excluded because they re-fetch on demand; including them would bloat the file with stale data.
• oauth:* — GitHub, Linear, and Google access tokens (plus the Ticker widget's Finnhub API key). Excluded because they're credentials bound to this device; moving them to another machine would be both a security risk and pointless (the receiving device would still need to re-auth to refresh).

How to import

Press , , scroll to Layout, click Import, and pick a butter export file. butter validates the schema version, applies the payload, and reloads the new tab so every widget remounts cleanly with its new content.

What import actually does

• The sync section replaces wholesale. Existing chrome.storage.sync is cleared, then the import's sync values are written. So if the import has a different theme, you get the import's theme.
• The local section merges, with prefix-scoped replacement. Existing local keys that aren't excluded (cache:*, oauth:*) are removed; the import's local section is written in. Cached network data and OAuth tokens survive — so importing a layout on a device with GitHub already connected doesn't disconnect it.
• Free-tier cap is enforced. If the import has more than six widgets and the importing user isn't Pro, the import is refused with a message explaining the limit. This stops anyone from sharing a 50-widget export as a workaround.

Use cases

• Migrating to a new machine without Chrome sync. Export from the old, import on the new. Faster than waiting for sync to settle and works even across Chrome profiles.
• Backing up a setup you like. Save the JSON somewhere safe; restore it any time you want to roll back changes. The 6-widget cap on free imports means you can't restore a Pro layout after a downgrade — keep an eye on size if you're cycling tiers.
• Sharing a layout with a teammate. Send them the JSON, they import. They'll need to reconnect GitHub / Linear themselves — by design, your tokens never leave your device — and their Todo / Scratchpad content will be yours (since those ride in the export). If that's not what you want, edit the file first.
• Inspecting your data. The file is plain JSON, two-space indented. Open it in any editor to see exactly what butter holds about your dashboard.

Heads up

• Imports replace, not merge. Importing wipes the current sync section before applying the new one. If you have content on the receiving device you want to keep, export that first.
• Schema version 1. The current export is at version 1. A future format change will bump the version and old imports will refuse to load — they'll error rather than silently dropping fields. The reverse isn't supported: a v2 export can't be imported by a v1 client.
• OAuth tokens reset. After importing, the connected widgets (GitHub, Linear, Calendar) sit on the existing device's tokens (the receiving device's, not the source's). You don't need to reconnect after importing on a device that was already connected.

---