0
# Command Line Interface
1

2
The Snowpack CLI provides commands for project initialization, development, building, and package management. It supports various flags for customizing behavior and integrates with the programmatic API.
3

4
## Capabilities
5

6
### CLI Entry Point
7

8
Main CLI function that processes command-line arguments and executes appropriate commands.
9

10
```typescript { .api }
11
/**
12
 * Main CLI entry point
13
 * @param args - Command line arguments array
14
 * @returns Promise resolving when command completes
15
 */
16
function cli(args: string[]): Promise<void>;
17
```
18

19
```typescript
20
import { cli } from "snowpack";
21

22
// Programmatic CLI usage
23
await cli(['node', 'snowpack', 'dev', '--port', '3000']);
24
await cli(['node', 'snowpack', 'build', '--verbose']);
25
```
26

27
### CLI Commands
28

29
Available commands for project management and development.
30

31
#### Initialize Project
32

33
```bash
34
snowpack init
35
```
36

37
Creates a new Snowpack configuration file in the current directory.
38

39
```typescript
40
// Equivalent programmatic usage
41
import { initCommand } from "snowpack/commands";
42
await initCommand({ config, lockfile });
43
```
44

45
#### Prepare Dependencies
46

47
```bash
48
snowpack prepare
49
```
50

51
Prepares dependencies for development (installs and processes packages).
52

53
```typescript
54
// Equivalent programmatic usage  
55
import { preparePackages } from "snowpack";
56
await preparePackages({ config });
57
```
58

59
#### Development Server
60

61
```bash
62
snowpack dev
63
```
64

65
Starts the development server with hot module replacement.
66

67
```typescript
68
// Equivalent programmatic usage
69
import { startServer } from "snowpack";
70
const server = await startServer({ config, lockfile });
71
```
72

73
#### Production Build
74

75
```bash
76
snowpack build
77
```
78

79
Builds the project for production deployment.
80

81
```typescript
82
// Equivalent programmatic usage
83
import { build } from "snowpack";
84
const result = await build({ config, lockfile });
85
```
86

87
#### Package Management
88

89
```bash
90
snowpack add <package>
91
snowpack rm <package>
92
```
93

94
Add or remove packages from the project.
95

96
```typescript
97
// Equivalent programmatic usage
98
import { addCommand, rmCommand } from "snowpack/commands";
99
await addCommand('react', { config, lockfile });
100
await rmCommand('lodash', { config, lockfile });
101
```
102

103
## CLI Flags
104

105
### Global Flags
106

107
Flags available for all commands.
108

109
```typescript { .api }
110
/**
111
 * CLI flags interface
112
 */
113
interface CLIFlags {
114
  /** Display help message */
115
  help?: boolean;
116
  /** Display version information */
117
  version?: boolean;
118
  /** Clear local cache before running */
119
  reload?: boolean;
120
  /** Specify project root directory */
121
  root?: string;
122
  /** Path to configuration file */
123
  config?: string;
124
  /** Environment variables to set */
125
  env?: string[];
126
  /** URLs/browsers to open */
127
  open?: string[];
128
  /** Enable HTTPS */
129
  secure?: boolean;
130
  /** Enable verbose logging */
131
  verbose?: boolean;
132
  /** Enable minimal logging */
133
  quiet?: boolean;
134
  /** Additional custom flags */
135
  [flag: string]: any;
136
}
137
```
138

139
### Help and Version
140

141
```bash
142
# Display help information
143
snowpack --help
144
snowpack -h
145

146
# Display version information  
147
snowpack --version
148
snowpack -v
149
```
150

151
### Configuration
152

153
```bash
154
# Use custom config file
155
snowpack dev --config ./custom.config.js
156

157
# Set project root
158
snowpack build --root ./my-app
159

160
# Clear cache before running
161
snowpack dev --reload
162
```
163

164
### Logging
165

166
```bash
167
# Verbose logging (show debug information)
168
snowpack build --verbose
169

170
# Quiet logging (minimal output)
171
snowpack build --quiet
172
```
173

174
### Development Server Flags
175

176
```bash
177
# Custom port
178
snowpack dev --port 8080
179

180
# Custom hostname
181
snowpack dev --hostname 0.0.0.0
182

183
# Enable HTTPS
184
snowpack dev --secure
185

186
# Open in browser
187
snowpack dev --open chrome
188
snowpack dev --open "google chrome"
189

190
# Set environment variables
191
snowpack dev --env NODE_ENV=development --env DEBUG=true
192
```
193

194
### Build Flags
195

