0
# Command Line Interface
1
2
Complete CLI with 15 commands for managing Python projects including installation, environment management, dependency resolution, and project operations. The CLI is built using Click and provides both individual commands and a main group with global options.
3
4
## Capabilities
5
6
### Main CLI Group
7
8
The main CLI entry point with global options that apply to all subcommands.
9
10
```python { .api }
11
def cli():
12
"""
13
Main CLI group with global options.
14
15
Global Options:
16
--where: Output project home information
17
--venv: Output virtualenv information
18
--py: Output Python interpreter information
19
--envs: Output environment variable options
20
--rm: Remove the virtualenv
21
--bare: Minimal output
22
--man: Display manpage
23
--support: Output diagnostic information
24
--version: Show version information
25
--verbose: Verbose output
26
--quiet: Quiet output
27
--clear: Clear caches
28
--python: Specify Python version
29
"""
30
```
31
32
### Package Installation
33
34
Install packages from PyPI, VCS, or local paths and automatically add them to Pipfile.
35
36
```python { .api }
37
def install(*packages, dev=False, pre=False, editable=False, system=False,
38
ignore_pipfile=False, skip_lock=False, requirements=None, **kwargs):
39
"""
40
Install packages and add to Pipfile, or install all from Pipfile.
41
42
Parameters:
43
packages: Package names to install
44
dev: Install as development dependency
45
pre: Allow pre-release packages
46
editable: Install package in editable mode
47
system: Use system pip instead of virtualenv
48
ignore_pipfile: Ignore Pipfile and install from command line only
49
skip_lock: Skip locking mechanism
50
requirements: Install from requirements.txt file
51
"""
52
```
53
54
Usage examples:
55
```bash
56
pipenv install requests # Install and add to Pipfile
57
pipenv install pytest --dev # Install as dev dependency
58
pipenv install -e git+https://... # Install from git in editable mode
59
pipenv install --requirements requirements.txt # Install from requirements.txt
60
pipenv install # Install all from Pipfile
61
```
62
63
### Package Removal
64
65
Remove packages from the virtual environment and Pipfile.
66
67
```python { .api }
68
def uninstall(*packages, all_dev=False, all=False, dev=False):
69
"""
70
Remove packages from virtualenv and Pipfile.
71
72
Parameters:
73
packages: Package names to uninstall
74
all_dev: Remove all development packages
75
all: Remove all packages
76
dev: Remove from development dependencies
77
"""
78
```
79
80
Usage examples:
81
```bash
82
pipenv uninstall requests # Remove specific package
83
pipenv uninstall --all-dev # Remove all dev packages
84
pipenv uninstall --all # Remove all packages
85
```
86
87
### Package Updates
88
89
Update packages to newer versions and regenerate lock file.
90
91
```python { .api }
92
def update(*packages, dev=False, bare=False, outdated=False, dry_run=False):
93
"""
94
Run lock, then sync (or upgrade specific packages).
95
96
Parameters:
97
packages: Specific packages to update
98
dev: Include development packages
99
bare: Minimal output
100
outdated: Show outdated packages
101
dry_run: Show what would be updated without making changes
102
"""
103
104
def upgrade(*packages, dev=False, pre=False, lock_only=False):
105
"""
106
Resolve and upgrade packages, merge results to Pipfile.lock.
107
108
Parameters:
109
packages: Specific packages to upgrade
110
dev: Include development packages
111
pre: Allow pre-release packages
112
lock_only: Only update lock file, don't install
113
"""
114
```
115
116
Usage examples:
117
```bash
118
pipenv update # Update all packages
119
pipenv update requests # Update specific package
120
pipenv update --outdated # Show outdated packages
121
pipenv upgrade # Upgrade packages and lock
122
```
123
124
### Dependency Locking
125
126
Generate and manage Pipfile.lock for deterministic builds.
127
128
```python { .api }
129
def lock(dev=False, dev_only=False, pre=False, categories=None):
130
"""
131
Generate Pipfile.lock.
132
133
Parameters:
134
dev: Include development dependencies
135
dev_only: Only include development dependencies
136
pre: Allow pre-release packages
137
categories: Specific categories to lock
138
"""
139
```
140
141
Usage examples:
142
```bash
143
pipenv lock # Generate lock file
144
pipenv lock --dev # Include dev dependencies
145
pipenv lock --dev-only # Only dev dependencies
146
```
147
148
### Environment Synchronization
149
150
Install packages exactly as specified in Pipfile.lock.
151
152
```python { .api }
153
def sync(bare=False, dev=False, system=False):
154
"""
155
Install packages from Pipfile.lock.
156
157
Parameters:
158
bare: Minimal output
159
dev: Include development packages
160
system: Use system pip
161
"""
162
```
163
164
Usage examples:
165
```bash
166
pipenv sync # Install from lock file
167
pipenv sync --dev # Include dev packages
168
```
169
170
### Shell Activation
171
172
Spawn a shell within the virtual environment.
173
174
```python { .api }
175
def shell(fancy=False, anyway=False, quiet=False, *args):
176
"""
177
Spawn shell within virtualenv.
178
179
Parameters:
180
fancy: Use fancy shell prompt
181
anyway: Always spawn shell even if already active
182
quiet: Quiet output
183
args: Additional shell arguments
184
"""
185
```
186
187
Usage examples:
188
```bash
189
pipenv shell # Activate environment shell
190
pipenv shell --fancy # Use fancy prompt
191
```
192
193
### Command Execution
194
195
Execute commands within the virtual environment.
196
197
```python { .api }
198
def run(*command):
199
"""
200
Execute command in virtualenv.
201
202
Parameters:
203
command: Command name and arguments to execute
204
"""
205
```
206
207
Usage examples:
208
```bash
209
pipenv run python script.py # Run Python script
210
pipenv run pytest # Run tests
211
pipenv run python -m module # Run module
212
```
213
214
### Dependency Analysis
215
216
Display dependency graph and analyze package relationships.
217
218
```python { .api }
219
def graph(bare=False, json=False, json_tree=False, reverse=False):
220
"""
221
Display dependency graph information.
222
223
Parameters:
224
bare: Minimal output
225
json: Output in JSON format
226
json_tree: Output JSON dependency tree
227
reverse: Show reverse dependencies
228
"""
229
```
230
231
Usage examples:
232
```bash
233
pipenv graph # Show dependency graph
234
pipenv graph --json # JSON output
235
pipenv graph --reverse # Show reverse dependencies
236
```
237
238
### Environment Cleanup
239
240
Remove packages not specified in Pipfile.lock.
241
242
```python { .api }
243
def clean(bare=False, dry_run=False):
244
"""
245
Remove packages not in Pipfile.lock.
246
247
Parameters:
248
bare: Minimal output
249
dry_run: Show what would be removed without making changes
250
"""
251
```
252
253
Usage examples:
254
```bash
255
pipenv clean # Remove extra packages
256
pipenv clean --dry-run # Show what would be removed
257
```
258
259
### Security Checking
260
261
Check for security vulnerabilities in installed packages (deprecated).
262
263
```python { .api }
264
def check(db=None, ignore=None, output="screen", key=None, scan=False, auto_install=False):
265
"""
266
Security vulnerability checks via PyUp Safety (DEPRECATED).
267
268
Parameters:
269
db: Path to safety database
270
ignore: Ignore specific vulnerabilities
271
output: Output format (screen, text, json)
272
key: API key for safety service
273
scan: Full environment scan
274
auto_install: Auto-install safety if missing
275
"""
276
```
277
278
### Requirements Generation
279
280
Generate requirements.txt files from Pipfile.lock.
281
282
```python { .api }
283
def requirements(dev=False, dev_only=False, hash=False, exclude_markers=False, categories=None):
284
"""
285
Generate requirements.txt from Pipfile.lock.
286
287
Parameters:
288
dev: Include development packages
289
dev_only: Only development packages
290
hash: Include package hashes
291
exclude_markers: Exclude environment markers
292
categories: Specific categories to include
293
"""
294
```
295
296
Usage examples:
297
```bash
298
pipenv requirements > requirements.txt # Generate requirements
299
pipenv requirements --dev --hash # Include dev deps with hashes
300
```
301
302
### Project Information
303
304
Access project information and locations.
305
306
```python { .api }
307
def scripts():
308
"""List scripts from Pipfile."""
309
310
def open(module_name):
311
"""
312
Open module in editor.
313
314
Parameters:
315
module_name: Name of module to open
316
"""
317
318
def verify():
319
"""Verify Pipfile.lock hash is up-to-date."""
320
```
321
322
Usage examples:
323
```bash
324
pipenv scripts # List available scripts
325
pipenv open requests # Open module in editor
326
pipenv verify # Verify lock file integrity
327
```
328
329
## CLI Options System
330
331
### State Management
332
333
The CLI uses state objects to pass configuration between commands and business logic.
334
335
```python { .api }
336
class State:
337
"""
338
Main state container with project, install state, and global options.
339
340
Attributes:
341
project: Project instance
342
installstate: Installation state
343
quiet: Quiet output flag
344
verbose: Verbose output flag
345
clear: Clear caches flag
346
python: Python version specification
347
"""
348
349
class InstallState:
350
"""
351
Installation-specific options and package lists.
352
353
Attributes:
354
packages: List of packages to install
355
dev: Development dependency flag
356
pre: Pre-release flag
357
system: System pip flag
358
"""
359
360
class LockOptions:
361
"""
362
Lock-specific options.
363
364
Attributes:
365
dev: Include development dependencies
366
pre: Allow pre-release packages
367
"""
368
```
369
370
### Option Decorators
371
372
Reusable option decorators for CLI commands.
373
374
```python { .api }
375
def pass_state(f):
376
"""Click decorator for state passing."""
377
378
def common_options(f):
379
"""Common CLI options: pypi-mirror, verbose, quiet, clear, python."""
380
381
def install_options(f):
382
"""Install-related options including packages, dev, pre, etc."""
383
384
def lock_options(f):
385
"""Lock-specific options including dev-only flag."""
386
387
def sync_options(f):
388
"""Sync-specific options."""
389
390
def general_options(f):
391
"""Common + site-packages options."""
392
```
393
394
## Context Settings
395
396
CLI context configuration for Click framework.
397
398
```python { .api }
399
CONTEXT_SETTINGS = {
400
"help_option_names": ["-h", "--help"],
401
"auto_envvar_prefix": "PIPENV"
402
}
403
```
404
405
The CLI automatically maps environment variables with the `PIPENV_` prefix to corresponding command options.