0
# CLI Interface
1

2
Command-line interface providing build, metadata inspection, version management, and dependency analysis functionality. The CLI offers direct access to hatchling's capabilities for development and debugging.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
```python { .api }
9
def hatchling() -> int:
10
    """
11
    Main CLI entry point.
12
    
13
    Returns:
14
        int: Exit code (0 for success)
15
    """
16
```
17

18
### Build Command
19

20
Build distributions (wheels and source distributions) from the command line.
21

22
```bash
23
hatchling build [OPTIONS]
24

25
Options:
26
  -t, --target TEXT    Build target (wheel, sdist, binary, or custom)
27
  -c, --clean          Clean build directory before building
28
  --ext                Build extensions
29
  --no-sources         Skip source distribution building
30
  --no-wheel           Skip wheel building
31
  -h, --help          Show help message
32
```
33

34
### Metadata Command
35

36
Inspect and display project metadata information.
37

38
```bash
39
hatchling metadata [OPTIONS]
40

41
Options:
42
  --field TEXT         Show specific metadata field
43
  --core               Show core metadata in email format
44
  --json               Output metadata as JSON
45
  -h, --help          Show help message
46
```
47

48
### Version Command
49

50
Manage project version information.
51

52
```bash
53
hatchling version [OPTIONS] [VERSION]
54

55
Arguments:
56
  VERSION              New version to set (optional)
57

58
Options:
59
  --dry-run           Show what would be changed without making changes
60
  -h, --help          Show help message
61
```
62

63
### Dependency Command
64

65
Analyze and display project dependencies.
66

67
```bash
68
hatchling dep [OPTIONS] COMMAND [ARGS]...
69

70
Commands:
71
  show                 Show dependency information
72
  hash                 Show dependency hashes
73
  freeze               Show installed dependencies in freeze format
74

75
Options:
76
  -h, --help          Show help message
77
```
78

79
## Command Details
80

81
### Build Command Usage
82

83
Build all distribution types:
84
```bash
85
hatchling build
86
```
87

88
Build only wheels:
89
```bash
90
hatchling build -t wheel
91
```
92

93
Build only source distributions:
94
```bash
95
hatchling build -t sdist
96
```
97

98
Build with clean directory:
99
```bash
100
hatchling build --clean
101
```
102

103
Build custom targets:
104
```bash
105
hatchling build -t my-custom-builder
106
```
107

108
### Metadata Command Usage
109

110
Show all metadata:
111
```bash
112
hatchling metadata
113
```
114

115
Show specific field:
116
```bash
117
hatchling metadata --field name
118
hatchling metadata --field version
119
hatchling metadata --field dependencies
120
```
121

122
Show core metadata:
123
```bash
124
hatchling metadata --core
125
```
126

127
Output as JSON:
128
```bash
129
hatchling metadata --json
130
```
131

132
### Version Command Usage
133

134
Show current version:
135
```bash
136
hatchling version
137
```
138

139
Set new version:
140
```bash
141
hatchling version 1.2.0
142
```
143

144
Preview version change:
145
```bash
146
hatchling version 1.2.0 --dry-run
147
```
148

149
### Dependency Command Usage
150

151
Show project dependencies:
152
```bash
153
hatchling dep show
154
```
155

156
Show dependency hashes:
157
```bash
158
hatchling dep hash
159
```
160

161
Show freeze format:
162
```bash
163
hatchling dep freeze
164
```
165

166
## CLI Implementation
167

168
### Command Registration
169

170
```python { .api }
171
def build_command(subparsers, defaults):
172
    """Register build command with argument parser."""
173

174
def metadata_command(subparsers, defaults):
175
    """Register metadata command with argument parser."""
176

177
def version_command(subparsers, defaults):
178
    """Register version command with argument parser."""
179

180
def dep_command(subparsers, defaults):
181
    """Register dependency command with argument parser."""
182
```
183

184
### Argument Parser
185

186
The CLI uses Python's `argparse` module with the following structure:
187