196
```bash
197
# Watch mode (rebuild on changes)
198
snowpack build --watch
199

200
# Custom output directory
201
snowpack build --out ./dist
202

203
# Clean output directory
204
snowpack build --clean
205

206
# Generate source maps
207
snowpack build --sourcemap inline
208
```
209

210
## Command Implementation
211

212
### Command Structure
213

214
Each command follows a consistent structure with configuration loading and error handling.
215

216
```typescript
217
// Basic command structure
218
export async function commandName(commandOptions: CommandOptions) {
219
  try {
220
    const { config, lockfile } = commandOptions;
221
    
222
    // Command-specific logic here
223
    await performCommandLogic(config, lockfile);
224
    
225
  } catch (error) {
226
    logger.error(error.message);
227
    logger.error(error.stack);
228
    process.exit(1);
229
  }
230
}
231
```
232

233
### Error Handling
234

235
CLI commands include comprehensive error handling with helpful messages.
236

237
```bash
238
# Example error output
239
❌ Build failed: Configuration validation error
240
   → Missing required field "mount" in snowpack.config.js
241
   → See https://snowpack.dev/reference/configuration
242

243
❌ Development server failed to start
244
   → Port 3000 is already in use
245
   → Try using --port flag with a different port number
246
```
247

248
### Configuration Loading
249

250
The CLI automatically loads configuration with the following precedence:
251

252
1. Command-line flags (highest priority)
253
2. Configuration file specified by `--config`
254
3. Default configuration files (`snowpack.config.js`, etc.)
255
4. `package.json` snowpack field
256
5. Built-in defaults (lowest priority)
257

258
```typescript
259
// CLI configuration loading process
260
const cliFlags = parseArgs(args);
261
const cliConfig = expandCliFlags(cliFlags);
262
const config = await loadConfiguration(cliConfig, cliFlags.config);
263
```
264

265
## Binary Interface
266

267
### Executable Files
268

269
Snowpack provides two binary aliases:
270

271
```bash
272
# Full name
273
snowpack dev
274

275
# Short alias
276
sp dev
277
```
278

279
### Node.js Requirements
280

281
```bash
282
# Check Node.js version
283
node --version  # Must be 10.19.0 or higher
284
```
285

286
### Package Manager Integration
287

288
```bash
289
# Using npm scripts
290
npm run dev     # "dev": "snowpack dev"
291
npm run build   # "build": "snowpack build"
292

293
# Using yarn
294
yarn dev
295
yarn build
296

297
# Using pnpm  
298
pnpm dev
299
pnpm build
300
```
301

302
## Environment Variables
303

304
### Snowpack Environment Variables
305

306
```bash
307
# Set via CLI
308
snowpack dev --env NODE_ENV=development
309

310
# Set in shell
311
export NODE_ENV=development
312
snowpack dev
313

314
# Public variables (available in browser)
315
export SNOWPACK_PUBLIC_API_URL=https://api.example.com
316
```
317

318
### Configuration via Environment
319

320
```bash
321
# Override config file location
322
export SNOWPACK_CONFIG=./custom.config.js
323

324
# Set cache directory
325
export SNOWPACK_CACHE_DIR=./custom-cache
326
```
327

328
## Exit Codes
329

330
The CLI uses standard exit codes:
331

332
- `0`: Success
333
- `1`: General error (build failure, configuration error, etc.)
334
- `130`: Interrupted by user (Ctrl+C)
335

336
```bash
337
# Check exit code in scripts
338
snowpack build
339
if [ $? -eq 0 ]; then
340
  echo "Build successful"
341
else
342
  echo "Build failed"
343
  exit 1
344
fi
345
```
346

347
## Integration Examples
348

349
### CI/CD Integration
350

351
```yaml
352
# GitHub Actions example
353
- name: Build with Snowpack
354
  run: |
355
    npm ci
356
    npx snowpack build --verbose
357
    
358
# Docker example
359
RUN npm ci && npm run build
360
```
361

362
### Development Workflow
363

364
```bash
365
# Development setup
366
npm install
367
snowpack prepare  # Optional: pre-install dependencies
368
snowpack dev      # Start development server
369

370
# Production build
371
snowpack build
372
snowpack build --watch  # Watch mode for testing
373
```
374

375
### Package Scripts
376

377
```json
378
{
379
  "scripts": {
380
    "start": "snowpack dev",
381
    "build": "snowpack build",
382
    "build:watch": "snowpack build --watch",
383
    "clean": "snowpack build --clean",
384
    "prepare": "snowpack prepare"
385
  }
386
}
387
```