Command-Line Interface (CLI)

Navidrome has a built-in CLI for administration, maintenance, and troubleshooting. Each command has its own page. This page covers what the commands share.

Quick start

Show the list of commands:

navidrome --help

Show help for one command or subcommand:

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

If you run navidrome with no command, it starts the server.

Commands

Global flags

Every command accepts these flags.

Commands read the same config file and ND_ environment variables as the server. Run them with the same settings as your server, or they will look at a different database. The server also takes flags such as --port and --address. Run navidrome --help to see them, and see Configuration Options for every setting.

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

Running the CLI in Docker

If Navidrome runs in a container, run CLI commands in a container too. That way they use the same /data, /music, config file, and environment variables as your server.

Docker Compose

Use docker compose run with the name of your Navidrome service. It is usually navidrome:

# 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

To run a command in the container that is already running, use docker compose exec. Put the navidrome binary name before the command:

docker compose exec navidrome navidrome user list

Docker run

Start a one-off container with the same image tag, volumes, and environment variables as your main Navidrome container:

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

-it gives the command a terminal. Commands that ask for input need it, such as user create, which asks for a password.

Notes and best practices

• Flags change between releases. Run --help to see the flags of the version you have.
• In scripts, pass --configfile so the command reads the config you expect.
• Stop Navidrome before you run backup restore or search rebuild.
• backup restore, backup prune, and missing fix can’t be undone. Check the paths and IDs you pass, and run navidrome backup create first.