188
```python
189
parser = argparse.ArgumentParser(prog='hatchling', allow_abbrev=False)
190
subparsers = parser.add_subparsers()
191

192
# Default settings for all subcommands
193
defaults = {'metavar': ''}
194
```
195

196
## Usage Examples
197

198
### Development Workflow
199

200
```bash
201
# Check project metadata
202
hatchling metadata --field name
203
hatchling metadata --field version
204

205
# Build development distributions
206
hatchling build --clean
207

208
# Update version
209
hatchling version 1.1.0
210

211
# Build release distributions
212
hatchling build -t wheel -t sdist
213
```
214

215
### CI/CD Integration
216

217
```bash
218
# Validate metadata
219
hatchling metadata --core > /dev/null
220

221
# Build distributions for upload
222
hatchling build --clean
223

224
# Check dependency information
225
hatchling dep show
226
```
227

228
### Debugging
229

230
```bash
231
# Show all metadata in JSON format
232
hatchling metadata --json
233

234
# Show specific metadata fields
235
hatchling metadata --field dynamic
236
hatchling metadata --field build-system
237

238
# Preview version changes
239
hatchling version 2.0.0 --dry-run
240
```
241

242
### Custom Builder Integration
243

244
```bash
245
# Build with custom builder plugin
246
hatchling build -t my-custom-builder
247

248
# Show available builders (through metadata)
249
hatchling metadata --field tool.hatch.build
250
```
251

252
## Exit Codes
253

254
The CLI returns standard exit codes:
255

256
- `0`: Success
257
- `1`: General error (invalid arguments, build failures, etc.)
258
- `2`: File not found or permission error
259

260
## Configuration
261

262
CLI behavior can be configured through:
263

264
1. **pyproject.toml**: Project-specific settings
265
2. **Environment variables**: Build-time overrides
266
3. **Command-line options**: Per-invocation settings
267

268
### Environment Variables
269

270
Common environment variables that affect CLI behavior:
271

272
- `HATCH_BUILD_CLEAN`: Clean build directory (equivalent to --clean)
273
- `HATCH_BUILD_NO_SOURCES`: Skip source distribution building
274
- `HATCH_BUILD_NO_WHEEL`: Skip wheel building
275
- `HATCH_VERBOSE`: Enable verbose output
276

277
### Configuration Files
278

279
The CLI reads configuration from:
280

281
```toml
282
[tool.hatch.build]
283
targets = ["wheel", "sdist"]
284
clean = true
285

286
[tool.hatch.version]
287
source = "code"
288
path = "src/package/__about__.py"
289

290
[tool.hatch.metadata]
291
allow-direct-references = true
292
```
293

294
## Programmatic Access
295

296
The CLI functions can also be called programmatically:
297

298
```python
299
import sys
300
from hatchling.cli import hatchling
301

302
# Call CLI programmatically
303
sys.argv = ['hatchling', 'build', '--clean']
304
exit_code = hatchling()
305
```
306

307
However, for programmatic usage, it's recommended to use the builder classes directly rather than the CLI interface.
308

309
## Error Handling
310

311
The CLI provides user-friendly error messages for common issues:
312

313
- Missing pyproject.toml or invalid configuration
314
- Build failures with detailed error context
315
- Invalid metadata field references
316
- Version parsing or setting errors
317
- Dependency resolution issues
318

319
Errors are displayed to stderr with helpful suggestions when possible.
320

321
## Integration with Build Tools
322

323
The CLI integrates with various development tools:
324

325
- **tox**: Use hatchling CLI in tox environments
326
- **GitHub Actions**: CI/CD with hatchling commands
327
- **pre-commit**: Version management hooks
328
- **make**: Build automation with make targets
329

330
Example Makefile integration:
331
```makefile
332
build:
333
	hatchling build --clean
334

335
metadata:
336
	hatchling metadata --json > metadata.json
337

338
version:
339
	hatchling version $(VERSION)
340
```
341

342
The CLI interface provides a convenient way to access hatchling's functionality during development, CI/CD, and release workflows while maintaining consistency with the programmatic API.