CLI Reference

Microgamma ships two executables: the Microgamma desktop app, and mg, a companion CLI that handles configuration, login, and library scanning. This page lists every mg command and flag. Add --help to any command to print its usage.

mg setup

Interactive first-run wizard — walks through device name, music folder, login, and an initial scan in a single pass. The fastest way to get a new install running.

mg setup

mg login

Starts a device-code login. Prints a URL and a short code — open the URL in any browser, enter the code, and approve. The access token is saved to your config directory and reused on every launch.

mg login

mg logout

Removes the stored access token.

mg logout

mg config

With no options, prints the current device name, device ID, and music path. Pass options to set them:

mg config --device-name "Living Room" --music-path /home/user/Music

• -n, --device-name <name> — set the device name (how this machine shows up when you connect from another device).
• -m, --music-path <path> — set the folder Microgamma reads your music from.

mg scan [path]

Scans your music folder into the library. Uses the configured music path unless you pass a path argument. While the app is running it also watches the folder and picks up added or removed tracks automatically.

mg scan

• [path] — optional folder to scan instead of the configured music path.
• -r, --reset — rebuild the library database from scratch.

mg scan --reset

The app binary

The Microgamma executable only launches the app — all configuration, login, and scanning live in mg. Its one flag is --headless (run without a window). On Linux and inside containers, also pass --no-sandbox and run under a virtual framebuffer — see Headless Mode.

Microgamma --headless

Configuration & storage

Configuration lives in ~/.microgamma by default — the device config, settings, and your auth token, each stored as a small JSON file. Override the location with the MG_BASE_PATH environment variable:

MG_BASE_PATH=/srv/microgamma mg config

An absolute path is used as-is; a relative value is treated as a folder name under your home directory. Set the same value for both mg and Microgamma so they share one configuration.

Environment variables

There is no --version flag; use --help on any command for its usage.