0
# Command Line Interface
1

2
Comprehensive command-line tools for building assets, managing bundles, and integrating with deployment workflows through the `webassets` command.
3

4
## Capabilities
5

6
### Command Line Environment
7

8
Main interface class for command-line asset management operations.
9

10
```python { .api }
11
class CommandLineEnvironment:
12
    def __init__(self, env, log_level='INFO'):
13
        """
14
        Command-line interface for webassets.
15
        
16
        Parameters:
17
        - env: Environment instance
18
        - log_level: Logging level for output
19
        """
20
    
21
    def build(self, bundles=None, force=False, no_cache=False, production=False):
22
        """
23
        Build bundles from command line.
24
        
25
        Parameters:
26
        - bundles: Specific bundles to build (None for all)
27
        - force: Force rebuild even if cache is valid
28
        - no_cache: Disable caching for this build
29
        - production: Use production settings
30
        """
31
    
32
    def watch(self, bundles=None):
33
        """
34
        Watch files and rebuild automatically.
35
        
36
        Parameters:
37
        - bundles: Specific bundles to watch (None for all)
38
        """
39
    
40
    def clean(self):
41
        """Clean generated files and cache."""
42
    
43
    def check(self):
44
        """Check bundle configuration for errors."""
45
```
46

47
### Command Base Classes
48

49
Foundation classes for implementing command-line operations.
50

51
```python { .api }
52
class Command:
53
    name = None
54
    help = None
55
    
56
    def add_parser(self, subparsers):
57
        """Add command parser to argument parser."""
58
    
59
    def run(self, args, env):
60
        """
61
        Execute command.
62
        
63
        Parameters:
64
        - args: Parsed command arguments
65
        - env: Environment instance
66
        """
67

68
class BuildCommand(Command):
69
    name = 'build'
70
    help = 'Build asset bundles'
71
    
72
    def run(self, args, env):
73
        """Execute build command."""
74

75
class WatchCommand(Command):
76
    name = 'watch'  
77
    help = 'Watch files and rebuild automatically'
78
    
79
    def run(self, args, env):
80
        """Execute watch command."""
81

82
class CleanCommand(Command):
83
    name = 'clean'
84
    help = 'Clean generated files'
85
    
86
    def run(self, args, env):
87
        """Execute clean command."""
88

89
class CheckCommand(Command):
90
    name = 'check'
91
    help = 'Check bundle configuration'
92
    
93
    def run(self, args, env):
94
        """Execute check command."""
95
```
96

97
### Main Entry Point
98

99
Primary function for command-line interface execution.
100

101
```python { .api }
102
def main(argv=None):
103
    """
104
    Main entry point for command-line interface.
105
    
106
    Parameters:
107
    - argv: Command line arguments (defaults to sys.argv)
108
    
109
    Returns:
110
    Exit code (0 for success, non-zero for error)
111
    """
112
```
113

114
### Command Exceptions
115

116
Exception handling for command-line operations.
117

118
```python { .api }
119
class CommandError(Exception):
120
    """Raised by command-line operations."""
121
```
122

123
## Command Usage Examples
124

125
### Basic Commands
126

127
```bash
128
# Build all bundles
129
webassets build
130

131
# Build specific bundles
132
webassets build js_all css_all
133

134
# Force rebuild (ignore cache)
135
webassets build --force
136

137
# Build without cache
138
webassets build --no-cache
139

140
# Production build
141
webassets build --production
142

143
# Watch for changes and rebuild
144
webassets watch
145

146
# Watch specific bundles
147
webassets watch js_all
148

149
# Clean generated files
150
webassets clean
151

152
# Check configuration
153
webassets check
154
```
155

156
### Advanced Command Options
157

158
```bash
159
# Build with custom environment file
160
webassets -c assets.yaml build
161

162
# Build with verbose output
163
webassets -v build
164

165
# Build with specific log level
166
webassets --log-level DEBUG build
167

168
# Build and specify output directory
169
webassets --env-directory ./dist build
170

171
# Build with custom configuration
172
webassets --env-url /static --env-debug false build
173
```
174

175
### Configuration File Usage
176

177
Create an `assets.yaml` configuration file:
178

