0
# Command Line Interface
1

2
Standard Version provides a comprehensive CLI for automated versioning and changelog generation. The CLI analyzes conventional commits, determines appropriate version bumps, updates files, generates changelogs, and creates git tags.
3

4
## Capabilities
5

6
### Basic Commands
7

8
Standard command-line usage for common versioning scenarios.
9

10
```bash { .api }
11
# Automatic version bump based on conventional commits
12
standard-version
13

14
# Specific release types
15
standard-version --release-as major
16
standard-version --release-as minor  
17
standard-version --release-as patch
18
standard-version --release-as 1.5.0
19

20
# Pre-release versions
21
standard-version --prerelease
22
standard-version --prerelease alpha
23
standard-version --prerelease beta
24
```
25

26
**Usage Examples:**
27

28
```bash
29
# Analyze commits and bump version automatically
30
standard-version
31
# If commits contain: feat: add new feature -> minor bump
32
# If commits contain: fix: resolve bug -> patch bump  
33
# If commits contain: feat!: breaking change -> major bump
34

35
# Force specific version bump
36
standard-version --release-as major
37
# Always creates major version bump regardless of commits
38

39
# Create pre-release version
40
standard-version --prerelease
41
# 1.0.0 -> 1.0.1-0, 1.0.1-0 -> 1.0.1-1
42

43
# Create pre-release with custom tag
44
standard-version --prerelease alpha
45
# 1.0.0 -> 1.0.1-alpha.0
46
```
47

48
### Release Configuration Options
49

50
Options for controlling release behavior and version calculation.
51

52
```bash { .api }
53
--release-as, -r <type>        # Specify release type (major|minor|patch) or exact version
54
--prerelease, -p [tag]         # Create pre-release with optional tag identifier  
55
--first-release, -f            # Mark as first release (skips version bump)
56
```
57

58
**Usage Examples:**
59

60
```bash
61
# First release of a project
62
standard-version --first-release
63
# Creates changelog and tag without bumping version from package.json
64

65
# Pre-release with custom tag
66
standard-version --prerelease canary
67
# Creates version like 1.0.1-canary.0
68
```
69

70
### Git Configuration Options
71

72
Options for controlling git commit and tag behavior.
73

74
```bash { .api }
75
--sign, -s                     # Sign git commit and tag with GPG
76
--no-verify, -n               # Bypass pre-commit and commit-msg git hooks
77
--commit-all, -a              # Commit all staged changes, not just version files
78
--tag-prefix, -t <prefix>     # Custom prefix for git tags (default: 'v')
79
```
80

81
**Usage Examples:**
82

83
```bash
84
# Sign commits and tags
85
standard-version --sign
86
# Creates signed commit and tag using configured GPG key
87

88
# Skip git hooks during commit
89
standard-version --no-verify  
90
# Bypasses pre-commit hooks that might prevent commit
91

92
# Custom tag prefix
93
standard-version --tag-prefix rel-
94
# Creates tags like 'rel-1.0.0' instead of 'v1.0.0'
95
```
96

97
### File Configuration Options
98

99
Options for controlling which files are read and updated.
100

101
```bash { .api }
102
--infile, -i <path>           # Path to changelog file (default: CHANGELOG.md)
103
--package-files <files>       # Comma-separated list of files to read version from
104
--bump-files <files>          # Comma-separated list of files to update with version
105
```
106

107
**Usage Examples:**
108

109
```bash
110
# Custom changelog file
111
standard-version --infile HISTORY.md
112
# Updates HISTORY.md instead of CHANGELOG.md
113

114
# Multiple package files
115
standard-version --package-files package.json,manifest.json
116
# Reads version from either package.json or manifest.json
117

118
# Custom bump files  
119
standard-version --bump-files package.json,version.txt
120
# Updates both package.json and version.txt with new version
121
```
122

123
### Behavior Control Options
124

125
Options for controlling output and execution behavior.
126

127
```bash { .api }
128
--silent                      # Suppress all output except errors
129
--dry-run                     # Show what would be done without making changes
130
--git-tag-fallback           # Use git tags for version if no package files found
131
```
132

133
**Usage Examples:**
134

135
```bash
136
# Preview changes without executing
137
standard-version --dry-run
138
# Shows planned version bump, changelog entries, and files to be modified
139

140
# Run silently for CI/CD
141
standard-version --silent
142
# Suppresses progress output, only shows errors
143

144
# Use git tags as version source
145
standard-version --git-tag-fallback
146
# Falls back to latest git tag if package.json not found
147
```
148

149
### Advanced Configuration Options
150

151
Options for advanced customization and workflow integration.
152

153
```bash { .api }
154
--scripts <object>            # JSON object defining lifecycle hook scripts
155
--skip <object>               # JSON object defining steps to skip
156
--preset <preset>             # Conventional changelog preset name
157
--path <path>                 # Only include commits made under this path
158
--lerna-package <name>        # Extract tags for specific package in Lerna monorepo
159
--header <text>               # Custom header for changelog
160
```
161

162
**Usage Examples:**
163

164
```bash
165
# Skip specific steps
166
standard-version --skip.changelog=true --skip.tag=true
167
# Bumps version and commits, but skips changelog and tagging
168

169
# Custom changelog preset
170
standard-version --preset angular
171
# Uses Angular conventional changelog preset
172

173
# Include only commits under specific path
174
standard-version --path packages/core
175
# Only analyzes commits that modified files under packages/core
176

177
# Lerna monorepo package-specific versioning
178
standard-version --lerna-package my-package
179
# Extracts tags specifically for 'my-package' in a Lerna monorepo
180

181
# Custom lifecycle scripts
182
standard-version --scripts.prebump="echo 'Starting version bump'"
183
# Runs custom script before version bump
184
```
185

186
### Deprecated Options
187

188
Options that are deprecated and will be removed in future versions.
189

190
```bash { .api }
191
--message, -m <template>      # [DEPRECATED] Use --releaseCommitMessageFormat
192
--changelogHeader <text>      # [DEPRECATED] Use --header
193
```
194

195
## Exit Codes
196

197
Standard Version uses conventional exit codes:
198

199
- `0` - Success
200
- `1` - Error occurred during execution
201

202
## Configuration File Integration
203

204
All CLI options can be specified in configuration files:
205

206
```json
207
{
208
  "scripts": {
209
    "prebump": "echo 'Preparing version bump'",
210
    "postbump": "echo 'Version bumped'"
211
  },
212
  "skip": {
213
    "changelog": false,
214
    "tag": false
215
  },
216
  "tagPrefix": "release-",
217
  "releaseCommitMessageFormat": "chore(release): {{currentTag}}"
218
}
219
```
220

221
The CLI will automatically load configuration from `.versionrc`, `.versionrc.json`, `.versionrc.js`, or the `standard-version` key in `package.json`.