0
# Command Line Interface
1

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

4
## Capabilities
5

6
### Init Command (Default)
7

8
Main server initialization command that starts the Verdaccio registry server.
9

10
```typescript { .api }
11
class InitCommand extends Command {
12
  /** Listen address option (host:port) */
13
  listen: string;
14
  /** Configuration file path option */
15
  config: string;
16
  
17
  /**
18
   * Execute the server initialization
19
   * @returns Promise that resolves when server starts or rejects on error
20
   */
21
  execute(): Promise<void>;
22
}
23
```
24

25
**Usage Examples:**
26

27
```bash
28
# Start server with default configuration (looks for ./config.yaml)
29
verdaccio
30

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

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

39
# Combine options
40
verdaccio --config ./production.yaml --listen 0.0.0.0:4873
41
```
42

43
The init command:
44
- Locates and parses the configuration file
45
- Initializes logging based on configuration
46
- Sets up storage and authentication
47
- Starts the HTTP/HTTPS server
48
- Handles graceful shutdown signals (if `VERDACCIO_HANDLE_KILL_SIGNALS=true`)
49

50
### Version Command
51

52
Display the current Verdaccio version.
53

54
```typescript { .api }
55
class VersionCommand extends Command {
56
  /**
57
   * Execute version display
58
   * @returns Promise that resolves after displaying version
59
   */
60
  execute(): Promise<void>;
61
}
62
```
63

64
**Usage Examples:**
65

66
```bash
67
# Display version
68
verdaccio --version
69
verdaccio -v
70
```
71

72
Output format: `v6.1.6`
73

74
### Info Command
75

76
Display comprehensive environment and system information for debugging and support.
77

78
```typescript { .api }
79
class InfoCommand extends Command {
80
  /**
81
   * Execute system information display
82
   * @returns Promise that resolves after displaying info
83
   */
84
  execute(): Promise<void>;
85
}
86
```
87

88
**Usage Examples:**
89

90
```bash
91
# Display system information
92
verdaccio --info
93
verdaccio -i
94
```
95

96
Information includes:
97
- Operating System details (OS, CPU)
98
- Binary versions (Node.js, npm, yarn, pnpm)
99
- Virtualization (Docker)
100
- Browser versions (Chrome, Edge, Firefox, Safari)
101
- Global Verdaccio package information
102

103
## Command Line Options
104

105
### Global Options
106

107
All commands support these global patterns:
108

109
- `--help`: Display command help information
110
- `--version` / `-v`: Display version (VersionCommand)
111
- `--info` / `-i`: Display system info (InfoCommand)
112

113
### Init Command Options
114

115
- `--config <path>` / `-c <path>`: Specify configuration file path
116
  - Default: `./config.yaml`
117
  - Supports absolute and relative paths
118
  - Must be a valid YAML configuration file
119

120
- `--listen <address>` / `-l <address>`: Specify listen address
121
  - Default: From configuration file or `localhost:4873`
122
  - Format: `host:port`, `port`, or `unix:/path/to/socket`
123
  - Examples: `localhost:4873`, `0.0.0.0:5000`, `4873`
124

125
## Error Handling
126

127
CLI commands handle various error conditions:
128

129
### Configuration Errors
130
- Missing or invalid configuration file
131
- Invalid YAML syntax
132
- Missing required configuration sections
133

134
### Server Startup Errors
135
- Port already in use
136
- Permission denied (e.g., binding to port < 1024 without sudo)
137
- Invalid HTTPS certificate configuration
138
- Storage directory creation failures
139

140
### Process Management
141
- Node.js version compatibility (requires Node.js >= 18)
142
- Root user warnings (Verdaccio doesn't need superuser privileges)
143
- Uncaught exception handling with error reporting
144

145
## Exit Codes
146

147
- `0`: Success
148
- `1`: Configuration or startup error
149
- `2`: HTTPS certificate or server creation error
150
- `255`: Uncaught exception
151

152
## Environment Variables
153

154
### VERDACCIO_HANDLE_KILL_SIGNALS
155
When set to `"true"`, enables graceful shutdown handling for:
156
- `SIGINT` (Ctrl+C)
157
- `SIGTERM` (termination signal)
158
- `SIGHUP` (hangup signal)
159

160
```bash
161
VERDACCIO_HANDLE_KILL_SIGNALS=true verdaccio
162
```
163

164
### NODE_ENV
165
Standard Node.js environment variable, defaults to `"production"` for the Express application.
166

167
## Process Management
168

169
The CLI sets the process title based on configuration:
170
- Default: `"verdaccio"`
171
- Custom: From `web.title` configuration option
172

173
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).