CLI Reference
The installed entry point is syncfm. Run syncfm COMMAND --help for generated help matching the installed version.
Global options
Global options must appear before the subcommand:
syncfm --database ./state.sqlite3 --config ./profiles.toml sync ...
| Option | Environment variable | Default | Meaning |
|---|---|---|---|
--database FILE |
SYNCFM_DATABASE_PATH |
Platform user-state directory, then syncfm/syncfm.sqlite3 |
SQLite recovery-state database |
--config FILE |
SYNCFM_CONFIG_PATH |
Platform user-config directory, then syncfm/config.toml |
Profile configuration document |
--verbose, -v |
— | Off | Enable diagnostic logging |
--install-completion |
— | — | Install shell completion |
--show-completion |
— | — | Print shell completion code |
--help, -h |
— | — | Show help |
On a typical Linux system the defaults are ~/.local/state/syncfm/syncfm.sqlite3 and ~/.config/syncfm/config.toml. Actual paths are chosen with platformdirs, so use syncfm --help to confirm them on the current OS.
syncfm sync
Start a new one-way synchronization:
syncfm sync --source PROFILE --target PROFILE [--start UNIX] [--end UNIX]
| Option | Environment variable | Required | Meaning |
|---|---|---|---|
--source TEXT |
SYNCFM_SOURCE_PROFILE |
Yes | Profile to read |
--target TEXT |
SYNCFM_TARGET_PROFILE |
Yes | Profile to receive missing events |
--start INTEGER |
— | No | Inclusive, non-negative Unix start timestamp |
--end INTEGER |
— | No | Inclusive, non-negative Unix end timestamp |
If start is omitted, the target's latest scrobble determines it. An empty target therefore requires --start. If end is omitted, current Unix time is used. Start must not exceed end.
The CLI refuses to start while any unfinished session exists in the selected database. Resume or discard that session first.
syncfm status
syncfm status
Lists unfinished sessions with their ID, direction, range, and phase. Completed sessions are removed automatically.
syncfm resume
syncfm resume SESSION_ID [--source PROFILE --target PROFILE]
Resumes from safely persisted state. Current sessions store both profile names and need only the ID. For a legacy session, provide both original profile names once; they are then persisted. Supplied names must match stored names.
The --source and --target options also accept SYNCFM_SOURCE_PROFILE and SYNCFM_TARGET_PROFILE.
syncfm discard
syncfm discard SESSION_ID [--yes|-y]
Deletes the session and all associated snapshots and queue state. Without --yes, the CLI asks for confirmation. This does not remove scrobbles already accepted by a remote target.
Profile commands
Add or replace
syncfm profile add NAME \
--type lastfm|librefm|gnufm \
--username USER \
--api-key KEY \
[--hostname HOST] \
[--proxy URL] \
[--secret-storage keyring|file] \
[--use-session-key] \
[--force]
--hostname is required for gnufm. The default secret storage is keyring. --force replaces an existing profile. Secret values are prompted, or can be supplied through:
SYNCFM_PROFILE_API_SECRETSYNCFM_PROFILE_PASSWORDSYNCFM_PROFILE_SESSION_KEYwhen--use-session-keyis set
Avoid leaking secrets through shell history, process configuration, or CI logs when using environment variables.
List and inspect
syncfm profile list
syncfm profile show NAME
These commands do not display credentials.
Remove
syncfm profile remove NAME [--yes|-y]
Removal deletes the TOML profile and, for keyring-backed profiles, the corresponding keyring entry.
Exit behavior
Application-owned configuration, network, synchronization, and persistence errors are printed as ExceptionClass: message and exit with status 1. Attempting a new sync while unfinished work exists exits with status 2. Normal Typer parsing and usage errors use Typer's standard nonzero exits.