Command-Line Interface (CLI)

• 1: navidrome artwork
• 2: navidrome backup
• 3: navidrome doctor
• 4: navidrome inspect
• 5: navidrome missing
• 6: navidrome plugin
• 7: navidrome pls
• 8: navidrome scan
• 9: navidrome search
• 10: navidrome service
• 11: navidrome user

navidrome --help

navidrome <command> --help
navidrome <command> <subcommand> --help

navidrome -c /etc/navidrome/navidrome.toml --nobanner user list

# Show CLI help
docker compose run --rm navidrome --help

# Run a full scan
docker compose run --rm navidrome scan --full

# List users
docker compose run --rm navidrome user list

docker compose exec navidrome navidrome user list

docker run --rm -it \
  --user $(id -u):$(id -g) \
  -v /path/to/music:/music:ro \
  -v /path/to/data:/data \
  --env-file /path/to/navidrome.env \
  -e ND_CONFIGFILE=/data/navidrome.toml \
  deluan/navidrome:latest \
  user list

1 - navidrome artwork

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.

reprocess skips media files. A track’s artwork comes only from its embedded tags, and Navidrome reads them at scan time or the first time someone views the track. Media files still end up in the queue, so cancel can remove them.

Disc artwork has no stored state. Navidrome resolves it on every request and caches the result by content, so refresh has nothing to clear.

explain accepts playlists and radios. It shows their stored state and queue row, but they have no priority chain to walk.

Subcommands

artwork status

Shows the queue by kind and priority, how many items use each source, how many items have no image, and whether artwork settings changed since the last full reprocess.

navidrome artwork status

Flags

This subcommand has no flags.

Output

The Absent block splits items with no image in two. NO IMAGE counts items where every candidate answered and none had an image. FAILED counts items where Navidrome ran out of retries, for example because a provider kept timing out. Those are the best candidates for another try.

Absent (resolved, no image found)
  KIND      NO IMAGE  FAILED
  artist    212       37
  album     48        0

Navidrome retries neither group by itself. artwork reprocess --source absent retries both, and --source failed retries only the ones that gave up.

The Config block compares a fingerprint of six settings: CoverArtPriority, ArtistArtPriority, ArtistImageFolder, Agents, EnableExternalServices, and EnableM3UExternalAlbumArt.

Config
  State:                fingerprint changed — stored artwork keeps the old resolution; run 'artwork reprocess --all' to apply it
  Stored fingerprint:   7e537a22febc07d3
  Current fingerprint:  c49003a68a82ee68
  Fingerprint inputs (changing any of these makes the stored artwork stale):
    CoverArtPriority:           cover.*, folder.*, front.*, embedded, external
    ...

Changing one of these settings does not update artwork that is already stored. Stored artwork keeps what the old settings found, and Navidrome logs a warning at startup. Run artwork reprocess --all to apply the new settings to the whole library. A full reprocess with no filters also saves the new fingerprint, and the warning goes away.

artwork explain

Shows why one item got the artwork it has. The output has the item’s stored artwork state, its queue row, the settings that decide its artwork, and the priority chain. The chain shows which candidate won and why each one above it lost.

navidrome artwork explain [<kind>] <id> [--live]

You can name the item three ways. Use a bare ID, a full artwork ID such as al-<id>, or a <kind> <id> pair. For a bare ID, Navidrome looks up the kind itself, so artists, albums, playlists, radios, and media files don’t need <kind>. Discs have no table to look up, so a disc always needs its kind. A disc artwork ID is the album ID and the disc number, joined by a colon.

By default, explain prints the chain the server recorded the last time it resolved the item. That is what really happened, and reading it costs no new lookups. The header shows when Navidrome recorded it. --live walks the chain again right now, and the header reads Chain (walked now). Discs have no stored state, so explain always walks a disc’s chain on the spot.

Flags

Examples

# Explain an album by its bare ID
navidrome artwork explain 6XTD9naRGpIrZLoA99pH1r

