0
# Command Line Interface
1

2
Command-line tool for version generation and validation that works with any programming language project.
3

4
## Installation and Access
5

6
The CLI is available after installing the dunamai package:
7

8
```bash
9
pip install dunamai
10
```
11

12
The `dunamai` command becomes available system-wide via the entry point in pyproject.toml.
13

14
## Basic Commands
15

16
### Version Generation
17

18
Generate version strings from version control system information.
19

20
```bash
21
# Auto-detect VCS and generate version
22
dunamai from any
23

24
# Use specific VCS
25
dunamai from git
26
dunamai from mercurial
27
dunamai from darcs
28
dunamai from subversion
29
dunamai from bazaar
30
dunamai from fossil
31
dunamai from pijul
32
```
33

34
**Example Outputs**:
35
```bash
36
$ dunamai from any
37
1.2.3.post7.dev0+g29045e8
38

39
$ dunamai from git
40
1.2.3.post7.dev0+g29045e8
41
```
42

43
### Version Validation
44

45
Validate version strings against versioning standards.
46

47
```bash
48
# Validate against PEP 440 (default)
49
dunamai check "1.2.3"
50

51
# Validate against Semantic Versioning
52
dunamai check "1.2.3-alpha.1" --style semver
53

54
# Validate against Haskell PVP
55
dunamai check "1.2.3-test" --style pvp
56
```
57

58
**Example Outputs**:
59
```bash
60
$ dunamai check "1.2.3"
61
# No output means valid
62

63
$ dunamai check "v1.2.3" --style pep440
64
Version 'v1.2.3' does not conform to the PEP 440 style
65
```
66

67
## Command Options
68

69
### Global Options
70

71
Options available for all commands:
72

73
```bash
74
dunamai --help                    # Show help
75
dunamai --version                 # Show dunamai version
76
```
77

78
### VCS-Specific Options
79

80
Common options for `dunamai from <vcs>` commands:
81

82
```bash
83
# Metadata control
84
dunamai from any --metadata         # Always include metadata
85
dunamai from any --no-metadata      # Never include metadata
86

87
# Dirty state
88
dunamai from any --dirty            # Include dirty flag
89

90
# Git-specific: ignore untracked files
91
dunamai from git --ignore-untracked
92

93
# Tagged metadata
94
dunamai from any --tagged-metadata
95

96
# Custom tag pattern
97
dunamai from any --pattern "custom-(?P<base>\d+\.\d+\.\d+)"
98

99
# Tag selection
100
dunamai from any --latest-tag       # Use latest tag by date
101
```
102

103
### Format Control
104

105
Control the output format and style:
106

107
```bash
108
# Built-in styles
109
dunamai from any --style pep440     # PEP 440 (default)
110
dunamai from any --style semver     # Semantic Versioning
111
dunamai from any --style pvp        # Haskell PVP
112

113
# Custom format strings
114
dunamai from any --format "v{base}+{distance}.{commit}"
115
dunamai from any --format "{base}-{branch}"
116
dunamai from any --format "{major}.{minor}.{patch}.{distance}"
117
```
118

119
### Version Bumping
120

121
Automatically increment version components:
122

123
```bash
124
# Bump version for next release
125
dunamai from any --bump
126

127
# Combined with custom format
128
dunamai from any --bump --format "v{base}"
129
```
130

131
## Usage Examples
132

133
### CI/CD Integration
134

135
```bash
136
# Get clean version for releases
137
VERSION=$(dunamai from any --style semver --no-metadata)
138
echo "Release version: $VERSION"
139

140
# Get development version with commit info
141
DEV_VERSION=$(dunamai from git --dirty)
142
echo "Development version: $DEV_VERSION"
143

144
# Docker tag-friendly format
145
DOCKER_TAG=$(dunamai from any --format "{base}-{commit}")
146
docker build -t myapp:$DOCKER_TAG .
147
```
148

149
### Multi-Language Projects
150

151
```bash
152
# Generate version for any project type
153
cd /path/to/cpp-project
154
dunamai from any --format "{major}.{minor}.{patch}"
155

156
cd /path/to/nodejs-project  
157
dunamai from any --style semver
158

159
cd /path/to/python-project
160
dunamai from any --style pep440
161
```
162

163
### Branch-Aware Versioning
164

