Command-Line Interface (CLI) on Navidrome

navidrome artwork

Sun, 13 Sep 2026 00:00:00 +0000

The artwork commands tell you why a cover is wrong or an artist image is missing, without opening the database. They also queue artwork to resolve again, one item at a time or in bulk. See Artwork resolution for how Navidrome picks an image.

Usage

navidrome artwork <subcommand> [flags]

All commands also accept the global flags.

Artwork kinds

Each kind of artwork has a short code. Not every subcommand accepts every kind.

navidrome backup

Sun, 13 Sep 2026 00:00:00 +0000

The backup commands make a copy of the Navidrome database, delete old copies, and restore a copy. Navidrome can also make backups on a schedule. See Automated Backup.

Backups go to the folder in the Backup.Path setting. Each backup file has a name like navidrome_backup_2026.04.01_04.00.00.db, with the date and time it was made.

Usage

navidrome backup <subcommand> [flags]

The alias bkp works too, so navidrome bkp create is the same as navidrome backup create.

navidrome doctor

Sun, 13 Sep 2026 00:00:00 +0000

The doctor command checks the database for problems. It only reads the database and never changes your data. Run it when Navidrome logs errors such as database disk image is malformed, or when every scan fails.

Usage

navidrome doctor

Flags

doctor has no flags of its own. It accepts the global flags.

Examples

# Check the database
navidrome doctor

# Stop a script when the database has problems
navidrome doctor || exit 1

# Check the database with Docker Compose
docker compose run --rm navidrome doctor

What it checks

doctor runs two checks.

navidrome inspect

Sun, 13 Sep 2026 00:00:00 +0000

The inspect command prints the tags of one or more music files, the way Navidrome reads them. Use it when an album shows up split in two, or a tag you set doesn’t appear in Navidrome. For each file it prints the raw tags stored in the file and the mapped tags Navidrome uses. See Tagging for how Navidrome maps tags.

Usage

navidrome inspect [flags] <file> [<file>...]

All commands also accept the global flags.

navidrome missing

Sun, 13 Sep 2026 00:00:00 +0000

The missing commands list files marked as missing, and remap a missing file onto an existing one.

The scanner marks a file missing when it no longer finds it on disk. When you rename or move a file, the scanner normally reconnects it and carries over play counts, ratings, starred status, and bookmarks. If the scanner can’t match the two files, the old entry stays missing and the new file starts with no history. missing fix does that remap by hand.

navidrome plugin

Sun, 13 Sep 2026 00:00:00 +0000

The plugin commands list, check, configure, enable, and disable plugins. They do the same things as the plugin screens in the web UI. See Plugins for how the plugin system works.

Usage

navidrome plugin <subcommand> [flags]

All commands also accept the global flags.

Commands that work with installed plugins need the plugin system enabled. Plugins.Enabled is on by default. You can still use plugin info and plugin validate on a .ndp package file when the plugin system is disabled.

navidrome pls

Sun, 13 Sep 2026 00:00:00 +0000

The pls commands list playlists, export them to M3U files, and import M3U files as playlists.

Navidrome also imports M3U files it finds in your library when it scans. You don’t need pls import for those. See AutoImportPlaylists and PlaylistsPath in Configuration Options.

Usage

navidrome pls --playlist <name-or-id> [--output <file>]
navidrome pls <subcommand> [flags]

pls with no subcommand exports one playlist. pls export does the same, and it can also export many playlists at once.

navidrome scan

Sun, 13 Sep 2026 00:00:00 +0000

The scan command scans your music library for new, changed, and removed files. Use it to start a scan from a script, to force a full scan, or to scan only some folders.

Usage

navidrome scan [flags]

All commands also accept the global flags.

Flags

Flag	Default	Description
`-f, --full`	`false`	Check all folders and ignore modification times
`-t, --target`		Scan only this folder, as a `libraryID:folderPath` pair. Repeatable
`--target-file`		File with folders to scan, one `libraryID:folderPath` pair per line

Navidrome also has a --subprocess flag. The server uses it to run scans, so don’t pass it yourself.

navidrome search

Sun, 13 Sep 2026 00:00:00 +0000

The search command maintains the full-text search index.

Usage

navidrome search <subcommand> [flags]

All commands also accept the global flags.

Subcommands

Subcommand	Description
`rebuild`	Delete the search index and build it again from the library data

`search rebuild`

Deletes the full-text search index and builds it again from your library data. The index only holds copies of data stored elsewhere in the database, so you lose nothing. Navidrome checks the new index before it saves it.

navidrome service

Sun, 13 Sep 2026 00:00:00 +0000

The service commands install Navidrome as a service in your OS service manager, then start, stop, and check it. The service manager is systemd on most Linux systems, launchd on macOS, and the Service Control Manager on Windows. navidrome service --help shows the one your system uses.

The installation guides for Linux, macOS, and Windows show the full setup.

Usage

navidrome service <subcommand> [flags]

The alias svc works too, so navidrome svc status is the same as navidrome service status.

navidrome user

Sun, 13 Sep 2026 00:00:00 +0000

The user commands create, edit, list, and delete Navidrome users.

These commands need at least one admin user in the database. On a new install, create the first admin in the web UI.

Usage

navidrome user <subcommand> [flags]

All commands also accept the global flags.

Subcommands

Subcommand	Alias	Description
`create`	`c`	Create a user
`edit`	`e`	Change a user
`list`		List users
`delete`	`d`	Delete a user

`user create`

Creates a user. The command asks for the password twice. Press Enter with no password to cancel. There is no flag for the password, so run the command in a terminal. With docker run, add -it.