0
# CLI Commands
1

2
Command-line interface providing comprehensive project management through terminal commands. Includes all Poetry CLI functionality for project creation, dependency management, building, publishing, and environment management.
3

4
## Capabilities
5

6
### CLI Application
7

8
Main command-line application providing the `poetry` command and all its subcommands.
9

10
```python { .api }
11
class Application:
12
    """
13
    Main CLI application for Poetry.
14
    
15
    Extends Cleo application framework to provide Poetry's
16
    command-line interface with plugin support and error handling.
17
    """
18
    
19
    def main(self) -> int:
20
        """
21
        Main entry point for CLI application.
22
        
23
        Returns:
24
            Exit code (0 for success, non-zero for errors)
25
        """
26
    
27
    def configure(self) -> None:
28
        """Configure application with commands and settings."""
29
    
30
    def load_plugins(self) -> None:
31
        """Load and register application plugins."""
32
    
33
    def handle_exception(self, exception: Exception) -> None:
34
        """Handle uncaught exceptions with user-friendly output."""
35
```
36

37
### Base Command Class
38

39
Abstract base class for all Poetry commands providing common functionality.
40

41
```python { .api }
42
class Command:
43
    """
44
    Base class for Poetry CLI commands.
45
    
46
    Provides common functionality for command implementation
47
    including Poetry instance access and error handling.
48
    """
49
    
50
    @property
51
    def poetry(self) -> Poetry:
52
        """Access to Poetry instance for current project."""
53
    
54
    def set_poetry(self, poetry: Poetry) -> None:
55
        """
56
        Set Poetry instance for command.
57
        
58
        Args:
59
            poetry: Poetry instance
60
        """
61
    
62
    def reset_poetry(self) -> None:
63
        """Reset Poetry instance."""
64
    
65
    def get_application(self) -> Application:
66
        """
67
        Get CLI application instance.
68
        
69
        Returns:
70
            Application instance
71
        """
72
    
73
    def handle(self) -> int:
74
        """
75
        Handle command execution (implemented by subclasses).
76
        
77
        Returns:
78
            Exit code (0 for success)
79
        """
80
```
81

82
## Core Commands
83

84
### Project Management Commands
85

86
Commands for creating and managing Poetry projects.
87

88
```python { .api }
89
class NewCommand(Command):
90
    """Create new Poetry project."""
91
    name = "new"
92
    description = "Create a new Python project at <path>"
93
    
94
    def handle(self) -> int:
95
        """Create new project structure with pyproject.toml."""
96

97
class InitCommand(Command):
98
    """Initialize existing directory as Poetry project."""
99
    name = "init"
100
    description = "Initialize a pre-existing project's pyproject.toml"
101
    
102
    def handle(self) -> int:
103
        """Initialize pyproject.toml in current directory."""
104

105
class CheckCommand(Command):
106
    """Validate project configuration."""
107
    name = "check"
108
    description = "Check the validity of the pyproject.toml file"
109
    
110
    def handle(self) -> int:
111
        """Validate pyproject.toml and report issues."""
112
```
113

114
### Dependency Management Commands
115

116
Commands for adding, removing, and updating dependencies.
117

118
```python { .api }
119
class AddCommand(Command):
120
    """Add dependencies to project."""
121
    name = "add"
122
    description = "Add and install packages to pyproject.toml"
123
    
124
    def handle(self) -> int:
125
        """Add dependencies and update lock file."""
126

127
class RemoveCommand(Command):
128
    """Remove dependencies from project."""
129
    name = "remove"
130
    description = "Remove packages from pyproject.toml"
131
    
132
    def handle(self) -> int:
133
        """Remove dependencies and update lock file."""
134

135
class UpdateCommand(Command):
136
    """Update dependencies to latest compatible versions."""
137
    name = "update"
138
    description = "Update dependencies to latest compatible versions"
139
    
140
    def handle(self) -> int:
141
        """Update dependencies and lock file."""
142

143
class ShowCommand(Command):
144
    """Show package information."""
145
    name = "show"
146
    description = "Show information about packages"
147
    
148
    def handle(self) -> int:
149
        """Display package information and dependencies."""
150
```
151

152
### Installation Commands
153

154
Commands for installing and synchronizing dependencies.
155

156
```python { .api }
157
class InstallCommand(Command):
158
    """Install project dependencies."""
159
    name = "install"
160
    description = "Install project dependencies"
161
    
162
    def handle(self) -> int:
163
        """Install dependencies from lock file."""
164

165
class SyncCommand(Command):
166
    """Synchronize environment with lock file."""
167
    name = "sync"
168
    description = "Synchronize environment with lock file"
169
    
170
    def handle(self) -> int:
171
        """Sync environment to match lock file exactly."""
172

173
class LockCommand(Command):
174
    """Generate or update lock file."""
175
    name = "lock"
176
    description = "Generate or update poetry.lock file"
177
    
178
    def handle(self) -> int:
179
        """Generate lock file without installing."""
180
```
181

