CLI Commands

Without arguments, the binary starts the MCP server. With a subcommand, it runs as a standalone CLI tool for batch operations.

# MCP server mode (default, launched by your MCP host)
reklawdbox

# CLI mode
reklawdbox <command> [options]

CLI commands load env vars from .mcp.json automatically — same config as the MCP server.

Command overview

Command	Description
analyze	Batch audio analysis
backup	Manage Rekordbox library backups
hydrate	Batch enrichment and audio analysis
read-tags	Read native audio-file metadata
write-tags	Write native audio-file metadata
extract-art	Extract embedded cover art
embed-art	Embed cover art into audio files
setup	Install Essentia or configure a custom broker
disconnect-broker	Clear the stored Discogs broker session

---

backup

Manage Rekordbox library backups. Creates compressed archives of your database files in ~/Music/rekordbox-backups/.

reklawdbox backup [options]

Flag	Type	Description
--db-only	flag	Database files only (~50MB, fast)
--list	flag	List existing backups
--restore	path	Restore from a backup archive

With no flags, creates a full backup (~1GB compressed) of the entire Rekordbox data directory. When REKORDBOX_DB_PATH is configured, manual database-only and full backups use its parent directory rather than the standard install path. The configured value must be a direct regular file named master.db; symlinks are rejected. Close Rekordbox first for the strongest backup consistency.

New full archives always contain one canonical top-level rekordbox/ directory, even when the configured source directory has a different name. Full restore maps that root into the configured target directory. A database restore can recreate a missing master.db when its configured parent directory already exists; if any related allowlisted file remains there, a successful pre-restore safety archive is still mandatory. --list does not require a live source database.

A database-only backup also runs automatically before every write_xml export — you don’t need to run this manually for that. The built-in export path must create and move its archive successfully before XML creation. A configured custom script receives --pre-op first plus the effective path in its child REKORDBOX_DB_PATH; its zero exit is trusted as the operator’s success attestation. A missing or failed custom script blocks the export, while staged changes remain available for retry. This command is for manual backups and restores; neither database-only nor full archives include your audio files.

---

hydrate

Batch Discogs + Beatport enrichment and audio analysis. Use it to warm these caches for workflows that consume them.

reklawdbox hydrate [options]

Flag	Short	Type	Default	Description
--providers		list	discogs,beatport,analysis	Comma-separated provider list
--playlist		string		Filter by playlist ID
--artist		string		Filter by artist (partial match)
--genre		string		Filter by genre (partial match)
--bpm-min		number		Minimum BPM
--bpm-max		number		Maximum BPM
--key		string		Filter by musical key
--label		string		Filter by label (partial match)
--path		string		Filter by file path (partial match)
--query		string		Search query matching title or artist
--added-after		date		ISO date — tracks added on or after
--added-before		date		ISO date — tracks added on or before
--rating-min		1-5		Minimum star rating
--max-tracks		integer	unlimited	Cap number of tracks to process
--no-retry-errors		flag		Don’t retry previously-errored enrichments
--cpu		preset	background	CPU scheduling: background (~50% cores, niced) or overnight (cores - 2)
--concurrency	-j	integer	4	Enrichment concurrency (min 1, max 16)
--yes	-y	flag		Skip confirmation prompt

Discovers tracks, shows a summary with cache/pending/error counts, prompts for confirmation, then runs all three providers concurrently with progress bars and graceful Ctrl+C. If Discogs auth is needed, it opens the browser flow automatically.

The analysis provider runs built-in Stratum analysis and Essentia when its optional Python environment is available. Bandcamp and MusicBrainz are not CLI hydrate providers; use their targeted MCP lookup and backfill paths instead.

The command drains and prints its final summary before exiting. A new provider, analysis, cache-write, or worker failure exits nonzero, as does Ctrl+C or any incomplete selected work. An all-cached/no-work run and declining the confirmation prompt remain successful.

Examples

# Hydrate everything (Discogs + Beatport + audio analysis)
reklawdbox hydrate

# Just audio analysis, 8 concurrent
reklawdbox hydrate --providers analysis -j 8

# Hydrate a specific playlist, skip confirmation
reklawdbox hydrate --playlist "Weekend Set" -y

# Only Discogs, only tracks added this year
reklawdbox hydrate --providers discogs --added-after 2026-01-01

# Only Discogs for a specific genre
reklawdbox hydrate --providers discogs --genre "Techno"

# Overnight run — max CPU, skip confirmation
reklawdbox hydrate --cpu overnight -y

Tip

hydrate --cpu overnight -y for unattended runs. ~1,000 tracks takes 30-60 min (enrichment) + 45-90 min (analysis). Use --cpu background (default) if using the machine at the same time.

---

analyze

Batch audio analysis. A focused alternative to hydrate --providers analysis with additional backend control.

reklawdbox analyze [options]

Flag	Short	Type	Default	Description
--playlist		string		Filter by playlist ID
--artist		string		Filter by artist (partial match)
--genre		string		Filter by genre (partial match)
--bpm-min		number		Minimum BPM
--bpm-max		number		Maximum BPM
--key		string		Filter by musical key
--label		string		Filter by label (partial match)
--path		string		Filter by file path (partial match)
--query		string		Search query matching title or artist
--added-after		date		ISO date
--added-before		date		ISO date
--rating-min		1-5		Minimum star rating
--max-tracks		integer	200	Max tracks to process
--no-skip-cached		flag		Re-analyze already-cached tracks
--stratum-only		flag		Skip Essentia, run stratum-dsp only
--cpu		preset	background	CPU scheduling: background (~50% cores, niced) or overnight (cores - 2)
--concurrency	-j	integer	auto	Override analysis concurrency (overrides --cpu preset, min 1, max 16)

