0
# CLI Commands
1

2
Command-line interface providing comprehensive version management functionality. The CLI is the primary user interface for bump-my-version, offering interactive commands with extensive configuration options for automating version workflows.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
The primary CLI command group that provides the foundation for all bump-my-version operations.
9

10
```python { .api }
11
@click.group(
12
    context_settings={"help_option_names": ["-h", "--help"]},
13
    add_help_option=True,
14
)
15
@click.version_option(version=__version__)
16
@click.pass_context
17
def cli(ctx: Context) -> None:
18
    """Version bump your Python project."""
19
```
20

21
**Usage:**
22
```bash
23
bump-my-version --help
24
bump-my-version --version
25
```
26

27
### Version Bumping
28

29
Primary command for incrementing version numbers and updating project files. Supports both component-based bumping (patch, minor, major) and explicit version setting.
30

31
```python { .api }
32
@cli.command(context_settings={"ignore_unknown_options": True})
33
@click.argument("args", nargs=-1, type=str)
34
@config_option("--config-file", envvar="BUMPVERSION_CONFIG_FILE", help="Config file to read most of the variables from.")
35
@click.option("-v", "--verbose", count=True, required=False, envvar="BUMPVERSION_VERBOSE", help="Print verbose logging to stderr. Can specify several times for more verbosity.")
36
@click.option("--allow-dirty/--no-allow-dirty", default=None, required=False, envvar="BUMPVERSION_ALLOW_DIRTY", help="Don't abort if working directory is dirty, or explicitly abort if dirty.")
37
@click.option("--current-version", metavar="VERSION", required=False, envvar="BUMPVERSION_CURRENT_VERSION", help="Version that needs to be updated")
38
@click.option("--new-version", metavar="VERSION", required=False, envvar="BUMPVERSION_NEW_VERSION", help="New version that should be in the files")
39
@click.option("--parse", metavar="REGEX", required=False, envvar="BUMPVERSION_PARSE", help="Regex parsing the version string")
40
@click.option("--serialize", metavar="FORMAT", multiple=True, envvar="BUMPVERSION_SERIALIZE", help="How to format what is parsed back to a version")
41
@click.option("--search", metavar="SEARCH", required=False, envvar="BUMPVERSION_SEARCH", help="Template for search string")
42
@click.option("--replace", metavar="REPLACE", required=False, envvar="BUMPVERSION_REPLACE", help="Template for replace string")
43
@click.option("--regex/--no-regex", default=None, envvar="BUMPVERSION_REGEX", help="Treat the search parameter as a regex pattern")
44
@click.option("--no-configured-files", is_flag=True, envvar="BUMPVERSION_NO_CONFIGURED_FILES", help="Only update files specified on the command line")
45
@click.option("--ignore-missing-files", is_flag=True, envvar="BUMPVERSION_IGNORE_MISSING_FILES", help="Ignore missing files when searching")
46
@click.option("--ignore-missing-version", is_flag=True, envvar="BUMPVERSION_IGNORE_MISSING_VERSION", help="Ignore missing version in files when searching")
47
@click.option("--dry-run", "-n", is_flag=True, envvar="BUMPVERSION_DRY_RUN", help="Don't write any files, just pretend.")
48
@click.option("--commit/--no-commit", default=None, envvar="BUMPVERSION_COMMIT", help="Commit to version control")
49
@click.option("--tag/--no-tag", default=None, envvar="BUMPVERSION_TAG", help="Create a tag in version control")
50
@click.option("--sign-tags/--no-sign-tags", default=None, envvar="BUMPVERSION_SIGN_TAGS", help="Sign tags if created")
51
@click.option("--tag-name", metavar="TAG_NAME", required=False, envvar="BUMPVERSION_TAG_NAME", help="Tag name (only works with --tag)")
52
@click.option("--tag-message", metavar="TAG_MESSAGE", required=False, envvar="BUMPVERSION_TAG_MESSAGE", help="Tag message")
53
@click.option("-m", "--message", metavar="COMMIT_MSG", required=False, envvar="BUMPVERSION_MESSAGE", help="Commit message")
54
@click.option("--commit-args", metavar="COMMIT_ARGS", required=False, envvar="BUMPVERSION_COMMIT_ARGS", help="Extra arguments to commit command")
55
def bump(
56
    args: List[str],
57
    config_file: Optional[str],
58
    verbose: int,
59
    allow_dirty: Optional[bool],
60
    current_version: Optional[str],
61
    new_version: Optional[str],
62
    parse: Optional[str],
63
    serialize: Optional[List[str]],
64
    search: Optional[str],
65
    replace: Optional[str],
66
    regex: Optional[bool],
67
    no_configured_files: bool,
68
    ignore_missing_files: bool,
69
    ignore_missing_version: bool,
70
    dry_run: bool,
71
    commit: Optional[bool],
72
    tag: Optional[bool],
73
    sign_tags: Optional[bool],
74
    tag_name: Optional[str],
75
    tag_message: Optional[str],
76
    message: Optional[str],
77
    commit_args: Optional[str],
78
) -> None:
79
    """
80
    Change the version by bumping VERSION_PART or setting a NEW_VERSION.
81
    
82
    Bump version components (major, minor, patch) or set explicit version.
83
    Updates files, creates commits and tags according to configuration.
84
    """
85
```
86

