0
# CLI Interface
1

2
Release It!'s command-line interface provides a comprehensive set of options for automating release workflows. The CLI supports both interactive and non-interactive modes, with extensive configuration options.
3

4
## Capabilities
5

6
### Main CLI Function
7

8
Primary command-line interface entry point.
9

10
```javascript { .api }
11
/**
12
 * Main CLI entry point that processes options and delegates to appropriate handler
13
 * @param options - Parsed CLI options object
14
 * @returns Promise that resolves when CLI operation completes
15
 */
16
function cli(options: CLIOptions): Promise<any>;
17

18
interface CLIOptions {
19
  /** Show version information */
20
  version?: boolean;
21
  /** Show help information */
22
  help?: boolean;
23
  /** Version increment or explicit version */
24
  increment?: string;
25
  /** Dry run mode - show operations without executing */
26
  "dry-run"?: boolean;
27
  /** Verbose output (can be boolean or number for level) */
28
  verbose?: boolean | number;
29
  /** CI mode - non-interactive operation */
30
  ci?: boolean;
31
  /** Prompt only for version selection */
32
  "only-version"?: boolean;
33
  /** Print release version and exit */
34
  "release-version"?: boolean;
35
  /** Print changelog and exit */
36
  changelog?: boolean;
37
  /** Configuration file path */
38
  config?: string;
39
  /** Configuration directory */
40
  "config-dir"?: string;
41
  /** Configuration to extend */
42
  extends?: string;
43
  [key: string]: any;
44
}
45
```
46

47
### Argument Parsing
48

49
Command-line argument parsing and validation.
50

51
```javascript { .api }
52
/**
53
 * Parse command-line arguments into structured options object
54
 * @param args - Array of command-line arguments (typically process.argv.slice(2))
55
 * @returns Parsed options object with normalized keys
56
 */
57
function parseCliArguments(args: string[]): CLIOptions;
58
```
59

60
### Information Commands
61

62
Commands for displaying version and help information.
63

64
```javascript { .api }
65
/**
66
 * Print Release It! version information
67
 * Outputs version number to console and exits
68
 */
69
function version(): void;
70

71
/**
72
 * Print comprehensive help text with usage examples
73
 * Outputs help information to console and exits
74
 */
75
function help(): void;
76
```
77

78
### CLI Command Examples
79

80
Release It! provides a flexible command-line interface with numerous options:
81

82
**Basic Usage:**
83
```bash
84
# Interactive release with prompts
85
release-it
86

87
# Release with specific increment
88
release-it patch
89
release-it minor
90
release-it major
91
release-it prerelease
92

93
# Explicit version specification
94
release-it 2.1.0
95
release-it 1.0.0-beta.1
96
```
97

98
**Mode Options:**
99
```bash
100
# Dry run - show what would happen without executing
101
release-it --dry-run
102
release-it -d
103

104
# CI mode - non-interactive, fail on prompts
105
release-it --ci
106

107
# Only prompt for version, skip other interactions
108
release-it --only-version
109

110
# Print version that would be released and exit
111
release-it --release-version
112

113
# Print changelog for upcoming release and exit
114
release-it --changelog
115
```
116

117
**Configuration Options:**
118
```bash
119
# Use specific configuration file
120
release-it --config .release-it.production.json
121
release-it -c custom-config.js
122

123
# Disable configuration file loading
124
release-it --no-config
125

126
# Specify configuration directory
127
release-it --config-dir ./configs
128

129
# Extend specific configuration
130
release-it --extends @company/release-config
131
```
132

133
**Verbosity Options:**
134
```bash
135
# Enable verbose output
136
release-it --verbose
137
release-it -V
138

139
# Extra verbose output (shows internal commands)
140
release-it -VV
141

142
# Numeric verbosity levels
143
release-it --verbose=1
144
release-it --verbose=2
145
```
146

147
**Plugin Options:**
148
```bash
149
# Disable specific plugins
150
release-it --no-git
151
release-it --no-npm
152
release-it --no-github
153

154
# Plugin-specific configuration via CLI
155
release-it --git.requireCleanWorkingDir=false
156
release-it --npm.publish=false
157
release-it --github.release=true
158
```
159

160
**Combined Examples:**
161
```bash
162
# CI release with specific version and dry-run
163
release-it 1.2.0 --ci --dry-run --verbose
164

165
# Pre-release with custom config and GitHub disabled
166
release-it prerelease --config .release-it.beta.json --no-github
167

168
# Interactive release with verbose output and custom commit message
169
release-it --verbose --git.commitMessage="chore: release v\${version}"
170
```
171

