Skip to content

Command line

This page lists every command of the musonic-server program, for administrators who run the server with Docker or as a standalone program.

What you need

Command What it does
musonic-server Starts the server (what Docker and your service manager run).
musonic-server scan [--full] Scans the music folder once, prints a summary, and exits.
musonic-server user add <name> [--admin] Creates an account.
musonic-server import-navidrome <navidrome.db> [--replace-playlists] [--new-ids] Imports playlists, likes, ratings and plays from a copy of a Navidrome database.
  • <name>: the username of the new account (1 to 64 characters).
  • <navidrome.db>: the path of a copy of Navidrome’s database file.

There is no --help option: an unknown command prints the list of commands and exits with an error.

Error: unknown command "--help" (expected: scan [--full], user add <name> [--admin], import-navidrome <navidrome.db>)

Every command reads the same configuration as the server: the environment variables (MUSONIC_DATA_DIR, MUSONIC_MUSIC_DIR…) and the TOML file named by MUSONIC_CONFIG. A command must therefore see the same data folder as the running server, otherwise it works on another, empty database.

Run the command inside the running container, from the folder that holds compose.yml:

Terminal window
docker compose exec musonic-server musonic-server <command>

The first musonic-server is the service name in compose.yml, the second one is the program. Inside the container the data folder is /data and the music folder /music, already set by the image.

Without a command, the program starts the server: it opens the database (applying the migrations it needs), starts the library watcher and the scheduled scans, and listens on bind (127.0.0.1:4533 by default; 0.0.0.0:4533 in the Docker image). Ctrl+C stops it cleanly.

When there is no account yet, the log says so: create the administrator in the web client, with POST /v1/setup, or with user add … --admin.

Scans the music folder once and prints what it did as JSON, then exits.

Option Effect
(none) Quick scan: only the folders and files that changed are read.
--full Reads every file again.
Terminal window
docker compose exec musonic-server musonic-server scan --full

Output fields: full, folders, folders_changed, files, files_read, files_missing, tracks_added, errors (list of messages), duration_ms.

It fails with no music folder configured (MUSONIC_MUSIC_DIR) when no music folder is set.

Creates an account. With --admin, the account is an administrator.

  1. Run the command with the new username.

    Terminal window
    docker compose exec musonic-server musonic-server user add <name> --admin

    With the standalone program: ./musonic-server user add <name> --admin, with the same environment as your service.

  2. Type the password, then press Enter.

    The prompt is Password for <name>:. The password needs at least 8 characters.

  3. Read the confirmation.

    created <name> (administrator) or created <name> (user).

Errors: usage: user add <name> [--admin] (no name), invalid username, the password needs at least 8 characters, this username is taken.

For your family and friends, prefer invitation links from the console: each person chooses their own name and password.

Imports from a copy of a Navidrome database: playlists, likes, ratings, play counts and plays. Passwords never come over.

Option Effect
(none) Tracks are matched by their file and keep their Navidrome ids, as do playlists, so what clients saved keeps working. Running it again adds nothing twice.
--new-ids Gives tracks and playlists new ids instead of Navidrome’s.
--replace-playlists Imports again the playlists imported before, replacing them.
  1. Create the accounts in Musonic first, with the same usernames as in Navidrome.

    Navidrome accounts without an account of the same name are skipped (listed in users_skipped).

  2. Make a consistent copy of Navidrome’s database into Musonic’s data folder.

    Terminal window
    sqlite3 -readonly /path/to/navidrome.db ".backup ./data/navidrome-copy.db"

    ./data is the folder mounted as /data in compose.yml. The Docker container is read-only apart from /data and /music.

  3. Scan the library, so the tracks can be matched by their files.

    Terminal window
    docker compose exec musonic-server musonic-server scan
  4. Run the import.

    Terminal window
    docker compose exec musonic-server musonic-server import-navidrome /data/navidrome-copy.db
  5. Restart the server.

    Terminal window
    docker compose restart musonic-server

    The import writes to the database from another process: a restart makes sure the server stops serving the answers it kept from before.

Output fields: users, users_skipped, files_matched, files_not_found, ids_kept, playlists, playlists_already_there, playlist_entries, playlist_entries_missing, track_annotations, album_annotations, artist_annotations, plays.

The full migration guide is in Coming from Navidrome.

Environment variables read by the commands

Section titled “Environment variables read by the commands”

All the configuration settings apply. These ones matter most on the command line:

Variable Used by Meaning
MUSONIC_DATA_DIR all Data folder (database musonic.db, caches, backups). Default data; /data in Docker.
MUSONIC_MUSIC_DIR serve, scan Music folder. /music in Docker.
MUSONIC_CONFIG all Path of a TOML configuration file.
MUSONIC_PASSWORD user add The password, instead of typing it.
MUSONIC_SECRET_KEY serve, user add Key (64 hex characters) that encrypts the passwords kept for Subsonic token sign-in. Default: secret.key in the data folder, created on first start.
RUST_LOG all Log level, for example info or debug (default info).