Hirad/syncfm-core
Watch
1
0
Fork
You've already forked syncfm-core
 0
generated from Hirad/Template
Code Issues Pull requests Projects Releases 8 Packages Wiki Activity Actions
Page: Getting Started
Pages
CLI Reference Development Getting Started Home Networks and Proxies Persistence and Recovery Profiles and Credentials Public API Reference Python Integration Synchronization Behavior Troubleshooting
2 Getting Started
Hirad edited this page 2026-08-26 08:50:12 +03:30
Table of contents

Getting Started

Requirements

  • Python 3.12 or newer
  • API credentials for each music network
  • A working Python keyring backend, unless credentials are deliberately stored in the profile file

The project currently publishes its package metadata from the Git repository. Install from a pinned tag or commit when reproducibility matters.

Install the command-line application

With uv:

uv tool install git+https://git.hirad.it/Hirad/syncfm-core.git

With pipx:

pipx install git+https://git.hirad.it/Hirad/syncfm-core.git

From a source checkout:

git clone https://git.hirad.it/Hirad/syncfm-core.git
cd syncfm-core
uv sync
uv run syncfm --help

Create two profiles

Profiles name the source and target accounts. The command prompts for the API secret and password without echoing them.

syncfm profile add lastfm-main \
  --type lastfm \
  --username alice \
  --api-key YOUR_LASTFM_API_KEY

syncfm profile add libre-backup \
  --type librefm \
  --username alice \
  --api-key YOUR_LIBREFM_API_KEY

Use --use-session-key to enter an existing session key instead of a password. See Profiles and Credentials for GNU.fm, proxies, automation, and file-backed secrets.

Confirm the saved, non-secret fields:

syncfm profile list
syncfm profile show lastfm-main

Run the first sync

syncfm sync --source lastfm-main --target libre-backup

With no --start, SyncFM starts at the target's latest scrobble. With no --end, it ends at the current time. If the target has no scrobbles, an explicit start is required:

syncfm sync \
  --source lastfm-main \
  --target libre-backup \
  --start 1704067200

Both bounds are Unix timestamps in seconds and are inclusive.

After submission, SyncFM fetches the source history again and checks fresh target history up to three times while the service exposes newly submitted scrobbles. The result table distinguishes initial snapshot counts from verified counts. If source scrobbles are still absent from the target, the CLI lists them and asks whether to synchronize the range again.

A synchronization is one-way. Reverse --source and --target only if you intentionally want a separate reverse synchronization.

Recover interrupted work

The CLI allows one unfinished session in its selected database. If a run fails or is interrupted:

syncfm status
syncfm resume SESSION_ID

Modern sessions remember their source and target profiles. --source and --target on resume are needed only for legacy sessions that predate stored profile references.

To abandon the session and its local state:

syncfm discard SESSION_ID

See Persistence and Recovery before discarding a session whose target submission may have been interrupted.

Next steps

syncfm-core