Chrome Extension Setting Manager (CESM)

A command-line tool that backs up, moves, and restores extension settings stored in Chrome's local storage (chrome.storage.local) between profiles and machines.

For example: export a VPN bypass list from your laptop, copy the JSON file to your desktop, and import it there—without reconfiguring the extension by hand.

What it does

CESM reads and writes the on-disk storage Chrome extensions use for local settings. The typical workflow:

• Discover Chrome profiles and installed extensions (cesm list)
• Export selected settings to human-readable JSON in ./export/ (cesm export)
• Import JSON into another profile or machine, with merge or overwrite (cesm import)
• Rollback if an import goes wrong, using auto-saved snapshots in ./backup/ (cesm rollback)

flowchart LR
    list["cesm list"] --> export["cesm export"]
    export --> jsonFile["JSON in ./export/"]
    jsonFile --> importCmd["cesm import"]
    importCmd --> verify["Verify in Chrome"]
    verify -->|problem| rollback["cesm rollback"]

Loading

Running commands without flags launches guided prompts: profile picker, extension picker, key checklist, merge vs overwrite, and confirmations before writing.

Requirements

• Python 3.10+
• Google Chrome or Chromium with the target extension already installed on both source and destination
• Chrome must be fully closed during export, import, and rollback (the tool checks and will prompt you to close it)
• Supported OS: Windows, macOS, Linux (including native, Flatpak, and Snap installs)

On Linux, if Chrome lives in a non-standard location, set the CHROME_USER_DATA_DIR environment variable to your Chrome user data directory.

Installation

git clone <repo-url>
cd chrome-extension-setting-manager
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
cesm --help

plyvel (LevelDB) prerequisites

You only need these steps if pip install -e . fails while building plyvel from source. On common Linux x86_64 systems with Python 3.10–3.12, pre-built wheels usually install without extra packages.

Install system packages for your OS, then retry the install command above:

OS	Packages
Debian / Ubuntu	build-essential, python3-dev, libleveldb-dev
Fedora / RHEL	gcc-c++, python3-devel, leveldb-devel
macOS	Xcode Command Line Tools (xcode-select --install); if the build still fails: brew install leveldb
Windows	Visual Studio Build Tools with "Desktop development with C++"; prefer a Python version with a pre-built wheel when possible

# Debian/Ubuntu
sudo apt install build-essential python3-dev libleveldb-dev

# Fedora
sudo dnf install gcc-c++ python3-devel leveldb-devel

Quick start

The interactive path is recommended for first-time use:

# 1. See profiles and extensions
cesm list

# 2. Export (prompts for profile, extension, keys, output path)
cesm export

# 3. Copy the JSON file to the other machine, then import
cesm import

# 4. If something is wrong after verifying in Chrome
cesm rollback

Commands

Command	Purpose
cesm list	Browse profiles and extensions
cesm export	Save selected settings to JSON
cesm import	Restore settings from JSON
cesm rollback	Undo a prior import

cesm list

Shows Chrome profiles and the extensions installed in each one.

cesm list
cesm list --profile "Profile 1"

cesm export

Reads settings from an extension and writes them to a JSON backup file. You choose which keys to include.

cesm export
cesm export --profile "Default" --id <extension-id> --output ./export/my-backup.json
cesm export --keys bypass-list,antiphishing-enabled

Useful flags:

• --profile, -p — Chrome profile folder name (e.g. "Default", "Profile 1")
• --id, -i — 32-character extension ID
• --output, -o — destination JSON file path
• --keys, -k — comma-separated list of keys to export (skips the interactive checklist)
• --force — bypass the Chrome-closed safety check (use with caution)

cesm import

Writes settings from a JSON backup into an extension's storage. A rollback snapshot is saved automatically before any changes are made.

cesm import
cesm import --input ./export/my-backup.json
cesm import --input ./export/my-backup.json --profile Default --no-merge
cesm import --input ./export/my-backup.json --merge

Useful flags:

• --input, -in — source JSON backup file
• --profile, -p — destination Chrome profile
• --id, -i — 32-character extension ID (overrides backup metadata)
• --merge, -m / --no-merge — merge list data into existing keys, or overwrite keys entirely
• --force — bypass the Chrome-closed safety check (use with caution)

Merge vs overwrite: merge appends and deduplicates list data (useful for whitelists and bypass lists). Overwrite replaces each key's value entirely.

cesm rollback

Restores extension settings from a pre-import snapshot created during a prior cesm import.

cesm rollback
cesm rollback --backup ./backup/rollback-my-ext-20260620T120000.json

Useful flags:

• --backup — path to a specific rollback snapshot
• --profile, -p — filter or target a Chrome profile
• --id, -i — filter or target an extension ID
• --force — bypass the Chrome-closed safety check (use with caution)

Where files go

Location	Contents
./export/	Backups you create with cesm export (default suggestion: backup-{extension-name}.json)
./backup/	Automatic pre-import rollback snapshots (created by cesm import; used by cesm rollback)

Both directories are gitignored. Treat export files as portable backups you can copy between machines. Rollback snapshots are local safety nets and are kept until you delete them.

An exported backup looks roughly like this:

{
  "cesm": {
    "format_version": 1,
    "extension_id": "...",
    "extension_name": "My Extension",
    "source_profile": "Default",
    "exported_at": "2026-06-20T12:00:00+00:00"
  },
  "settings": {
    "some-key": "value",
    "another-key": []
  }
}

Tips and cautions

• Install the same extension on the destination machine before importing.
• Close Chrome completely before export, import, or rollback.
• Every import creates a rollback snapshot automatically—you can undo with cesm rollback if settings look wrong.
• Extension storage may contain sensitive data (tokens, account IDs). Handle JSON backups accordingly and do not commit them to version control.

Further reading

For architecture, JSON formats, and implementation details, see README-Architecture.md.

License

This project is licensed under the MIT License.