Profiles

Profiles let you save commonly-used configuration options in reusable files, making it easy to run complex commands without typing all the options every time. This has many uses: stick it in a cronjob, make sure your syncs are repeatable, experiment with adding multiple filters berfore committing to a --patterns-from file, etc.

Quick Start

Create a profile file (TOML, JSON, or YAML):

# myprofile.toml
[albums]
from = "subsonic"
to = "spotify"
similarity = 0.85
include = ["artist:'Taylor Swift'", "artist:'Opeth'"]

Use it with the --profile option:

pushtunes push albums --profile=myprofile.toml

Profile Formats

Profiles support three formats, auto-detected by file extension:

• TOML (.toml): Most readable, recommended
• JSON (.json): Standard data format also used for Pushtunes cache files
• YAML (.yaml, .yml): Popular configuration format you might enjoy if you're already haunted by YAML in your day job

TOML Example

[albums]
from = "subsonic"
to = "spotify"
similarity = 0.85
verbose = false
delete = false
color = true
log-level = "INFO"
ytm-auth = "browser.json"
include = ["artist:'Taylor Swift'", "artist:'Opeth'"]
exclude = ["album:'Live.*'"]
mappings-file = "mappings.csv"
export-csv = "not_found,error"
export-csv-file = "export.csv"
report = "not_found,error"

[tracks]
from = "subsonic"
to = "csv"
csv-file = "tracks-backup.csv"
verbose = false
color = true
include = ["artist:'Pink Floyd'"]

[playlist]
from = "spotify"
to = "ytm"
similarity = 0.9
verbose = false
color = true
log-level = "INFO"
require-all-tracks = false
on-conflict = "abort"
ytm-auth = "browser.json"

JSON Example

{
  "albums": {
    "from": "subsonic",
    "to": "spotify",
    "similarity": 0.85,
    "verbose": false,
    "delete": false,
    "color": true,
    "log-level": "INFO",
    "include": ["artist:'Taylor Swift'", "artist:'Opeth'"],
    "exclude": ["album:'Live.*'"],
    "mappings-file": "mappings.csv",
    "report": "not_found,error"
  },
  "tracks": {
    "from": "subsonic",
    "to": "csv",
    "csv-file": "tracks-backup.csv",
    "verbose": false,
    "color": true
  }
}

YAML Example

albums:
  from: subsonic
  to: spotify
  similarity: 0.85
  verbose: false
  delete: false
  color: true
  log-level: INFO
  include:
    - "artist:'Taylor Swift'"
    - "artist:'Opeth'"
  exclude:
    - "album:'Live.*'"
  mappings-file: mappings.csv
  report: not_found,error

tracks:
  from: subsonic
  to: csv
  csv-file: tracks-backup.csv
  verbose: false
  color: true

Profile Locations

Pushtunes searches for profiles in this order:

1. Absolute path: If you provide a full path like /home/user/configs/myprofile.toml
2. Current directory: The directory where you run the command
3. Config directory: ~/.config/pushtunes/ on Linux/macOS, similar on other platforms

Examples:

# Use profile from current directory
pushtunes push albums --profile=myprofile.toml

# Use profile from config directory
pushtunes push albums --profile=backup-config.toml

# Use absolute path
pushtunes push tracks --profile=/home/user/configs/production.yaml

Command-Specific Sections

Profiles can contain configurations for different commands using sections:

[albums]
from = "subsonic"
to = "spotify"
similarity = 0.85

[tracks]
from = "subsonic"
to = "ytm"
similarity = 0.9

[playlist]
from = "spotify"
to = "ytm"

When you run pushtunes push albums --profile=config.toml, only the [albums] section is used. This lets you keep all your configurations in one file.

Flat Structure (Single Command)

If your profile file only configures one command type, you can skip the section header:

# spotify-to-ytm.toml - used only for albums
from = "spotify"
to = "ytm"
similarity = 0.9

This works, but using sections is recommended for clarity.

Supported Options

All command-line options can be set in profiles:

Source and Target

• from: Source service (subsonic, jellyfin, spotify, ytm, csv)
• to: Target service (spotify, ytm, csv)

Files

• csv-file: CSV file path (for CSV source/target)
• ytm-auth: YouTube Music authentication file path (default: browser.json)
• mappings-file: Manual mappings CSV file
• patterns-from: File with include/exclude patterns

Filtering

• include: Array of include patterns
• exclude: Array of exclude patterns

Export

• export-csv: Comma-separated statuses to export
• export-csv-file: Filename for exported CSV

Matching

• similarity: Similarity threshold (0.0-1.0, default: 0.8)

Boolean Options

• verbose: Enable verbose output (default: false)
• delete: Delete items from target not in source (default: false)
• color: Enable colored output (default: true)
• require-all-tracks: Require all playlist tracks to match (playlist only, default: false)

Other Options

• log-level: Console log level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
• report: Generate detailed report for specific statuses (comma-separated)
• on-conflict: Playlist conflict resolution: abort, replace, append, or sync (playlist only, default: abort)

Playlist-Specific Options

• playlist-name: Name of the playlist to push
• source-playlist-id: ID of source playlist (for direct lookup)
• playlist-id: ID of existing target playlist (for conflict resolution)

