Metadata-Version: 2.5
Name: braveprefs
Version: 0.1.0
Summary: Export, compare and restore browser profile settings as one small readable JSON file.
Project-URL: Homepage, https://github.com/Rezarys/braveprefs
Project-URL: Source, https://github.com/Rezarys/braveprefs
Author: Younes Z.
License: MIT
License-File: LICENSE
Keywords: backup,browser,chromium,cli,configuration,dotfiles,migration,preferences,profile,restore,settings
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# braveprefs

```
pip install braveprefs
```

Put your browser settings in one short JSON file, compare that file between two machines, and write it back on a fresh install. No sync account, no QR code, no network.

This project is not affiliated with Brave Software or with any browser publisher. It reads and writes files on your own disk and nothing else.

## Why

Today the way to move your settings to a new machine is to copy the whole profile directory, several gigabytes of caches and databases, to recover a few kilobytes of choices. The rest of that directory does not restore cleanly anyway. `braveprefs` takes the few kilobytes.

The output is a file you can read, keep in a git repository, and diff.

## Use

Find your profile directory first (see below), then:

```
braveprefs export "<profile directory>" -o settings.json
braveprefs diff settings.json other-machine.json
braveprefs import "<profile directory>" settings.json
```

`import` is a dry run by default: it prints what it would change and writes nothing. Add `--apply` to write, with the browser closed:

```
braveprefs import "<profile directory>" settings.json --apply
```

Before writing, it copies the original `Preferences` file next to itself with a timestamp, so you can always put it back. If a `SingletonLock` file is present, the browser may still be running and the command stops; close the browser, or pass `--force` if you know the lock is stale.

`diff` exits with status 1 when the two files differ and 0 when they match, so it fits in a script.

## What never leaves your profile

The list of settings this tool touches is a list of named keys, written out one by one in `src/braveprefs/keys.py`. It is not a name pattern. A key that is not named there is never read and never written. Concretely, none of this is ever in the exported file:

- passwords, cookies, tokens, session state
- browsing history, downloads history, visited sites
- wallet data, payment methods, or any encrypted store
- your extensions and their data, except the id of your current theme, which is technically an extension in this browser
- account identifiers and anything the browser uses to sign you in

The exported file is plain text on purpose. Open it and read it.

Two settings in the list are folder paths, the download folder and the save as folder, and a folder path can contain your account name. When either is present the exported file says so in its `notes` field. Read the file before you share it. A folder path that exists on one machine may not exist on another, especially across operating systems; import writes it anyway, so check it still makes sense before you apply it.

## Settings the browser protects, and what this tool does about them

Some settings are not stored like the others. Upstream Chromium splits the profile in two: `Preferences`, and a second file `Secure Preferences` for a fixed set of tracked settings, with a validation authenticator recorded for each of them under `protection.macs`. Two things follow. Writing one of those settings into the plain file has no effect, because the browser reads it from the other file. Writing it into the protected file without a matching authenticator is undone at the next start, on the platforms where upstream turns enforcement on, which are Windows and macOS by default. Either way an outside tool cannot put those values back and make them stay, and it would look like it had worked.

So this tool does not write them. It exports them under a separate `read_only` key in the file, and `export` prints them by name, so you can still read them, compare two machines, and set them yourself in the settings screen. The settings in that group are the home button and home page, what opens on startup, pinned tabs, and the default search engine.

On top of that fixed list, `export` and `import` also look at your actual profile: any covered setting that sits in `Secure Preferences`, or that has an authenticator recorded for it, is treated as read only for that profile even if the fixed list does not mention it. A file edited by hand cannot get around this either, because the list of names is checked again on the way in.

This is the honest shape of the problem rather than a workaround. A tool that says what it cannot do stays useful. A tool whose writes quietly disappear does not.

## Which settings are covered

Roughly sixty named keys, grouped as:

- appearance and layout: bookmarks bar, side panel, toolbar buttons, dark mode, tab behaviour
- new tab page: clock, stats row, what the page shows
- fonts and text: font families, default and minimum sizes, caret browsing
- languages and spelling: accepted languages, dictionaries, translation preferences
- downloads and printing: download folder, ask where to save, default printer
- privacy and autofill: do not track, suggestions, preloading, address and payment autofill
- shields: your own filter rules, filter list subscriptions, embed and language settings
- startup and search: read only, see the section above

The file `src/braveprefs/keys.py` is the list, with a one line label for each key. Every key in it has its own test.

## Finding your profile directory

Open the browser's version page (`brave://version` in that browser, `chrome://version` in others) and copy the value next to **Profile Path**. That is the directory to pass to `braveprefs`. It is the directory that contains a file named `Preferences`, not the directory above it.

On Windows it sits under `C:\Users\<you>\AppData\Local\BraveSoftware\Brave-Browser`. On other systems the version page is the reliable answer.

## What has not been tested

No real browser profile was read while building this. The key names and the protection mechanism come from the upstream Chromium source, and the test suite runs on example files written for the tests. If you run it on a real profile, whether it works or not, please open an issue and say what happened. That is the one thing I cannot check from here.

## Where this came from

The request thread: https://github.com/brave/brave-browser/issues/46192

There are other tools in this area that apply a hardened set of settings chosen by their author. This one does the opposite: it moves *your* settings, whatever they are, and decides nothing for you.

## Notes

Built with AI assistance, reviewed and tested by me.

Requires Python 3.8 or later. No dependencies outside the standard library.

Run the tests with `python3 -m unittest discover -s tests -t tests` from a checkout, with `src` on `PYTHONPATH`.

MIT licensed. Younes Z.