182
### Build and Publishing Commands
183

184
Commands for building and publishing packages.
185

186
```python { .api }
187
class BuildCommand(Command):
188
    """Build package distributions."""
189
    name = "build"
190
    description = "Build the source and wheels archives"
191
    
192
    def handle(self) -> int:
193
        """Build wheel and source distributions."""
194

195
class PublishCommand(Command):
196
    """Publish package to repository."""
197
    name = "publish"
198
    description = "Publish the package to a remote repository"
199
    
200
    def handle(self) -> int:
201
        """Publish built packages to configured repository."""
202
```
203

204
### Environment Management Commands
205

206
Commands for managing virtual environments.
207

208
```python { .api }
209
class EnvInfoCommand(Command):
210
    """Show environment information."""
211
    name = "env info"
212
    description = "Show information about the current environment"
213
    
214
    def handle(self) -> int:
215
        """Display environment details."""
216

217
class EnvListCommand(Command):
218
    """List available environments."""
219
    name = "env list"
220
    description = "List the available environments"
221
    
222
    def handle(self) -> int:
223
        """List virtual environments for project."""
224

225
class EnvUseCommand(Command):
226
    """Select Python interpreter for project."""
227
    name = "env use"
228
    description = "Set the Python interpreter to use"
229
    
230
    def handle(self) -> int:
231
        """Configure Python interpreter."""
232

233
class EnvRemoveCommand(Command):
234
    """Remove virtual environment."""
235
    name = "env remove"
236
    description = "Remove virtual environment"
237
    
238
    def handle(self) -> int:
239
        """Remove project virtual environment."""
240

241
class EnvActivateCommand(Command):
242
    """Activate virtual environment."""
243
    name = "env activate"
244
    description = "Activate the project's virtual environment"
245
    
246
    def handle(self) -> int:
247
        """Generate activation commands for current shell."""
248
```
249

250
### Python Management Commands
251

252
Commands for managing Python interpreters with Poetry.
253

254
```python { .api }
255
class PythonInstallCommand(Command):
256
    """Install Python interpreter."""
257
    name = "python install" 
258
    description = "Install a Python interpreter"
259
    
260
    def handle(self) -> int:
261
        """Install specified Python version."""
262

263
class PythonListCommand(Command):
264
    """List available Python interpreters."""
265
    name = "python list"
266
    description = "List available Python interpreters"
267
    
268
    def handle(self) -> int:
269
        """Show installed and available Python versions."""
270

271
class PythonRemoveCommand(Command):
272
    """Remove Python interpreter."""
273
    name = "python remove"
274
    description = "Remove an installed Python interpreter"
275
    
276
    def handle(self) -> int:
277
        """Remove specified Python installation."""
278
```
279

280
### Configuration Commands
281

282
Commands for managing Poetry configuration.
283

284
```python { .api }
285
class ConfigCommand(Command):
286
    """Manage Poetry configuration."""
287
    name = "config"
288
    description = "Manage configuration settings"
289
    
290
    def handle(self) -> int:
291
        """Get, set, or list configuration values."""
292

293
class SourceAddCommand(Command):
294
    """Add package source."""
295
    name = "source add"
296
    description = "Add a package source"
297
    
298
    def handle(self) -> int:
299
        """Add package repository source."""
300

301
class SourceRemoveCommand(Command):
302
    """Remove package source."""
303
    name = "source remove"  
304
    description = "Remove a package source"
305
    
306
    def handle(self) -> int:
307
        """Remove package repository source."""
308

309
class SourceShowCommand(Command):
310
    """Show package sources."""
311
    name = "source show"
312
    description = "Show information about package sources"
313
    
314
    def handle(self) -> int:
315
        """Display configured package sources."""
316
```
317

318
### Utility Commands
319

320
Utility commands for package search, script running, and maintenance.
321

322
```python { .api }
323
class SearchCommand(Command):
324
    """Search for packages."""
325
    name = "search"
326
    description = "Search for packages on PyPI"
327
    
328
    def handle(self) -> int:
329
        """Search PyPI for packages."""
330

331
class RunCommand(Command):
332
    """Run scripts in virtual environment."""
333
    name = "run"
334
    description = "Run a command in the appropriate environment"
335
    
336
    def handle(self) -> int:
337
        """Execute command in project environment."""
338

339
class VersionCommand(Command):
340
    """Manage project version."""
341
    name = "version"
342
    description = "Show or update the project version"
343
    
344
    def handle(self) -> int:
345
        """Display or update project version."""
346

347
class CacheClearCommand(Command):
348
    """Clear Poetry cache."""
349
    name = "cache clear"
350
    description = "Clear Poetry's cache"
351
    
352
    def handle(self) -> int:
353
        """Clear cached data."""
354

355
class CacheListCommand(Command):
356
    """List cached packages."""
357
    name = "cache list"
358
    description = "List packages stored in cache"
359
    
360
    def handle(self) -> int:
361
        """Display cached package information."""
362
```
363