CLI Arguments Override Profiles

Command-line arguments always take precedence over profile values. This lets you use a profile as a base configuration and override specific values:

# Use profile but change target
pushtunes push albums --profile=myprofile.toml --to ytm

# Use profile but change similarity
pushtunes push tracks --profile=backup.yaml --similarity=0.9

# Override source and target completely
pushtunes push albums --profile=myprofile.toml --from spotify --to ytm

List Options (include/exclude)

For include and exclude options, CLI arguments are appended to profile values rather than replacing them:

Profile:

[albums]
from = "subsonic"
to = "spotify"
include = ["artist:'Igorrr'"]

Command:

pushtunes push albums --profile=myprofile.toml --include="artist:'Opeth'"

Result: Both patterns are applied: - artist:'Igorrr' (from profile) - artist:'Opeth' (from CLI)

Use Cases

Backup Configuration

Create a profile for regular backups:

# backup.toml
[albums]
from = "subsonic"
to = "csv"
csv-file = "backups/albums-backup.csv"

[tracks]
from = "subsonic"
to = "csv"
csv-file = "backups/tracks-backup.csv"

Usage:

pushtunes push albums --profile=backup.toml
pushtunes push tracks --profile=backup.toml

Filtered Sync

Sync only specific artists with custom settings:

# favorites.toml
[albums]
from = "subsonic"
to = "spotify"
similarity = 0.85
include = [
    "artist:'Carbon Based Lifeforms'",
    "artist:'Ulver'",
    "artist:'Opeth'",
]
mappings-file = "favorites-mappings.csv"
export-csv = "not_found,error"
export-csv-file = "favorites-not-found.csv"

Usage:

pushtunes push albums --profile=favorites.toml

Cross-Service Migration

Migrate playlists between services:

# spotify-to-ytm.toml
[playlist]
from = "spotify"
to = "ytm"
similarity = 0.9
ytm-auth = "browser.json"
mappings-file = "spotify-ytm-mappings.csv"

Usage:

pushtunes push playlist --profile=spotify-to-ytm.toml --playlist-name="My Playlist"

Multiple Environments

Different profiles for different situations:

# production.toml
[albums]
from = "subsonic"
to = "spotify"
similarity = 0.85
mappings-file = "production-mappings.csv"

# testing.toml
[albums]
from = "csv"
csv-file = "test-data.csv"
to = "csv"
csv-file = "test-output.csv"
similarity = 0.7

Usage:

# Production sync
pushtunes push albums --profile=production.toml

# Testing with sample data
pushtunes push albums --profile=testing.toml

Organizing Profiles

Per-User Configurations

Store personal profiles in ~/.config/pushtunes/:

mkdir -p ~/.config/pushtunes
cp myprofile.toml ~/.config/pushtunes/

# Now you can use it from any directory
pushtunes push albums --profile=myprofile.toml

Project-Specific Profiles

Keep profiles with your project files:

myproject/
├── music-data.csv
├── mappings.csv
└── sync-profile.toml

cd myproject
pushtunes push albums --profile=sync-profile.toml

Shared Profiles

Store profiles in version control if you have multiple people sharing a local music library and each person might have their own Spotify or YTM accounts to push to with different mappings and for different purposes:

music-sync/
├── profiles/
│   ├── user-1-daily-backup.toml
│   ├── user-1-weekly-full-sync.toml
│   └── user-2-push-ytm.toml
├── mappings/
└── README.md

Required Options

Some options are always required, either in the profile or on the command line:

• from - Must be specified
• to - Must be specified

If these are missing, you'll get a clear error:

$ pushtunes push albums --profile=incomplete.toml
Error: --from is required (either via command line or profile)

Error Handling

Profile Not Found

$ pushtunes push albums --profile=missing.toml
Error loading profile: Profile not found: missing.toml
Searched in:
  - Current directory: /home/user/project
  - Config directory: /home/user/.config/pushtunes

Invalid Format

$ pushtunes push albums --profile=broken.toml
Error loading profile: Failed to parse profile broken.toml: ...

Unsupported Extension

$ pushtunes push albums --profile=config.txt
Error loading profile: Unsupported profile format: .txt. Supported formats: .yaml, .yml, .json, .toml

Example: Complete Workflow

Here's a complete workflow using profiles:

1. Create a profile for your daily sync:

# ~/.config/pushtunes/daily-sync.toml
[albums]
from = "subsonic"
to = "spotify"
similarity = 0.85
include = [
    "artist:'Carbon Based Lifeforms'",
    "artist:'Ulver'",
]
mappings-file = "/home/user/music/mappings.csv"
export-csv = "not_found,error"
export-csv-file = "/home/user/music/logs/daily-sync-issues.csv"

2. Run your daily sync:

pushtunes push albums --profile=daily-sync.toml

3. Override for a one-time full sync:

# Sync everything, not just filtered artists
pushtunes push albums --profile=daily-sync.toml --include="artist:'.*'"

4. Check what went wrong:

# Review the exported CSV
cat ~/music/logs/daily-sync-issues.csv

5. Add mappings and re-sync:

# Edit mappings file, then re-run
pushtunes push albums --profile=daily-sync.toml