Command Line Interface

CLI commands for server operation, configuration, and system information. The Verdaccio CLI is accessed via the verdaccio binary installed globally or locally.

Capabilities

Init Command (Default)

Main server initialization command that starts the Verdaccio registry server.

class InitCommand extends Command {
  /** Listen address option (host:port) */
  listen: string;
  /** Configuration file path option */
  config: string;
  
  /**
   * Execute the server initialization
   * @returns Promise that resolves when server starts or rejects on error
   */
  execute(): Promise<void>;
}

Usage Examples:

# Start server with default configuration (looks for ./config.yaml)
verdaccio

# Start with custom configuration file
verdaccio --config /path/to/custom-config.yaml
verdaccio -c ./my-config.yaml

# Start on custom host and port
verdaccio --listen localhost:5000
verdaccio -l 0.0.0.0:4873

# Combine options
verdaccio --config ./production.yaml --listen 0.0.0.0:4873

The init command:

• Locates and parses the configuration file
• Initializes logging based on configuration
• Sets up storage and authentication
• Starts the HTTP/HTTPS server
• Handles graceful shutdown signals (if VERDACCIO_HANDLE_KILL_SIGNALS=true)

Version Command

Display the current Verdaccio version.

class VersionCommand extends Command {
  /**
   * Execute version display
   * @returns Promise that resolves after displaying version
   */
  execute(): Promise<void>;
}

Usage Examples:

# Display version
verdaccio --version
verdaccio -v

Output format: v6.1.6

Info Command

Display comprehensive environment and system information for debugging and support.

class InfoCommand extends Command {
  /**
   * Execute system information display
   * @returns Promise that resolves after displaying info
   */
  execute(): Promise<void>;
}

Usage Examples:

# Display system information
verdaccio --info
verdaccio -i

Information includes:

• Operating System details (OS, CPU)
• Binary versions (Node.js, npm, yarn, pnpm)
• Virtualization (Docker)
• Browser versions (Chrome, Edge, Firefox, Safari)
• Global Verdaccio package information

Command Line Options

Global Options

All commands support these global patterns:

• --help: Display command help information
• --version / -v: Display version (VersionCommand)
• --info / -i: Display system info (InfoCommand)

Init Command Options

• --config <path> / -c <path>: Specify configuration file path

  • Default: ./config.yaml
  • Supports absolute and relative paths
  • Must be a valid YAML configuration file

• --listen <address> / -l <address>: Specify listen address

  • Default: From configuration file or localhost:4873
  • Format: host:port, port, or unix:/path/to/socket
  • Examples: localhost:4873, 0.0.0.0:5000, 4873

Error Handling

CLI commands handle various error conditions:

Configuration Errors

• Missing or invalid configuration file
• Invalid YAML syntax
• Missing required configuration sections

Server Startup Errors

• Port already in use
• Permission denied (e.g., binding to port < 1024 without sudo)
• Invalid HTTPS certificate configuration
• Storage directory creation failures

Process Management

• Node.js version compatibility (requires Node.js >= 18)
• Root user warnings (Verdaccio doesn't need superuser privileges)
• Uncaught exception handling with error reporting

Exit Codes

• 0: Success
• 1: Configuration or startup error
• 2: HTTPS certificate or server creation error
• 255: Uncaught exception

Environment Variables

VERDACCIO_HANDLE_KILL_SIGNALS

When set to "true", enables graceful shutdown handling for:

• SIGINT (Ctrl+C)
• SIGTERM (termination signal)
• SIGHUP (hangup signal)

VERDACCIO_HANDLE_KILL_SIGNALS=true verdaccio

NODE_ENV

Standard Node.js environment variable, defaults to "production" for the Express application.

Process Management

The CLI sets the process title based on configuration:

• Default: "verdaccio"
• Custom: From web.title configuration option

For testing and automation, the server sends a verdaccio_started message via process.send() when the server is ready (if running as a child process).