# The same album, by its full artwork ID
navidrome artwork explain al-6XTD9naRGpIrZLoA99pH1r

# Walk the chain again now
navidrome artwork explain al 6XTD9naRGpIrZLoA99pH1r --live

# Explain disc 2 of an album
navidrome artwork explain dc 6XTD9naRGpIrZLoA99pH1r:2

Output

Item
  Kind:  album (al)
  ID:    6XTD9naRGpIrZLoA99pH1r
  Name:  OK Computer

Stored
  Source:        folder
  Hash:          fa90ba01c3d4e5f6
  Source path:   /music/Radiohead/OK Computer/cover.jpg
  Attempted at:  2026-04-19T03:22:11Z

Queue
  (not queued)

Config
  CoverArtPriority:  cover.*, folder.*, front.*, embedded, external
  Agents:            lastfm, spotify

Chain (recorded 2026-04-19T03:22:11Z)
  CANDIDATE  OUTCOME  DETAIL
  cover.*    hit      /music/Radiohead/OK Computer/cover.jpg

Result
  resolved from folder

The Chain table uses these outcomes:

Watch for unreadable. It points to a damaged file you can fix, while miss means nothing was there. Stored state alone can’t tell the two apart.

When resolution fails, the Queue block shows why. While Navidrome is still retrying, Last attempt failed lists the steps of the latest attempt. After it stops retrying, Gave up after lists the steps of the final one. If Navidrome found a candidate but could not process it, or an external lookup failed, Result says indeterminate rather than not resolved. Nothing proved the item has no artwork, and a retry may still find some.

Older Navidrome versions did not record chains, and explain tells you when it resolved an item before recording started. Run it with --live to see the chain. A live run is also worth comparing against Stored. If stored says external:lastfm and the live walk resolves from folder, the stored state is stale. Run artwork refresh to fix it.

artwork refresh

Clears the stored artwork state of each item and queues it at the highest priority. Admins can do the same for one album or artist in the web UI, with Refresh Metadata in the context menu.

navidrome artwork refresh [<kind>] <id>...

IDs work the same as in explain. Use bare IDs, full artwork IDs like al-<id>, or one <kind> followed by several IDs of that kind. Bare and full IDs carry their own kind, so you can mix kinds in one call. If Navidrome can’t find an ID, it reports the ID, skips it, and refreshes the rest.

The old state is gone, so the item shows a placeholder until Navidrome resolves it again.

Flags

This subcommand has no flags.

Examples

# Refresh one album by its bare ID
navidrome artwork refresh 6XTD9naRGpIrZLoA99pH1r

# Refresh an album and an artist in one call
navidrome artwork refresh al-6XTD9naRGpIrZLoA99pH1r ar-1dfeR4HaWDbWqFHLkxsg1d

# Refresh two albums
navidrome artwork refresh al 1dfeR4HaWDbWqFHLkxsg1d 6XTD9naRGpIrZLoA99pH1r

artwork reprocess

Queues artwork in bulk. reprocess is the only way to retry absent artwork, because Navidrome never goes back to an item with no image by itself. It is also how you apply an artwork setting change to the whole library. See artwork status.

navidrome artwork reprocess [--kind ...] [--source ...] [--all] [--dry-run] [-y]

You must pass --kind, --source, or --all. Without one, the command fails, so you can’t resolve the whole library again by accident. --source alone covers every kind. If you name a source that no item uses, the command fails and lists the sources in use.

Before it queues anything, the command prints a breakdown and an estimate of external lookups, then asks you to confirm. A running server works through queued items in the background. A stopped server starts on them at its next startup.

Flags

failed selects absent items where Navidrome gave up after its retries.

Examples

# Preview artists that use Last.fm images now
navidrome artwork reprocess --kind ar --source external:lastfm --dry-run

# Retry only the items that gave up, for example after a provider outage
navidrome artwork reprocess --source failed