Concurrency set by --cpu preset: background (~50% cores, nice 10), overnight (cores - 2). Cached analysis is validated against the analysis schema plus the canonical audio file identity (path, size, and modification time). Stratum additionally fingerprints the Rekordbox beat grid used for analysis, or a versioned no-grid fallback, so grid changes invalidate and recompute Stratum without invalidating Essentia.

The command drains and prints its final summary before exiting. A new analysis, cache-write, or worker failure exits nonzero, as does Ctrl+C or any incomplete selected work. No matching tracks and all-cached/no-work runs remain successful.

Example

# Analyze all techno tracks, stratum-dsp only, 4 concurrent
reklawdbox analyze --genre Techno --stratum-only -j 4

# Overnight run — max CPU
reklawdbox analyze --cpu overnight

---

read-tags

Read native metadata tags from audio files.

reklawdbox read-tags <paths...> [options]

Flag	Short	Type	Default	Description
<paths>		string[]	required	Audio files or directories
--fields		list	all	Comma-separated field filter
--recursive	-r	flag		Recursively scan directories for audio files
--cover-art		flag		Include cover art metadata
--json		flag		Output as JSON (JSONL for multiple files)

Without --recursive, directories are scanned one level deep. WAV files show both ID3v2 and RIFF INFO layers.

Example

# Read all tags from a file
reklawdbox read-tags ~/Music/track.flac

# JSON output, only artist and title
reklawdbox read-tags ~/Music/*.flac --fields artist,title --json

---

write-tags

Write or delete metadata tags on audio files.

reklawdbox write-tags <path> [options]

Flag	Type	Default	Description
<path>	string	required	Audio file to write to
--artist	string		Set artist
--title	string		Set title
--album	string		Set album
--album-artist	string		Set album artist
--genre	string		Set genre
--year	string		Set year
--track	string		Set track number
--disc	string		Set disc number
--comment	string		Set comment
--publisher	string		Set publisher
--bpm	string		Set BPM
--key	string		Set musical key
--composer	string		Set composer
--remixer	string		Set remixer
--dry-run	flag		Preview changes without writing; WAV output is grouped by tag layer
--wav-targets	list	both	WAV targets: id3v2, riff_info
--json-input	flag		Read tags from stdin as JSON
--json	flag		Output as JSON

Set a field to "" to delete it. Use --dry-run to preview. For WAV files, human-readable previews show separate ID3v2 and RIFF INFO headings for the requested targets, including an indented No changes. when a layer is already up to date.

Examples

# Set genre and preview
reklawdbox write-tags track.flac --genre "Techno" --dry-run

# Delete the comment field
reklawdbox write-tags track.flac --comment ""

# Batch update via JSON stdin
echo '{"artist": "Artist", "genre": "House"}' | reklawdbox write-tags track.flac --json-input

# Write to specific WAV layers
reklawdbox write-tags track.wav --artist "Artist" --wav-targets riff_info

---

extract-art

Extract embedded cover art from an audio file.

reklawdbox extract-art <path> [options]

Flag	Type	Default	Description
<path>	string	required	Audio file
--output	string	cover.{ext}	Output path
--picture-type	string	front_cover	Exact accepted picture type; unknown values are rejected
--json	flag		Output as JSON

Example

reklawdbox extract-art track.flac --output artwork.jpg

Accepted cover-art picture types

Both cover-art commands accept these exact, case-sensitive, untrimmed values: other, icon, other_icon, front_cover, cover_front, back_cover, cover_back, leaflet, media, lead_artist, artist, conductor, band, composer, lyricist, recording_location, during_recording, during_performance, screen_capture, bright_fish, illustration, band_logo, and publisher_logo. cover_front and cover_back are compatibility aliases for the canonical front_cover and back_cover names. Unknown values are rejected. When a valid requested extraction type is absent, extraction falls back to the first embedded picture.

---

embed-art

Embed cover art into one or more audio files.

reklawdbox embed-art <image> <targets...> [options]

Flag	Type	Default	Description
<image>	string	required	Image file (JPEG or PNG)
<targets>	string[]	required	Audio files to embed into
--picture-type	string	front_cover	Exact accepted picture type; unknown values are rejected
--json	flag		Output as JSON

Example

# Embed cover art into multiple files
reklawdbox embed-art cover.jpg track1.flac track2.flac track3.flac

---

setup

Installs Essentia into a managed Python venv for audio analysis. Finds Python 3.9+, creates a venv at ~/.local/share/reklawdbox/essentia-venv, and installs Essentia via pip.

reklawdbox setup [options]

Flag	Short	Description
--broker		Configure a custom Discogs broker URL and token (self-hosted brokers only)
--yes	-y	Accept defaults without prompting (only applies to --broker)

The --broker flag opens an interactive prompt for custom Discogs broker configuration, writing settings to ~/Library/Application Support/reklawdbox/config.toml. The default broker is preconfigured and needs no setup.

---

disconnect-broker

Clear the current Discogs broker session, forcing a fresh OAuth device auth flow on the next lookup_discogs call. The command removes that broker’s credential from macOS Keychain and its matching metadata from the internal state database selected by CRATE_DIG_STORE_PATH. It preserves unrelated enrichment and analysis caches, audit history and resolutions, saved presets, and calibration/profile statistics. The operation is targeted and idempotent, so it is safe to run when no matching session exists.

reklawdbox disconnect-broker