0
# CLI Interface
1

2
setuptools-scm provides a comprehensive command-line interface for version retrieval, debugging, and integration with build systems and CI/CD pipelines.
3

4
## Capabilities
5

6
### Main CLI Function
7

8
Entry point for the command-line interface with full argument parsing and execution.
9

10
```python { .api }
11
def main(args: list[str] | None = None) -> int:
12
    """
13
    Main CLI entry point for setuptools-scm.
14
    
15
    Parameters:
16
    - args: Command line arguments (uses sys.argv if None)
17
    
18
    Returns:
19
    Exit code (0 for success, non-zero for error)
20
    """
21
```
22

23
## Command Line Usage
24

25
### Basic Version Retrieval
26

27
```bash
28
# Get version from current directory
29
python -m setuptools_scm
30

31
# Get version from specific directory  
32
python -m setuptools_scm --root /path/to/repo
33

34
# Get version using specific config file
35
python -m setuptools_scm --config /path/to/pyproject.toml
36
```
37

38
### Version Formatting Options
39

40
```bash
41
# Strip development version suffix
42
python -m setuptools_scm --strip-dev
43

44
# Use custom format string
45
python -m setuptools_scm --format "{tag}.{distance}"
46

47
# Output only the version (no extra information)
48
python -m setuptools_scm --quiet
49
```
50

51
### Configuration and Debugging
52

53
```bash
54
# Show detailed configuration information
55
python -m setuptools_scm --query all
56

57
# Show only specific query information
58
python -m setuptools_scm --query version
59
python -m setuptools_scm --query distance  
60
python -m setuptools_scm --query dirty
61
python -m setuptools_scm --query branch
62

63
# Force writing version files
64
python -m setuptools_scm --force-write-version-files
65

66
# Show help
67
python -m setuptools_scm --help
68

69
# List package files (subcommand)
70
python -m setuptools_scm ls
71
```
72

73
## CLI Options
74

75
### Core Options
76

77
- `--root PATH` - Repository root directory (default: current directory)
78
- `--config PATH` - Path to pyproject.toml config file (auto-detected if not specified)
79
- `--strip-dev` - Remove development version suffix (.dev, etc.)
80
- `--quiet` - Suppress extra output, show only version
81

82
### Output Formatting
83

84
- `--format FORMAT` - Custom format string for version output
85
- `--json` - Output version information as JSON
86

87
### Debugging and Information
88

89
- `--query FIELD` - Query specific information (version, distance, dirty, branch, tag, all)
90
- `--force-write-version-files` - Force writing of version files even if version unchanged
91
- `--verbose` - Enable verbose output for debugging
92

93
### Configuration Override
94

95
- `--version-scheme SCHEME` - Override version scheme from config
96
- `--local-scheme SCHEME` - Override local scheme from config  
97
- `--fallback-version VERSION` - Fallback version if SCM detection fails
98

99
### Subcommands
100

101
- `ls` - List information about the package (e.g., included files)
102

103
## Usage Examples
104

105
### Development Workflow
106

107
```bash
108
# Check current version during development
109
python -m setuptools_scm
110
# Output: 1.2.3.dev4+g1234567.d20231201
111

112
# Get clean version for release preparation
113
python -m setuptools_scm --strip-dev
114
# Output: 1.2.3
115

116
# Check if repository is dirty
117
python -m setuptools_scm --query dirty
118
# Output: True or False
119

120
# Get distance from last tag
121
python -m setuptools_scm --query distance
122
# Output: 4
123
```
124

125
### CI/CD Integration
126

127
```bash
128
# In GitHub Actions, GitLab CI, etc.
129
VERSION=$(python -m setuptools_scm --strip-dev)
130
echo "Building version: $VERSION"
131

132
# Get version with custom format for Docker tags
133
DOCKER_TAG=$(python -m setuptools_scm --format "v{tag}-{distance}")
134
echo "Docker tag: $DOCKER_TAG"
135

136
# Check if this is an exact release
137
python -m setuptools_scm --query distance
138
if [ $? -eq 0 ]; then
139
    echo "This is a release build"
140
else
141
    echo "This is a development build"
142
fi
143
```
144