# Retry every item that has no image
navidrome artwork reprocess --source absent

# Apply a changed artwork setting to the whole library
navidrome artwork reprocess --all

artwork cancel

Removes pending artwork work from the queue. reprocess fills the queue, and cancel empties it.

navidrome artwork cancel [--kind ...] [--priority ...] [--all] [--dry-run] [-y]

You must pass --kind, --priority, or --all. Like reprocess, the command prints a breakdown and asks you to confirm before it deletes anything.

Use --priority to call off a bulk job and keep everything else. reprocess queues items at recheck priority, and on a large library that can mean tens of thousands of external lookups. Cancel recheck to stop that job. Items you refreshed by hand sit at bump, so they stay queued.

Queue priorities, highest first:

Flags

Examples

# See what is queued at recheck priority
navidrome artwork cancel --priority recheck --dry-run

# Call off a bulk reprocess and keep manual refreshes queued
navidrome artwork cancel --priority recheck

# Empty the queue
navidrome artwork cancel --all --yes

2 - navidrome backup

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.

All commands also accept the global flags.

Subcommands

backup create

Makes a backup of the database. This command doesn’t delete old backups, even when you have more than Backup.Count. Run backup prune for that.

navidrome backup create [-d <folder>]

Flags

Examples

# Back up to the folder in Backup.Path
navidrome backup create

# Back up to another folder
navidrome backup create --backup-dir /mnt/backups/navidrome

backup prune

Deletes old backups and keeps the newest ones. It only looks at files named like navidrome_backup_<date>_<time>.db, and leaves other files in the folder alone.

navidrome backup prune [-d <folder>] [-k <count>] [-f]

By default, prune keeps as many backups as Backup.Count. If the number to keep is 0, prune deletes every backup. It asks you to type YES first, unless you pass --force.

Flags

Examples

# Keep the number of backups set in Backup.Count
navidrome backup prune

# Keep only the newest 7 backups
navidrome backup prune --keep-count 7

# Delete all backups without a prompt
navidrome backup prune --keep-count 0 --force

backup restore

Replaces the current database with a backup. It asks you to type YES first, unless you pass --force.

navidrome backup restore --backup-file <file> [-f]

If --backup-file is a file name or a relative path, the command looks for it in the Backup.Path folder. An absolute path works from anywhere.

Flags

Examples

# Restore a backup from the Backup.Path folder
navidrome backup restore --backup-file navidrome_backup_2026.04.01_04.00.00.db

# Restore a backup from another folder
navidrome backup restore --backup-file /mnt/backups/navidrome/navidrome_backup_2026.04.01_04.00.00.db

# With Docker Compose, stop the server first
docker compose stop navidrome
docker compose run --rm navidrome backup restore --backup-file navidrome_backup_2026.04.01_04.00.00.db
docker compose start navidrome

3 - navidrome doctor

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.

• Integrity check. Looks for corruption in the database file. If the damage is only in the search index, doctor tells you to run navidrome search rebuild. Damage anywhere else can’t be fixed automatically. Restore a backup with navidrome backup restore, or try SQLite’s .recover command.
• Foreign key check. Looks for orphaned rows, which point to rows that no longer exist. This is not corruption. navidrome scan -f clears some of them in library data, and you have to delete the rest by hand.

The integrity check stops after a fixed number of problems. When it hits that limit, the damage may be bigger than the list shows, and doctor won’t suggest a search index rebuild.

Output

A healthy database looks like this:

Checking database integrity...
Integrity check passed.
Checking foreign keys...
Foreign key check passed.
Database is healthy.

doctor exits with status 1 when a check finds a problem or can’t finish, so you can use it in scripts.

4 - navidrome inspect

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.

Flags

pretty prints a text block for each file, with the raw and mapped tags in TOML. json prints everything on one line, and jsonindent prints indented JSON.

Examples

# Print the tags of one file as indented JSON
navidrome inspect "/music/Artist/Album/01 Track.flac"