179
```yaml
180
directory: ./static
181
url: /static
182
debug: false
183
cache: filesystem
184
auto_build: false
185

186
bundles:
187
  js_all:
188
    contents:
189
      - js/app.js
190
      - js/utils.js
191
    filters: uglifyjs
192
    output: gen/app.js
193
    
194
  css_all:
195
    contents:
196
      - css/main.css
197
      - css/layout.css
198
    filters: cssmin
199
    output: gen/app.css
200
```
201

202
Then use it:
203

204
```bash
205
# Use configuration file
206
webassets -c assets.yaml build
207

208
# Override configuration options
209
webassets -c assets.yaml --env-debug build
210
```
211

212
## Programming Interface
213

214
### Programmatic Command Execution
215

216
```python
217
from webassets.script import CommandLineEnvironment
218
from webassets import Environment
219

220
# Create environment
221
env = Environment('./static', '/static')
222

223
# Register bundles
224
env.register('js_all', 'app.js', 'utils.js', filters='jsmin', output='gen/app.js')
225
env.register('css_all', 'style.css', filters='cssmin', output='gen/style.css')
226

227
# Create command-line interface
228
cmdline = CommandLineEnvironment(env)
229

230
# Build all bundles
231
cmdline.build()
232

233
# Build specific bundles
234
cmdline.build(['js_all'])
235

236
# Force rebuild
237
cmdline.build(force=True)
238

239
# Clean generated files
240
cmdline.clean()
241

242
# Check configuration
243
cmdline.check()
244
```
245

246
### Custom Command Implementation
247

248
```python
249
from webassets.script import Command
250

251
class DeployCommand(Command):
252
    name = 'deploy'
253
    help = 'Deploy assets to CDN'
254
    
255
    def add_parser(self, subparsers):
256
        parser = subparsers.add_parser(self.name, help=self.help)
257
        parser.add_argument('--cdn-url', help='CDN base URL')
258
        parser.add_argument('--aws-profile', help='AWS profile to use')
259
        return parser
260
    
261
    def run(self, args, env):
262
        # Build assets first
263
        cmdline = CommandLineEnvironment(env)
264
        cmdline.build(production=True)
265
        
266
        # Deploy to CDN
267
        import boto3
268
        s3 = boto3.client('s3', profile_name=args.aws_profile)
269
        
270
        for bundle_name, bundle in env:
271
            output_files = bundle.urls()
272
            for file_url in output_files:
273
                local_path = os.path.join(env.directory, file_url.lstrip('/'))
274
                s3_key = file_url.lstrip('/')
275
                
276
                s3.upload_file(local_path, 'my-assets-bucket', s3_key)
277
                print(f"Deployed {file_url} to CDN")
278

279
# Register custom command
280
from webassets.script import main
281
import sys
282

283
def custom_main():
284
    # Add custom command to available commands
285
    from webassets.script import commands
286
    commands.append(DeployCommand())
287
    
288
    # Run main CLI
289
    return main()
290

291
if __name__ == '__main__':
292
    sys.exit(custom_main())
293
```
294

295
### Integration with Build Tools
296

297
#### Makefile Integration
298

299
```makefile
300
# Makefile
301
SHELL := /bin/bash
302

303
.PHONY: assets assets-watch assets-clean assets-check
304

305
assets:
306
	webassets build
307

308
assets-watch:
309
	webassets watch
310

311
assets-clean:
312
	webassets clean
313

314
assets-check:
315
	webassets check
316

317
# Production build
318
assets-prod:
319
	webassets build --production
320

321
# Development setup
322
dev-setup: assets-clean assets
323

324
# Full deployment
325
deploy: assets-clean assets-prod
326
	# Additional deployment steps
327
```
328

329
#### npm Scripts Integration
330

331
```json
332
{
333
  "scripts": {
334
    "build": "webassets build",
335
    "build:prod": "webassets build --production",
336
    "watch": "webassets watch", 
337
    "clean": "webassets clean",
338
    "check": "webassets check"
339
  }
340
}
341
```
342

343
#### Docker Integration
344

345
```dockerfile
346
FROM python:3.11
347

348
# Install dependencies
349
COPY requirements.txt .
350
RUN pip install -r requirements.txt
351

352
# Copy assets configuration
353
COPY assets.yaml .
354

355
# Copy source assets
356
COPY static/ ./static/
357

358
# Build assets
359
RUN webassets -c assets.yaml build --production
360

361
# Copy application code
362
COPY . .
363

364
CMD ["python", "app.py"]
365
```
366

