Skip to content

CLI reference

The executable is refindery-import. Running it with no subcommand starts the default interactive import using config.toml in the current directory.

Global command

$ refindery-import [--version] [--help]
Option Behavior
--version Print refindery-import VERSION and exit successfully.
--install-completion Install shell completion for the current shell.
--show-completion Print the completion script for the current shell.
--help Show global help and available subcommands.

The global invocation does not accept --config. Use the explicit import subcommand when selecting another config file.

import

$ refindery-import import [OPTIONS]

Read, merge, filter, and submit browser history.

Option Value Default Behavior
--config Path config.toml Select the TOML config file.
--db Path Discovery Read one specific history database.
--browser chromium, firefox, or safari None Declare the schema family used by --db; required with it.
--all Flag Off Select every discovered profile without a prompt.
--limit Positive integer Unlimited Submit at most this many eligible URLs, newest first.
--dry-run Flag Off Build and report the plan without contacting Refindery.
--full Flag Off Ignore read watermarks; local submission deduplication still applies.
--help Flag — Show command help.

No discovered databases is a runtime error with exit status 1. A missing --browser for --db, a missing database file, or a non-positive limit is a usage error with status 2. Cancelling the interactive profile picker exits without submitting.

list-profiles

$ refindery-import list-profiles

List discovered browser profiles, URL counts, and history paths. Safari access problems are reported per profile so other profiles can still be listed. If no profiles are found, the command prints a diagnostic and returns without an import.

This command does not load or create config.toml.

status-sweep

$ refindery-import status-sweep [--config PATH]

Re-poll up to 500 recorded nonterminal pages, update local status, and print status counts. The config defaults to config.toml.

forget

$ refindery-import forget TARGET [OPTIONS]

Permanently purge a URL or domain from Refindery and create a blacklist rule. The operation always asks for confirmation.

Option Value Default Behavior
--domain Flag Off Treat TARGET as a complete domain instead of an exact URL.
--reason Text None Store an explanatory note on the rule.
--config Path config.toml Select the backend configuration.
--help Flag — Show command help.

blacklist list

$ refindery-import blacklist list [--config PATH]

Print server-side blacklist IDs, kinds, patterns, reasons, and creation times.

blacklist remove

$ refindery-import blacklist remove BLACKLIST_ID [--config PATH]

Delete one server-side rule. Future ingestion is allowed again, but previously purged content remains deleted.

Common runtime failures

Commands that load a config print a concise error and exit with status 1 for known runtime failures such as:

  • a missing or rejected bearer token;
  • Refindery not becoming ready before server.ready_timeout;
  • Safari Full Disk Access denial; or
  • a state database created by a newer, unsupported schema version.

See troubleshooting for remediation.