moodwavev2.0.0

Platform setup guides, the full command reference, and everything needed to go from install to a working terminal music companion.

Platform setup

Windows, macOS & Linux

Install

Install (PowerShell)

PS>irm https://raw.githubusercontent.com/Boredooms/Moodwave-CLI/main/cli/scripts/install.ps1 | iex

Audio backend (optional)

mpv (recommended)

PS>winget install mpv

ffplay (ffmpeg)

PS>winget install ffmpeg

File locations

Config file:%APPDATA%\moodwave\config.json
Cache directory:%LOCALAPPDATA%\moodwave\cache\

Moodwave also ships a native PresentationCore/Media Foundation audio backend, so it can play streams out of the box even without mpv or ffmpeg installed — run moodwave doctor to confirm which backend was picked.

Verify everything is working after install:

PS>moodwave doctor

Installation & user guide

Command reference

Every moodwave subcommand, grouped by what you're trying to do. Run moodwave --help anytime for the same list in your terminal.

Getting started
  • moodwave init

    Create config file and cache directories. Run once after install.

  • moodwave doctor

    Diagnose terminal, config, audio backends, and music source connectivity.

  • moodwave

    Launch the interactive TUI — scan, search, play, and manage playlists.

  • moodwave update

    Check for and install the latest release in place. Also runs automatically in the TUI.

Mood & playback
  • moodwave scan [path]

    Analyze the repository and infer a coding mood from language mix, TODOs, git churn, and structure.

  • moodwave mood

    Show the last detected mood profile, confidence, and music traits without re-scanning.

  • moodwave play

    Find and stream music matching the current mood. Runs a scan first if none exists.

  • moodwave search <query>

    Search YouTube directly and pick a track to play.

  • moodwave next

    Advance the recommendation queue to the next candidate.

  • moodwave queue

    Show the current recommendation queue and playing position.

Customization
  • moodwave theme <name>

    Switch the visual color theme (7+ presets — Midnight, Dracula, Nord, Tokyo Night, and more).

  • moodwave visual <mode>

    Switch the terminal visualizer — spectrum, fire, matrix, plasma, aurora, and 15+ others.

  • moodwave config

    View the resolved configuration as JSON, or edit it directly.

  • moodwave source

    List configured music sources and their live health status.

Diagnostics
  • moodwave status

    Show version, config paths, last mood, and playback state.

  • moodwave doctor

    Full diagnostic pass with a one-key auto-fix for missing audio backends.

Environment variables
MOODWAVE_THEMEVisual theme ID
MOODWAVE_VISUALVisual mode
MOODWAVE_NO_COLOR=1Disable ANSI color
MOODWAVE_NO_ANIMATION=1Disable animation
MOODWAVE_BACKENDForce a specific audio backend
MOODWAVE_VOLUMEVolume, 0–100
MOODWAVE_DEBUG=1Enable debug logging
JAMENDO_CLIENT_IDEnable the Jamendo source
Full docs on GitHub ↗