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.

---

hydrate

Batch enrichment + audio analysis. The recommended way to warm caches before classification or set building.

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.

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). Cache is invalidated when the analysis schema version changes.

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-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.

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	Picture type to extract
--json	flag		Output as JSON

Example

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

---

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	Picture type
--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 stored Discogs broker session, forcing a fresh OAuth device auth flow on the next lookup_discogs call. Removes the session token from both Keychain and the local SQLite store. Idempotent — safe to run when no session exists.

reklawdbox disconnect-broker