Skip to content

Getting started

This guide installs the command, inspects the browser profiles visible on your Mac, previews and estimates the import, and starts the first real submission.

Prerequisites

You need:

  • macOS;
  • Python 3.13 or newer;
  • uv;
  • a running Refindery backend; and
  • a bearer token accepted by that backend.

The backend defaults to http://127.0.0.1:8000. Deploying or configuring Refindery itself is outside the scope of this project.

Install the importer

Install the published command as an isolated tool:

$ uv tool install browser-history-refindery
$ refindery-import --version

Upgrade it later with:

$ uv tool upgrade browser-history-refindery

Choose a working directory

By default, the importer creates config.toml and refindery_state.sqlite3 in the current working directory. Run the command from one stable, private directory so every invocation finds the same settings and resume state:

$ mkdir -p ~/.config/refindery-import
$ cd ~/.config/refindery-import

Both files contain sensitive operational data. config.toml can contain the bearer token, and the state database records submitted and skipped URLs. Do not commit or share them.

Discover browser profiles

List the profiles the importer can read:

$ refindery-import list-profiles

The table shows the browser name, browser profile, distinct URL count, and history database path. See browser compatibility for the discovery rules and known browser families.

Grant Safari access

macOS protects Safari history with Full Disk Access. If Safari is shown as needs Full Disk Access:

  1. Open System Settings → Privacy & Security → Full Disk Access.
  2. Enable access for the terminal application that runs the importer.
  3. Quit and restart that terminal application.
  4. Run refindery-import list-profiles again.

You can leave Safari unselected if you do not want to grant access.

Preview the import

Start an interactive dry run:

$ refindery-import import --dry-run

All discovered profiles are initially checked. Adjust the selection, then confirm it. The report shows the total eligible pages, pages per Refinder-style domain, estimated incremental disk use and indexing cost, excluded and deduplicated counts, estimate coverage, and the ten newest eligible URLs.

A non-empty dry run probes Refindery and, with a valid token and a server that advertises batch_estimate, sends the same eligible URL metadata as an import. Refindery may fetch and extract those pages to estimate them, but it must not persist pages or invoke paid providers. Configure the token before the dry run for live estimates. If live estimation is unavailable, the importer uses the last configuration-aware fallback profile cached for that server; before the first successful estimate, storage and cost are reported as unavailable.

The command can create the default config and local state database, record the run and exclusions, and update the estimation-profile cache. It never records a successful submission or advances profile watermarks.

For an unattended preview of every discovered profile:

$ refindery-import import --dry-run --all

Configure Refindery authentication

The first import command creates a commented config.toml. Edit its server section when Refindery is not at the default URL:

[server]
base_url = "https://refindery.example.com"
auth_token = "replace-with-your-token"

For better secret hygiene, leave auth_token unset and use an environment variable instead:

$ export REFINDERY_AUTH_TOKEN="replace-with-your-token"

A non-empty server.auth_token takes precedence over the environment variable. See configuration for every setting and default.

Run the first import

Run the command without a subcommand for the default interactive flow:

$ refindery-import

Or import every discovered profile without a prompt:

$ refindery-import import --all

The importer waits for GET /readyz to return 200, reads and filters the selected histories, then shows a live dashboard while URLs are submitted and page statuses are polled.

If pages are still indexing when the import finishes, refresh them later:

$ refindery-import status-sweep

Continue with importing history to understand incremental runs, limits, retries, and interruption.