367
### CI/CD Integration
368

369
#### GitHub Actions
370

371
```yaml
372
# .github/workflows/assets.yml
373
name: Build Assets
374

375
on:
376
  push:
377
    branches: [main]
378
  pull_request:
379
    branches: [main]
380

381
jobs:
382
  build-assets:
383
    runs-on: ubuntu-latest
384
    
385
    steps:
386
    - uses: actions/checkout@v3
387
    
388
    - name: Set up Python
389
      uses: actions/setup-python@v4
390
      with:
391
        python-version: '3.11'
392
    
393
    - name: Install dependencies
394
      run: |
395
        pip install -r requirements.txt
396
    
397
    - name: Check asset configuration
398
      run: webassets check
399
    
400
    - name: Build assets
401
      run: webassets build --production
402
    
403
    - name: Upload assets
404
      uses: actions/upload-artifact@v3
405
      with:
406
        name: built-assets
407
        path: static/gen/
408
```
409

410
#### Jenkins Pipeline
411

412
```groovy
413
pipeline {
414
    agent any
415
    
416
    stages {
417
        stage('Install Dependencies') {
418
            steps {
419
                sh 'pip install -r requirements.txt'
420
            }
421
        }
422
        
423
        stage('Check Assets') {
424
            steps {
425
                sh 'webassets check'
426
            }
427
        }
428
        
429
        stage('Build Assets') {
430
            steps {
431
                sh 'webassets build --production'
432
            }
433
        }
434
        
435
        stage('Archive Assets') {
436
            steps {
437
                archiveArtifacts artifacts: 'static/gen/**/*', fingerprint: true
438
            }
439
        }
440
    }
441
}
442
```
443

444
### Environment-Specific Configurations
445

446
```bash
447
# Development
448
export WEBASSETS_ENV=development
449
webassets build
450

451
# Staging  
452
export WEBASSETS_ENV=staging
453
webassets build --production
454

455
# Production
456
export WEBASSETS_ENV=production
457
webassets build --production --no-cache
458
```
459

460
With corresponding configuration files:
461

462
```python
463
# assets.py
464
import os
465

466
env_name = os.environ.get('WEBASSETS_ENV', 'development')
467

468
if env_name == 'development':
469
    directory = './src/static'
470
    debug = True
471
    cache = False
472
elif env_name == 'staging':
473
    directory = './build/static'
474
    debug = False
475
    cache = True
476
    versions = 'timestamp'
477
elif env_name == 'production':
478
    directory = './dist/static'
479
    debug = False
480
    cache = True
481
    versions = 'hash'
482
    manifest = 'json:manifest.json'
483
```
484

485
### Automated Asset Pipeline
486

487
```python
488
#!/usr/bin/env python
489
"""
490
Automated asset pipeline script
491
"""
492

493
import os
494
import sys
495
from webassets.script import CommandLineEnvironment
496
from webassets.loaders import YAMLLoader
497

498
def build_assets(config_file='assets.yaml', environment='production'):
499
    """Build assets with specified configuration."""
500
    
501
    # Load configuration
502
    loader = YAMLLoader(config_file)
503
    env = loader.load_environment()
504
    
505
    # Override environment settings
506
    if environment == 'production':
507
        env.debug = False
508
        env.cache = True
509
        env.versions = 'hash'
510
        env.manifest = 'json:manifest.json'
511
    elif environment == 'development':
512
        env.debug = True
513
        env.cache = False
514
        env.versions = False
515
    
516
    # Create command line interface
517
    cmdline = CommandLineEnvironment(env, log_level='INFO')
518
    
519
    # Check configuration
520
    print("Checking asset configuration...")
521
    cmdline.check()
522
    
523
    # Clean previous build
524
    print("Cleaning previous build...")
525
    cmdline.clean()
526
    
527
    # Build assets
528
    print(f"Building assets for {environment}...")
529
    cmdline.build(production=(environment == 'production'))
530
    
531
    print("Asset build completed successfully!")
532

533
if __name__ == '__main__':
534
    env = sys.argv[1] if len(sys.argv) > 1 else 'production'
535
    build_assets(environment=env)
536
```
537

538
Usage:
539
```bash
540
python build_assets.py development
541
python build_assets.py production
542
```