Export & import

Every dashboard can be downloaded as a single JSON file: layout, theme, background, 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",
    "background": { "type": "gradient", "value": "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 and Linear access tokens. Excluded because they're bound to this device and OAuth app; 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 GitHub / Linear widgets will 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.

---