364
### Self-Management Commands
365

366
Commands for managing Poetry itself.
367

368
```python { .api }
369
class SelfInstallCommand(Command):
370
    """Install Poetry dependencies."""
371
    name = "self install"
372
    description = "Install Poetry itself"
373
    
374
    def handle(self) -> int:
375
        """Install or update Poetry."""
376

377
class SelfUpdateCommand(Command):
378
    """Update Poetry to latest version."""
379
    name = "self update"
380
    description = "Update Poetry to the latest version"
381
    
382
    def handle(self) -> int:
383
        """Update Poetry installation."""
384

385
class SelfShowCommand(Command):
386
    """Show Poetry information."""
387
    name = "self show"
388
    description = "Show information about Poetry's installation"
389
    
390
    def handle(self) -> int:
391
        """Display Poetry installation details."""
392
```
393

394
## Command Usage Examples
395

396
### Project Creation
397

398
```bash
399
# Create new project
400
poetry new my-project
401

402
# Initialize existing directory
403
poetry init
404

405
# Validate project configuration
406
poetry check
407
```
408

409
### Dependency Management
410

411
```bash
412
# Add dependencies
413
poetry add requests
414
poetry add pytest --group dev
415
poetry add "django>=3.2,<4.0"
416

417
# Remove dependencies
418
poetry remove requests
419
poetry remove pytest --group dev
420

421
# Update dependencies
422
poetry update
423
poetry update requests
424

425
# Show package information
426
poetry show
427
poetry show requests
428
poetry show --tree
429
```
430

431
### Installation and Environment
432

433
```bash
434
# Install dependencies
435
poetry install
436
poetry install --no-dev
437
poetry install --only dev
438

439
# Synchronize environment
440
poetry sync
441

442
# Generate lock file
443
poetry lock
444

445
# Environment management
446
poetry env info
447
poetry env list
448
poetry env use python3.11
449
poetry env remove test-env
450
```
451

452
### Building and Publishing
453

454
```bash
455
# Build distributions
456
poetry build
457
poetry build --format wheel
458

459
# Publish to PyPI
460
poetry publish
461
poetry publish --repository my-repo
462
```
463

464
### Configuration
465

466
```bash
467
# Configuration management
468
poetry config --list
469
poetry config virtualenvs.create false
470
poetry config repositories.my-repo https://repo.example.com
471

472
# Package sources
473
poetry source add my-repo https://repo.example.com
474
poetry source show
475
poetry source remove my-repo
476
```
477

478
### Utilities
479

480
```bash
481
# Search packages
482
poetry search requests
483

484
# Run commands in environment
485
poetry run python script.py
486
poetry run pytest
487

488
# Version management
489
poetry version
490
poetry version patch
491
poetry version 1.2.3
492

493
# Cache management
494
poetry cache clear pypi --all
495
```
496

497
## Custom Command Development
498

499
### Creating Custom Commands
500

501
```python
502
from poetry.console.commands.command import Command
503

504
class MyCustomCommand(Command):
505
    """Custom Poetry command."""
506
    
507
    name = "my-command"
508
    description = "My custom functionality"
509
    
510
    def handle(self):
511
        """Handle command execution."""
512
        # Access Poetry instance
513
        poetry = self.poetry
514
        
515
        # Access command arguments and options
516
        arg = self.argument("argument_name")
517
        opt = self.option("option_name")
518
        
519
        # Output to user
520
        self.line(f"Executing custom command for {poetry.package.name}")
521
        
522
        # Custom logic here
523
        result = self.perform_custom_logic()
524
        
525
        if result:
526
            self.line("<info>Success!</info>")
527
            return 0
528
        else:
529
            self.line("<error>Failed!</error>")
530
            return 1
531
    
532
    def perform_custom_logic(self):
533
        """Custom command logic."""
534
        return True
535
```
536

537
### Registering Commands via Plugin
538

539
```python
540
from poetry.plugins.application_plugin import ApplicationPlugin
541

542
class MyCommandPlugin(ApplicationPlugin):
543
    """Plugin that adds custom commands."""
544
    
545
    @property
546
    def commands(self):
547
        """Return custom commands."""
548
        return [MyCustomCommand()]
549
```
550

551
## Error Handling
552

553
CLI command exceptions and error conditions:
554

555
```python { .api }
556
class CommandError(PoetryError):
557
    """Base CLI command error."""
558

559
class CommandNotFoundError(CommandError):
560
    """Command not found or not available."""
561

562
class ArgumentError(CommandError):
563
    """Invalid command arguments or options."""
564

565
class ExecutionError(CommandError):
566
    """Command execution failures."""
567
```
568

569
Common CLI errors:
570
- Invalid command arguments or options
571
- Project not found or not initialized
572
- Permission errors accessing files or directories
573
- Network errors during package operations
574
- Environment activation or creation failures
575
- Configuration validation errors