Command Line Tool

The Verdaccio CLI is your tool to start and stop the application.

Commands

verdaccio --listen 4000 --config ./config.yaml

Command	Default	Example	Description
--listen / -l	localhost:4873	7000	Protocol + host + port to listen on (see below)
--port / -p 7.x	localhost:4873	7000	Aliases of --listen
--config / -c	~/.config/verdaccio/config.yaml	./config.yaml	Location of the configuration file
--info / -i			Print local environment information
--mask 7.x	false		With --info, obscures file paths in the report
--version / -v			Show version information

--listen accepts port, host:port, proto://host:port, an IPv6 address in brackets and a unix:/path/to.sock socket — the same values as the listen key of the configuration file. Passing it on the command line overrides that key.

--port / -p and --mask exist on 7.x; on 6.x use --listen and --info.

Default config file location

When --config is not given, Verdaccio builds a list of candidate paths and uses the first one that already holds a file:

1. $XDG_CONFIG_HOME/verdaccio/config.yaml, where $XDG_CONFIG_HOME falls back to $HOME/.config — so ~/.config/verdaccio/config.yaml on Linux and macOS. Only considered if that base directory exists.
2. %APPDATA%\verdaccio\config.yaml on Windows, e.g. C:\Users\<user>\AppData\Roaming\verdaccio\config.yaml.
3. ./verdaccio/config.yaml, relative to the current working directory.
4. ./config.yaml, kept so that older setups keep working.

If none of them exists, Verdaccio creates one at the first candidate, writing out the default configuration, and reports the path it chose in the startup log.

XDG_CONFIG_HOME, not XDG_DATA_HOME

The configuration is resolved through XDG_CONFIG_HOME. XDG_DATA_HOME is a different variable and only decides where the default storage lives.

Not sure which file a running process picked up? verdaccio --info reports it, and so does the conf field of the /-/_debug endpoint.

Config file format

The configuration must be YAML, in a file ending in .yaml or .yml (case insensitive).

JSON and JavaScript configs are 6.x only

6.x also accepts a .json file or a Node.js module, which it loads with require while emitting the VERDEP004 deprecation warning. 7.x removed that: any other extension fails at startup with config file must be a YAML file (.yaml or .yml). Convert the file before upgrading.

Default storage location

The default storage lives under $XDG_DATA_HOME, which falls back to $HOME/.local/share when unset — so ~/.local/share/verdaccio/storage. If you configured a storage path of your own, or a storage plugin, this location is irrelevant.

You can use VERDACCIO_STORAGE_PATH to define an alternative storage path, read more about VERDACCIO_STORAGE_PATH at the environment variables page.

Default database file location

The default database file location is within the storage location.

Environment variables

Full list of environment variables.

• VERDACCIO_HANDLE_KILL_SIGNALS to enable graceful shutdown. Only applies to 6.x: on 7.x graceful shutdown is always on and the variable was removed, see environment variables.