87
**Usage Examples:**
88
```bash
89
# Bump version components
90
bump-my-version bump patch
91
bump-my-version bump minor
92
bump-my-version bump major
93

94
# Set specific version
95
bump-my-version bump --new-version 2.1.0
96

97
# Bump with options
98
bump-my-version bump patch --commit --tag --dry-run
99

100
# Bump specific files only
101
bump-my-version bump patch setup.py __init__.py
102
```
103

104
### Configuration Display
105

106
Display current configuration, version information, and potential version changes in various output formats.
107

108
```python { .api }
109
@click.command()
110
@click.argument("args", nargs=-1, type=str)
111
@click.option("--config-file", type=str, help="Configuration file to use")
112
@click.option("--format", 
113
              type=click.Choice(['default', 'yaml', 'json']),
114
              default='default',
115
              help="Output format")
116
@click.option("--increment", type=str, help="Version part to increment for preview")
117
def show(
118
    args: Tuple[str, ...],
119
    config_file: Optional[str] = None,
120
    format: str = 'default',
121
    increment: Optional[str] = None
122
) -> None:
123
    """
124
    Show current configuration information and version components.
125
    
126
    Display configuration values, current version, or preview version changes.
127
    Supports multiple output formats and can show specific configuration keys.
128
    """
129
```
130

131
**Usage Examples:**
132
```bash
133
# Show all configuration
134
bump-my-version show
135

136
# Show specific values
137
bump-my-version show current_version
138
bump-my-version show new_version --increment patch
139

140
# Show in different formats
141
bump-my-version show --format yaml
142
bump-my-version show --format json
143

144
# Show with increment preview
145
bump-my-version show new_version --increment minor
146
```
147

148
### File Replacement
149

150
Replace version strings in files without performing SCM operations. Useful for testing version changes or manual file updates.
151

152
```python { .api }
153
@click.command()
154
@click.argument("files", nargs=-1, type=str)
155
@click.option("--config-file", type=str, help="Configuration file to use")
156
@click.option("--current-version", type=str, help="Current version to replace")
157
@click.option("--new-version", type=str, required=True, help="New version to set")
158
@click.option("--parse", type=str, help="Regex pattern to parse version")
159
@click.option("--serialize", type=str, multiple=True, help="Serialization format")
160
@click.option("--search", type=str, help="Template for search string")
161
@click.option("--replace", type=str, help="Template for replace string")
162
@click.option("--regex/--no-regex", default=False, help="Use regex for search")
163
@click.option("--dry-run", is_flag=True, help="Don't modify files")
164
@click.option("--ignore-missing-version", is_flag=True, help="Ignore missing version in files")
165
@click.option("--ignore-missing-files", is_flag=True, help="Ignore missing files")
166
@click.option("--verbose", "-v", count=True, help="Increase verbosity")
167
def replace(
168
    files: Tuple[str, ...],
169
    config_file: Optional[str] = None,
170
    current_version: Optional[str] = None,
171
    new_version: str = None,
172
    parse: Optional[str] = None,
173
    serialize: Tuple[str, ...] = (),
174
    search: Optional[str] = None,
175
    replace: Optional[str] = None,
176
    regex: bool = False,
177
    dry_run: bool = False,
178
    ignore_missing_version: bool = False,
179
    ignore_missing_files: bool = False,
180
    verbose: int = 0
181
) -> None:
182
    """
183
    Replace version strings in files without SCM operations.
184
    
185
    Updates version strings in specified files without creating commits or tags.
186
    Useful for testing version changes or manual file updates.
187
    """
188
```
189

