Hirad/syncfm-core
Watch
1
0
Fork
You've already forked syncfm-core
 0
generated from Hirad/Template
Code Issues Pull requests Projects Releases 1 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
1 Getting Started
Hirad edited this page 2026-08-14 09:18:17 +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.

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