# Print the tags of every MP3 in a folder, as YAML
navidrome inspect --format yaml /music/Artist/Album/*.mp3

# Easy-to-read output
navidrome inspect --format pretty "/music/Artist/Album/01 Track.flac"

# Inspect a file with Docker Compose. Use the path inside the container
docker compose run --rm navidrome inspect "/music/Artist/Album/01 Track.flac"

Notes

inspect skips files that are not audio files, and files it can’t read. It logs a warning for each one and goes on with the rest.

5 - navidrome missing

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.

See Missing Files for why files go missing, how to review them in the web UI, and how to purge them for good.

Usage

navidrome missing <subcommand> [flags]

All commands also accept the global flags.

Subcommands

missing list

Lists all files marked as missing. The CSV output has these columns: id, library id, title, album, artist, and path.

navidrome missing list [-f csv|json]

Flags

Examples

# List missing files as CSV
navidrome missing list

# List missing files as JSON
navidrome missing list --format json

missing fix

Moves the data of a missing file onto an existing file.

navidrome missing fix <missing> <target>

The first argument is the missing file. The second is the file that gets its data. Each argument can be a media file ID, a library-relative path, or a libraryID:path pair. Use an ID or a libraryID:path pair when the same path exists in more than one library.

Flags

This subcommand has no flags.

Examples

# Remap by library-relative path
navidrome missing fix "Rock/Old Album/track01.mp3" "Rock/New Album/track01.mp3"

# Remap by media file ID
navidrome missing fix 3Unsdwsei9i2ZvRtFKRfwA 7KpqZmXe4Ab2NvTuGHRcxQ

# Pick the library with a libraryID:path pair
navidrome missing fix 2:"Podcasts/ep01.mp3" 2:"Podcasts/episode-01.mp3"

6 - navidrome plugin

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.

Subcommands

plugin list

Lists installed plugins.

navidrome plugin list [-f table|csv|json]

Flags

Examples

# List installed plugins as a table
navidrome plugin list

# List installed plugins as JSON
navidrome plugin list -f json

plugin info

Shows details for an installed plugin or a .ndp package file. An argument that ends in .ndp is a package file. Anything else is the ID of an installed plugin.

navidrome plugin info <id|file.ndp> [-f text|json]

Flags

Examples

# Show details for an installed plugin
navidrome plugin info my-plugin

# Check a downloaded package before you install it
navidrome plugin info ./my-plugin-1.2.0.ndp

plugin validate

Checks the manifest of an installed plugin or a .ndp package file. For an installed plugin, it also checks the stored configuration when one exists. It reads the argument the same way as info.

navidrome plugin validate <id|file.ndp>

Flags

This subcommand has no flags.

Examples

# Check an installed plugin
navidrome plugin validate my-plugin

# Check a package file
navidrome plugin validate ./my-plugin-1.2.0.ndp

plugin enable

Enables an installed plugin.

navidrome plugin enable <id>

Flags

This subcommand has no flags.

Examples

navidrome plugin enable my-plugin

plugin disable

Disables an installed plugin.

navidrome plugin disable <id>

Flags

This subcommand has no flags.

Examples

navidrome plugin disable my-plugin

plugin edit

Changes a plugin’s config, the users and libraries it can access, and whether it can write to libraries. Pass at least one flag. The flags come in pairs, and you can’t use both flags of a pair in one call.

navidrome plugin edit <id> [flags]

Flags

The pairs are --config and --config-file, --users and --all-users, --libraries and --all-libraries, and --write-access and --no-write-access.

Examples

# Set a plugin's config
navidrome plugin edit my-plugin --config '{"apiKey":"abc123"}'

# Read the config from stdin
cat config.json | navidrome plugin edit my-plugin --config-file -

# Give access to all users and let the plugin write to libraries
navidrome plugin edit my-plugin --all-users --write-access

# Limit the plugin to two libraries
navidrome plugin edit my-plugin --libraries 1,2

plugin rescan

Looks in the plugins folder again and picks up plugins you added or removed. The folder comes from Plugins.Folder, which defaults to the plugins folder inside DataFolder.

navidrome plugin rescan

Flags

This subcommand has no flags.

Examples

# Pick up a new .ndp file you copied into the plugins folder
navidrome plugin rescan

7 - navidrome pls

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.

All commands also accept the global flags.

Flags

These flags are for pls with no subcommand.

Examples

# Print a playlist to stdout
navidrome pls --playlist "Road Trip Mix"

# Write a playlist to a file
navidrome pls --playlist "Road Trip Mix" --output ./road-trip.m3u8

Subcommands

pls list

Lists playlists, sorted by owner. The CSV output has these columns: playlist id, playlist name, owner id, owner name, and public.

navidrome pls list [-u <user>] [-f csv|json]

Flags

Examples

# List all playlists as CSV
navidrome pls list

# List the playlists of one user as JSON
navidrome pls list --user alice --format json

pls export

Exports one playlist or many playlists to M3U files.

navidrome pls export [-p <playlist>] [-u <user>] [-o <folder>]

What it does depends on the flags you pass:

• With --playlist and no --output, it prints that playlist to stdout.
• With --playlist and --output, it writes that playlist to a file in the output folder.
• Without --playlist, it writes every playlist to the output folder. Add --user to export only the playlists of one user. --output is required here.

--output is a folder, and the folder must already exist. This is different from pls --output, which takes a file. Each file gets the name of its playlist, such as Road Trip Mix.m3u. If two playlists have the same name, Navidrome adds the first 6 characters of the playlist ID to the file name, such as Road Trip Mix_3Unsdw.m3u.

Flags

Examples

# Export all playlists to a folder
navidrome pls export --output ./playlists

# Export the playlists of one user
navidrome pls export --user alice --output ./playlists

# Export one playlist to a folder
navidrome pls export --playlist "Road Trip Mix" --output ./playlists

pls import

Imports one or more M3U files as playlists. Navidrome matches each entry in the file to a track in your library. For each file, it prints how many tracks matched and how many it didn’t find. If one file fails, the command prints the error and goes on with the rest.

navidrome pls import [-u <user>] [--sync] <file> [<file>...]

By default, the first admin user owns the imported playlists. Pass --user to pick another owner.

A synced playlist follows its M3U file. You can’t edit its tracks in Navidrome. If the file is in your library, the scanner updates the playlist when the file changes. Without --sync, the playlist keeps the tracks from the import, and you can edit them.

Flags

Examples

# Import one file
navidrome pls import ./road-trip.m3u

# Import many files for one user
navidrome pls import --user alice ./playlists/*.m3u

# Import a playlist from the library and keep it synced with the file
navidrome pls import --sync "/music/Playlists/Favorites.m3u"

# With Docker Compose, mount the files so the container can read them
docker compose run --rm -v ./playlists:/playlists navidrome pls import /playlists/road-trip.m3u

8 - navidrome scan

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

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

Examples

# Scan for changes
navidrome scan

# Full scan
navidrome scan --full

# Scan only two folders, in two libraries
navidrome scan -t 1:Music/Rock -t 2:Audiobooks

# Read the folders to scan from a file
navidrome scan --target-file ./scan-targets.txt

# Full scan with Docker Compose
docker compose run --rm navidrome scan --full

Scan targets

A target is a library ID and a folder in that library, joined by a colon. The folder path is relative to the root folder of the library. For example, 1:Music/Rock is the Music/Rock folder in library 1.

To find library IDs, run navidrome user list. Its libraries column shows each library as id:path. See Multi-Library for how libraries work.

A target file has one target on each line. The command skips empty lines. If you pass both --target-file and --target, the command uses only the file.

9 - navidrome search

The search command maintains the full-text search index.

Usage

navidrome search <subcommand> [flags]

All commands also accept the global flags.

Subcommands

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 search rebuild [-f]

Use it in two cases:

• navidrome doctor reports that the corruption is limited to the search index.
• Search misses items that are in your library. doctor can’t detect an index that is out of sync but not corrupt, so a rebuild is the thing to try.

Without --force, the command asks you to type YES to continue.

Flags

Examples

# Check the database, then rebuild a corrupted search index
navidrome doctor
navidrome search rebuild

# With Docker Compose, stop the server first
docker compose stop navidrome
docker compose run --rm navidrome search rebuild
docker compose start navidrome

10 - navidrome service

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.

All commands also accept the global flags.

Subcommands

service install

Installs Navidrome as a system service. Before it installs, it prints the working directory, music folder, data folder, and log location the service will use. You usually need root or Administrator rights to install a service.

navidrome service install [-u <user>] [-w <folder>] [-c <config file>]

If you pass --configfile, the service uses that config file. Without it, the service looks for navidrome.toml in its working directory. The service manager restarts Navidrome if it fails. Logs go to the data folder, unless you set LogFile.

On Linux, the systemd unit also reads environment variables from /etc/sysconfig/navidrome if that file exists.

Flags

Examples

# Install the service with a config file, run by the navidrome user
sudo navidrome service install --user navidrome --configfile /etc/navidrome/navidrome.toml

# Install with a different working directory
sudo navidrome svc install --working-directory /var/lib/navidrome

service uninstall

Removes the service from the service manager. Your music and data folders stay as they are.

navidrome service uninstall

Flags

This subcommand has no flags.

Examples

sudo navidrome svc uninstall

service start

Starts the service.

navidrome service start

Flags

This subcommand has no flags.

Examples

sudo navidrome svc start

service stop

Stops the service. Navidrome gets 10 seconds to shut down cleanly.

navidrome service stop

Flags

This subcommand has no flags.

Examples

sudo navidrome svc stop

service status

Prints whether the service is Running, Stopped, or Unknown.

navidrome service status

Flags

This subcommand has no flags.

Examples

navidrome svc status

service execute

Runs Navidrome in the foreground as a service. The service manager runs this command to start Navidrome, so you don’t need it. To run Navidrome in the foreground yourself, run navidrome.

navidrome service execute

Flags

This subcommand has no flags.

11 - navidrome user

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

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.

navidrome user create --username <username> [flags]

Without --library-ids, the user can access all libraries. Admins can always access all libraries, so the command ignores --library-ids when you pass --admin. If a library ID doesn’t exist, the command fails and creates nothing.

Flags

Examples

# Create an admin user
navidrome user create --username alice --email alice@example.com --admin

# Create a regular user who can access libraries 1 and 3 only
navidrome user create --username bob --name "Bob Smith" --library-ids 1,3

user edit

Changes a user. Find the user by username or ID, then pass the flags for what you want to change. If nothing changes, the command says so.

navidrome user edit --user <username-or-id> [flags]

Some flags come in pairs, and you can’t use both flags of a pair in one call. The pairs are --set-admin and --set-regular, --email and --remove-email, and --name and --remove-name.

--set-admin gives the user access to all libraries. --set-regular keeps the libraries the user has, so add --library-ids to limit them.

Flags

Examples

# Make an admin a regular user
navidrome user edit --user alice --set-regular

# Change a password. The command asks for the new one
navidrome user edit --user alice --set-password

# Limit a user to libraries 1 and 2
navidrome user edit --user bob --library-ids 1,2

user list

Lists all users. The CSV output has these columns: user id, username, user’s name, user email, admin, created at, updated at, last access, last login, and libraries. The libraries column lists each library as id:path, separated by |.

navidrome user list [-f csv|json]

Flags

Examples

# List users as CSV
navidrome user list

# List users as JSON
navidrome user list --format json

user delete

Deletes a user. The command doesn’t ask for confirmation. It won’t delete the last user.

navidrome user delete --user <username-or-id>

Flags

Examples

navidrome user delete --user alice