172
### Exit Codes
173

174
Release It! uses standard exit codes to indicate operation results:
175

176
```javascript { .api }
177
interface ExitCodes {
178
  /** Successful completion */
179
  SUCCESS: 0;
180
  /** General error or operation failed */
181
  ERROR: 1;
182
  /** User interrupted operation (Ctrl+C) */
183
  INTERRUPTED: 130;
184
}
185
```
186

187
**Exit Code Usage:**
188
- `0` - Release completed successfully
189
- `1` - Error occurred during release (validation failed, command failed, etc.)
190
- `130` - User interrupted the process (Ctrl+C)
191

192
### Help Text
193

194
The CLI provides comprehensive help documentation:
195

196
```
197
Release It! v19.0.4
198

199
Usage: release-it <increment> [options]
200

201
Use e.g. "release-it minor" directly as shorthand for "release-it --increment=minor".
202

203
-c --config            Path to local configuration options [default: ".release-it.json"]
204
-d --dry-run           Do not touch or write anything, but show the commands
205
-h --help              Print this help
206
-i --increment         Increment "major", "minor", "patch", or "pre*" version; or specify version [default: "patch"]
207
   --ci                No prompts, no user interaction; activated automatically in CI environments
208
   --only-version      Prompt only for version, no further interaction
209
-v --version           Print release-it version number
210
   --release-version   Print version number to be released
211
   --changelog         Print changelog for the version to be released
212
-V --verbose           Verbose output (user hooks output)
213
-VV                    Extra verbose output (also internal commands output)
214

215
For more details, please see https://github.com/release-it/release-it
216
```
217

218
### Environment Detection
219

220
The CLI automatically detects and adapts to different environments:
221

222
```javascript { .api }
223
interface EnvironmentDetection {
224
  /** Detect CI environment and enable CI mode */
225
  detectCI(): boolean;
226
  
227
  /** Detect TTY availability for interactive features */
228
  detectTTY(): boolean;
229
  
230
  /** Detect debug mode from NODE_DEBUG environment variable */
231
  detectDebug(): boolean;
232
}
233
```
234

235
**Supported CI Environments:**
236
- GitHub Actions
237
- GitLab CI
238
- Travis CI
239
- CircleCI
240
- Jenkins
241
- Azure DevOps
242
- Bitbucket Pipelines
243
- AWS CodeBuild
244
- And many others via `ci-info` package
245

246
### Configuration Precedence
247

248
CLI options follow a specific precedence order (highest to lowest):
249

250
1. **CLI Arguments**: Direct command-line flags and options
251
2. **Environment Variables**: `CI=true`, `NODE_DEBUG=release-it`, etc.
252
3. **Configuration Files**: `.release-it.json`, `.release-it.js`, etc.
253
4. **package.json**: `release-it` property
254
5. **Default Configuration**: Built-in defaults
255

256
### Error Handling and Validation
257

258
The CLI includes comprehensive validation and error handling:
259

260
- **Argument Validation**: Invalid options and combinations are caught early
261
- **Configuration Validation**: Configuration files are validated on load
262
- **Environment Validation**: Git repository, npm authentication, etc.
263
- **Graceful Degradation**: Fallback behavior for unsupported environments
264

265
### Interactive Features
266

267
In interactive mode, the CLI provides:
268

269
- **Version Selection**: Choose from increment options or specify custom version
270
- **Operation Confirmation**: Confirm each major operation (commit, tag, push, publish)
271
- **Error Recovery**: Options to retry or skip failed operations
272
- **Progress Indication**: Spinners and progress bars for long-running operations
273

274
### Integration Examples
275

276
**Package.json Script:**
277
```json
278
{
279
  "scripts": {
280
    "release": "release-it",
281
    "release:patch": "release-it patch",
282
    "release:minor": "release-it minor",
283
    "release:major": "release-it major",
284
    "release:beta": "release-it prerelease --preReleaseId=beta",
285
    "release:dry": "release-it --dry-run"
286
  }
287
}
288
```
289

290
**GitHub Actions:**
291
```yaml
292
- name: Release
293
  run: npx release-it --ci
294
  env:
295
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
296
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
297
```
298

299
**Pre-commit Hook:**
300
```bash
301
#!/bin/sh
302
# Validate release configuration
303
npx release-it --dry-run --ci > /dev/null
304
```