0
# CLI Commands
1
2
Comprehensive command-line interface providing project management operations including environment management, dependency handling, building, testing, publishing, and Python installation management.
3
4
## Capabilities
5
6
### Build System
7
8
Build project distributions including source distributions (sdist) and wheel distributions with support for custom build hooks and multiple build targets.
9
10
```python { .api }
11
# Command: hatch build [options] [targets]
12
# Options:
13
# -t, --target TEXT The target to build (default: all)
14
# -c, --clean Clean artifacts before building
15
# -x, --ext Only build extension modules
16
# -h, --help Show help message
17
```
18
19
### Environment Management
20
21
Create, manage, and interact with isolated Python environments for development, testing, and execution. Supports virtual environments, custom environment types, and dependency management.
22
23
```python { .api }
24
# Command: hatch env [subcommand] [options]
25
# Subcommands:
26
# create [env_name] Create environment
27
# remove [env_name] Remove environment
28
# show [env_name] Show environment info
29
# find [env_name] Find environment path
30
# run Run command in environment
31
# prune Remove unused environments
32
```
33
34
Usage examples:
35
```bash
36
# Create default environment
37
hatch env create
38
39
# Create named environment
40
hatch env create test
41
42
# Show environment information
43
hatch env show test
44
45
# Remove environment
46
hatch env remove test
47
48
# Remove all unused environments
49
hatch env prune
50
```
51
52
### Project Creation and Initialization
53
54
Create new Python projects from templates or initialize existing directories as hatch projects with proper structure and configuration.
55
56
```python { .api }
57
# Command: hatch new [options] [name] [location]
58
# Options:
59
# --template TEXT Template to use
60
# --init Initialize existing directory
61
# --cli Add CLI support
62
# --no-readme Skip README creation
63
```
64
65
Usage examples:
66
```bash
67
# Create new project
68
hatch new my-project
69
70
# Create project with CLI support
71
hatch new --cli my-cli-tool
72
73
# Initialize existing directory
74
hatch new --init
75
```
76
77
### Dependency Management
78
79
Manage project dependencies including installation, updates, synchronization, and dependency resolution with support for development, test, and optional dependencies.
80
81
```python { .api }
82
# Command: hatch dep [subcommand] [options]
83
# Subcommands:
84
# show Show dependency tree
85
# hash Generate dependency hash
86
# freeze Output installed packages
87
```
88
89
### Command Execution
90
91
Execute commands and scripts within project environments with proper environment activation, dependency installation, and output capture.
92
93
```python { .api }
94
# Command: hatch run [options] [env:]<command>
95
# Options:
96
# -e, --env TEXT Environment to use
97
# --shell-spawn Spawn shell for command
98
```
99
100
Usage examples:
101
```bash
102
# Run command in default environment
103
hatch run python --version
104
105
# Run command in specific environment
106
hatch run test:pytest tests/
107
108
# Run script defined in pyproject.toml
109
hatch run lint:ruff check
110
```
111
112
### Testing
113
114
Execute project tests with support for multiple test environments, coverage reporting, and test discovery across different Python versions.
115
116
```python { .api }
117
# Command: hatch test [options] [pytest_args]
118
# Options:
119
# -c, --cover Enable coverage reporting
120
# -r, --randomize Randomize test order
121
# -p, --parallel Run tests in parallel
122
# --matrix-name TEXT Run specific matrix entry
123
```
124
125
### Code Formatting
126
127
Format project code using configured formatters with support for multiple formatters, custom configuration, and integration with CI/CD pipelines.
128
129
```python { .api }
130
# Command: hatch fmt [options] [paths]
131
# Options:
132
# --check Check formatting without changes
133
# --diff Show formatting differences
134
# --formatter TEXT Specific formatter to use
135
```
136
137
### Package Publishing
138
139
Publish packages to PyPI or custom package indices with authentication, metadata validation, and publishing hooks.
140
141
```python { .api }
142
# Command: hatch publish [options] [files]
143
# Options:
144
# -r, --repo TEXT Repository to publish to
145
# -u, --user TEXT Username for authentication
146
# --skip-existing Skip files that already exist
147
# --no-prompt Don't prompt for missing fields
148
```
149
150
### Python Installation Management
151
152
Manage Python installations including downloading, installing, and updating Python distributions with support for multiple versions and platforms.
153
154
```python { .api }
155
# Command: hatch python [subcommand] [options]
156
# Subcommands:
157
# install [version] Install Python version
158
# remove [version] Remove Python version
159
# show [version] Show Python info
160
# find [version] Find Python path
161
# update [version] Update Python version
162
```
163
164
Usage examples:
165
```bash
166
# Install Python 3.11
167
hatch python install 3.11
168
169
# Show available Python versions
170
hatch python show
171
172
# Find Python 3.10 path
173
hatch python find 3.10
174
175
# Update all Python installations
176
hatch python update
177
```
178
179
### Version Management
180
181
Manage project versioning including version bumping, tagging, and integration with version control systems.
182
183
```python { .api }
184
# Command: hatch version [options] [rule]
185
# Options:
186
# --dry-run Show version without updating
187
# --scheme TEXT Version scheme to use
188
# Rules:
189
# major, minor, patch, dev, alpha, beta, rc
190
```
191
192
### Configuration Management
193
194
Manage hatch configuration including user settings, project configuration, and environment variables with support for global and project-specific settings.
195
196
```python { .api }
197
# Command: hatch config [subcommand] [options]
198
# Subcommands:
199
# show [key] Show configuration value
200
# set [key] [value] Set configuration value
201
# find Find config file location
202
# restore Restore default configuration
203
```
204
205
### Project Operations
206
207
Manage project metadata, configuration, and operations including metadata display, configuration validation, and project introspection.
208
209
```python { .api }
210
# Command: hatch project [subcommand] [options]
211
# Subcommands:
212
# metadata Show project metadata
213
# config Show project configuration
214
```
215
216
### Build Artifact Management
217
218
Clean build artifacts and temporary files with support for custom clean patterns and selective cleaning.
219
220
```python { .api }
221
# Command: hatch clean [options]
222
# Options:
223
# --all Clean all artifacts
224
# --builds Clean build artifacts only
225
# --temp Clean temporary files only
226
```
227
228
### Shell Integration
229
230
Integrate with shell environments for enhanced development experience including shell activation, completion, and environment detection.
231
232
```python { .api }
233
# Command: hatch shell [options]
234
# Options:
235
# --name TEXT Environment name to activate
236
# --prompt TEXT Custom shell prompt
237
```
238
239
### Status Information
240
241
Display project status including environment information, dependency status, and configuration validation.
242
243
```python { .api }
244
# Command: hatch status [options]
245
# Options:
246
# --env TEXT Show specific environment status
247
# --all Show all environment status
248
```
249
250
### Self Management
251
252
Manage hatch installation including updates, restoration, and diagnostic reporting for troubleshooting and maintenance.
253
254
```python { .api }
255
# Command: hatch self [subcommand] [options]
256
# Subcommands:
257
# update Update hatch installation
258
# restore Restore hatch installation
259
# report Generate diagnostic report
260
```
261
262
## Global Options
263
264
All commands support these global options:
265
266
```python { .api }
267
# Global options available for all commands:
268
# -e, --env TEXT Environment name
269
# -p, --project TEXT Project name
270
# -v, --verbose Increase verbosity
271
# -q, --quiet Decrease verbosity
272
# --color/--no-color Control colored output
273
# --interactive/--no-interactive Control interactive features
274
# --data-dir TEXT Custom data directory
275
# --cache-dir TEXT Custom cache directory
276
# --config TEXT Custom config file
277
```
278
279
## Environment Variables
280
281
Commands respect these environment variables:
282
283
```python { .api }
284
# Application environment variables
285
HATCH_ENV='default' # Default environment name
286
HATCH_ENV_ACTIVE='env_name' # Currently active environment
287
HATCH_VERBOSE='1' # Verbose output level
288
HATCH_QUIET='1' # Quiet output level
289
HATCH_INTERACTIVE='true' # Interactive mode
290
HATCH_PYTHON='/path/to/python' # Python executable
291
292
# Configuration environment variables
293
HATCH_PROJECT='project_name' # Project name override
294
HATCH_DATA_DIR='/path/to/data' # Data directory
295
HATCH_CACHE_DIR='/path/to/cache' # Cache directory
296
HATCH_CONFIG='/path/to/config' # Configuration file
297
298
# Publishing environment variables
299
HATCH_INDEX_USER='username' # Package index username
300
HATCH_INDEX_AUTH='token' # Package index authentication
301
HATCH_INDEX_REPO='https://...' # Package index URL
302
```