145
### Build System Integration
146

147
```bash
148
# Generate version file before build
149
python -m setuptools_scm --force-write-version-files
150

151
# Use in setup.py or build scripts
152
VERSION=$(python -m setuptools_scm)
153
python setup.py sdist --version="$VERSION"
154

155
# Integration with other tools
156
python -m setuptools_scm --json > version.json
157
cat version.json | jq '.version'
158
```
159

160
### Debugging Configuration Issues
161

162
```bash
163
# Show all configuration and version information
164
python -m setuptools_scm --query all
165

166
# Test with different config file
167
python -m setuptools_scm --config alternative-pyproject.toml
168

169
# Override schemes for testing
170
python -m setuptools_scm --version-scheme only-version --local-scheme no-local-version
171

172
# Verbose output for troubleshooting
173
python -m setuptools_scm --verbose
174
```
175

176
## JSON Output Format
177

178
When using `--json` flag, the output includes detailed version information:
179

180
```json
181
{
182
  "version": "1.2.3.dev4+g1234567.d20231201",
183
  "tag": "1.2.3",
184
  "distance": 4,
185
  "dirty": false,
186
  "node": "1234567",
187
  "branch": "main",
188
  "node_date": "2023-12-01"
189
}
190
```
191

192
## Configuration File Integration
193

194
The CLI automatically detects and uses configuration from `pyproject.toml`:
195

196
```toml
197
[tool.setuptools_scm]
198
version_scheme = "guess-next-dev"
199
local_scheme = "node-and-date"
200
tag_regex = "^(?P<version>[vV]?\\d+(?:\\.\\d+){0,2}[^\\+]*)(?:\\+.*)?$"
201
fallback_version = "0.0.0"
202
write_to = "src/mypackage/_version.py"
203
```
204

205
The CLI respects all configuration options and can override them with command-line flags.
206

207
## Error Handling
208

209
The CLI provides clear error messages for common issues:
210

211
```bash
212
# No SCM repository found
213
python -m setuptools_scm --root /tmp
214
# ERROR: no version found
215

216
# Invalid configuration
217
python -m setuptools_scm --config invalid.toml  
218
# ERROR: could not use invalid.toml, using default configuration
219

220
# Git not available
221
python -m setuptools_scm
222
# Warning: command git not found while parsing the scm, using fallbacks
223
```
224

225
## Integration with Build Tools
226

227
### setuptools
228

229
```bash
230
# setuptools-scm integrates automatically, but CLI can verify
231
python -m setuptools_scm --query version > VERSION
232
python setup.py --version
233
```
234

235
### Build
236

237
```bash
238
python -m build --sdist --wheel
239
# setuptools-scm automatically provides version
240
```
241

242
### pip
243

244
```bash
245
# During development install
246
pip install -e .
247
# Version determined by setuptools-scm
248

249
# Check installed version matches SCM
250
pip show mypackage | grep Version
251
python -m setuptools_scm
252
```
253

254
## Advanced Usage
255

256
### Custom Format Strings
257

258
```bash
259
# Custom version format with multiple components
260
python -m setuptools_scm --format "v{tag}-build{distance}-{node}"
261
# Output: v1.2.3-build4-1234567
262

263
# Date-based formats
264
python -m setuptools_scm --format "{tag}.{node_date:%Y%m%d}"
265
# Output: 1.2.3.20231201
266

267
# Conditional formatting based on dirty state
268
python -m setuptools_scm --format "{tag}{'.dirty' if dirty else ''}"
269
```
270

271
### Scripting and Automation
272

273
```bash
274
#!/bin/bash
275
set -e
276

277
# Automated release script using setuptools-scm CLI
278
CURRENT_VERSION=$(python -m setuptools_scm --strip-dev)
279
DISTANCE=$(python -m setuptools_scm --query distance)
280

281
if [ "$DISTANCE" -eq 0 ]; then
282
    echo "Creating release for version $CURRENT_VERSION"
283
    # Perform release tasks
284
else
285
    echo "Not on a tagged commit, distance: $DISTANCE"
286
    exit 1
287
fi
288
```