190
**Usage Examples:**
191
```bash
192
# Replace version in specific files
193
bump-my-version replace --new-version 2.1.0 setup.py __init__.py
194

195
# Replace with custom patterns
196
bump-my-version replace --new-version 2.1.0 --search "version = '{current_version}'" file.py
197

198
# Dry run replacement
199
bump-my-version replace --new-version 2.1.0 --dry-run setup.py
200
```
201

202
### Configuration Generation
203

204
Generate sample configuration files interactively or with default settings to bootstrap new projects.
205

206
```python { .api }
207
@click.command(name="sample-config")
208
@click.option("--no-prompt", "--prompt", is_flag=True, help="Skip interactive prompts")
209
@click.option("--destination", type=str, default=".bumpversion.toml", help="Output file path")
210
def sample_config(prompt: bool, destination: str) -> None:
211
    """
212
    Generate a sample configuration file.
213
    
214
    Creates configuration file with default settings or through interactive prompts.
215
    Supports both automated and interactive configuration setup.
216
    """
217
```
218

219
**Usage Examples:**
220
```bash
221
# Generate with prompts
222
bump-my-version sample-config
223

224
# Generate with defaults
225
bump-my-version sample-config --no-prompt
226

227
# Specify output location  
228
bump-my-version sample-config --destination pyproject.toml
229
```
230

231
### Version Bump Visualization
232

233
Visualize potential version bump paths showing how each version component would change from current or specified version.
234

235
```python { .api }
236
@click.command(name="show-bump")
237
@click.argument("version", nargs=1, type=str, required=False, default="")
238
@click.option("--config-file", type=str, help="Configuration file to use")
239
@click.option("--ascii", is_flag=True, help="Use ASCII characters only")
240
@click.option("--verbose", "-v", count=True, help="Increase verbosity")
241
def show_bump(
242
    version: str,
243
    config_file: Optional[str] = None,
244
    ascii: bool = False,
245
    verbose: int = 0
246
) -> None:
247
    """
248
    Visualize version bump possibilities.
249
    
250
    Shows tree diagram of potential version changes for each component.
251
    Helps understand how version bumping affects different parts.
252
    """
253
```
254

255
**Usage Examples:**
256
```bash
257
# Show bumps for current version
258
bump-my-version show-bump
259

260
# Show bumps for specific version
261
bump-my-version show-bump 1.2.3
262

263
# ASCII-only output
264
bump-my-version show-bump --ascii
265
```
266

267
## Configuration Options
268

269
### Global Options
270

271
Available across all commands:
272

273
- `--config-file`: Specify configuration file path (default: auto-detected)
274
- `--verbose, -v`: Increase output verbosity (can be repeated)
275
- `--help, -h`: Show help message
276
- `--version`: Show version information
277

278
### File Configuration
279

280
Commands support reading configuration from:
281

282
- `pyproject.toml` (under `[tool.bumpversion]`)
283
- `.bumpversion.toml`
284
- `.bumpversion.cfg` (legacy format)
285
- `setup.cfg` (legacy format)
286

287
### Environment Variables
288

289
Configuration can be overridden using environment variables with `BMP_` prefix:
290

291
```bash
292
export BMP_CURRENT_VERSION="1.0.0"  
293
export BMP_COMMIT="true"
294
export BMP_TAG="true"
295
```
296

297
## Integration Examples
298

299
### CI/CD Integration
300

301
```bash
302
# In CI pipeline
303
bump-my-version bump patch --commit --tag
304
git push --follow-tags
305
```
306

307
### Pre-commit Hook
308

309
```bash
310
# .pre-commit-config.yaml integration
311
- repo: local
312
  hooks:
313
    - id: bump-version
314
      name: Bump version
315
      entry: bump-my-version bump patch --dry-run
316
      language: system
317
```
318

319
### GitHub Actions
320

321
```yaml
322
- name: Bump version and push tag
323
  run: |
324
    bump-my-version bump patch --commit --tag  
325
    git push --follow-tags
326
```