165
```bash
166
# Include branch in development builds
167
dunamai from git --format "{base}-{branch_escaped}+{commit}"
168

169
# Main branch vs feature branch handling
170
if [[ $(git branch --show-current) == "main" ]]; then
171
    VERSION=$(dunamai from git --style semver)
172
else
173
    VERSION=$(dunamai from git --format "{base}-dev.{distance}+{commit}")
174
fi
175
```
176

177
### Custom Tag Patterns
178

179
```bash
180
# For tags like "release-1.2.3"
181
dunamai from git --pattern "^release-(?P<base>\d+\.\d+\.\d+)$"
182

183
# For tags like "v1.2.3-rc1"
184
dunamai from any --pattern "^v(?P<base>\d+\.\d+\.\d+)(-(?P<stage>\w+)(?P<revision>\d+))?$"
185

186
# For Subversion with custom tag directory
187
dunamai from subversion --tag-dir "releases"
188
```
189

190
### Validation Workflows
191

192
```bash
193
# Validate current version
194
CURRENT_VERSION=$(dunamai from any)
195
dunamai check "$CURRENT_VERSION" --style pep440
196

197
# Validate custom version strings
198
dunamai check "1.2.3-rc.1" --style semver || echo "Invalid SemVer"
199
dunamai check "2!1.2.3.post1" --style pep440 || echo "Invalid PEP 440"
200
```
201

202
### Output Processing
203

204
```bash
205
# Extract version components
206
VERSION=$(dunamai from any --format "{base}")
207
MAJOR=$(dunamai from any --format "{major}")
208
MINOR=$(dunamai from any --format "{minor}")
209
PATCH=$(dunamai from any --format "{patch}")
210

211
echo "Version: $VERSION (Major: $MAJOR, Minor: $MINOR, Patch: $PATCH)"
212

213
# Generate multiple formats
214
PEP440=$(dunamai from any --style pep440)
215
SEMVER=$(dunamai from any --style semver)
216
PVP=$(dunamai from any --style pvp)
217

218
echo "PEP 440: $PEP440"
219
echo "SemVer:  $SEMVER" 
220
echo "PVP:     $PVP"
221
```
222

223
## Error Handling
224

225
The CLI provides meaningful error messages and exit codes:
226

227
```bash
228
# Exit code 0 for success
229
dunamai from git && echo "Success"
230

231
# Non-zero exit code for errors
232
dunamai from git --strict || echo "No tags found"
233

234
# Validation errors
235
dunamai check "invalid-version" || echo "Validation failed"
236
```
237

238
## Integration Examples
239

240
### Makefile Integration
241

242
```makefile
243
VERSION := $(shell dunamai from any --style semver)
244
DEV_VERSION := $(shell dunamai from any --bump --format "{base}-dev.{distance}")
245

246
version:
247
	@echo "Current version: $(VERSION)"
248

249
dev-version:
250
	@echo "Development version: $(DEV_VERSION)"
251

252
build:
253
	go build -ldflags "-X main.version=$(VERSION)" .
254
```
255

256
### GitHub Actions
257

258
```yaml
259
- name: Get version
260
  id: version
261
  run: |
262
    VERSION=$(dunamai from git --style semver)
263
    echo "version=$VERSION" >> $GITHUB_OUTPUT
264
    
265
- name: Build with version
266
  run: |
267
    echo "Building version ${{ steps.version.outputs.version }}"
268
    # Build commands here
269
```
270

271
### Docker Build
272

273
```dockerfile
274
ARG VERSION
275
LABEL version=${VERSION}
276
RUN echo "Building version ${VERSION}"
277
```
278

279
```bash
280
# Build with dynamic version
281
VERSION=$(dunamai from any --format "{base}")
282
docker build --build-arg VERSION=$VERSION .
283
```
284

285
## Advanced Usage
286

287
### Repository Detection
288

289
```bash
290
# Specify repository path
291
dunamai from any --path /path/to/repo
292

293
# Work with multiple repositories
294
for repo in repo1 repo2 repo3; do
295
    VERSION=$(dunamai from any --path $repo)
296
    echo "$repo: $VERSION"
297
done
298
```
299

300
### Pattern Development
301

302
```bash
303
# Test custom patterns
304
dunamai from any --pattern "(?P<base>\d+\.\d+\.\d+)" --debug
305

306
# Validate pattern against existing tags
307
git tag -l | while read tag; do
308
    echo "Testing tag: $tag"
309
    dunamai from git --pattern "your-pattern" || echo "Pattern doesn't match $tag"
310
done
311
```
312

313
The CLI tool provides a complete interface for version management in any software project, supporting all the same capabilities as the Python API with convenient command-line syntax.