0
# Command Line Interface
1

2
Full-featured CLI for browser management operations including installation, launching, listing, and cleanup. Provides complete access to all browser management functionality through command-line interface with interactive features and comprehensive help system.
3

4
## Capabilities
5

6
### CLI Class
7

8
Main command-line interface class providing browser management operations through command-line arguments.
9

10
```typescript { .api }
11
/**
12
 * Command-line interface for browser management
13
 */
14
class CLI {
15
  /**
16
   * Create CLI instance with configuration options
17
   * @param opts - Cache path string or configuration options
18
   * @param rl - Optional readline interface for interactive features
19
   */
20
  constructor(opts?: string | CLIOptions, rl?: readline.Interface);
21
  
22
  /**
23
   * Execute CLI with provided command-line arguments
24
   * @param argv - Command line arguments array (typically process.argv)
25
   * @returns Promise resolving when command execution completes
26
   */
27
  run(argv: string[]): Promise<void>;
28
}
29

30
interface CLIOptions {
31
  /** Cache directory path */
32
  cachePath?: string;
33
  /** Script name for help text */
34
  scriptName?: string;
35
  /** Version string */
36
  version?: string;
37
  /** Command prefix configuration */
38
  prefixCommand?: {
39
    cmd: string;
40
    description: string;
41
  };
42
  /** Allow cache path override via arguments */
43
  allowCachePathOverride?: boolean;
44
  /** Pinned browser configurations */
45
  pinnedBrowsers?: Partial<Record<Browser, {
46
    buildId: string;
47
    skipDownload: boolean;
48
  }>>;
49
}
50
```
51

52
**Usage Examples:**
53

54
```typescript
55
import { CLI } from "@puppeteer/browsers";
56

57
// Basic CLI usage
58
const cli = new CLI("./browsers-cache");
59
await cli.run(process.argv);
60

61
// Advanced CLI configuration
62
const advancedCli = new CLI({
63
  cachePath: "./custom-cache",
64
  scriptName: "my-browser-manager",
65
  version: "1.0.0",
66
  allowCachePathOverride: true,
67
  pinnedBrowsers: {
68
    [Browser.CHROME]: {
69
      buildId: "118.0.5993.70",
70
      skipDownload: false
71
    }
72
  }
73
});
74

75
await advancedCli.run([
76
  "node", "script.js", 
77
  "install", "chrome@stable"
78
]);
79
```
80

81
## Available Commands
82

83
### Install Command
84

85
Downloads and installs browsers with support for version specifications, platform targeting, and progress tracking.
86

87
**Command Syntax:**
88
```bash
89
npx @puppeteer/browsers install [browser[@version]] [options]
90
```
91

92
**Options:**
93
- `--platform <platform>` - Target platform (linux, mac, win32, etc.)
94
- `--path <path>` - Cache directory path
95
- `--base-url <url>` - Custom download base URL
96
- `--install-deps` - Install system dependencies (Linux Chrome only)
97

98
**Usage Examples:**
99

100
```bash
101
# Install latest stable Chrome
102
npx @puppeteer/browsers install chrome@stable
103

104
# Install specific Chrome version
105
npx @puppeteer/browsers install chrome@118.0.5993.70
106

107
# Install Chrome for specific platform
108
npx @puppeteer/browsers install chrome@stable --platform linux
109

110
# Install Firefox nightly
111
npx @puppeteer/browsers install firefox@nightly
112

113
# Install ChromeDriver
114
npx @puppeteer/browsers install chromedriver@stable
115

116
# Install with system dependencies (requires root on Linux)
117
npx @puppeteer/browsers install chrome@stable --install-deps
118

119
# Install to custom cache directory
120
npx @puppeteer/browsers install chrome@stable --path ./my-cache
121
```
122

123
### Launch Command
124

125
Launches installed browsers with customizable arguments and configuration options.
126

127
**Command Syntax:**
128
```bash
129
npx @puppeteer/browsers launch <browser[@version]> [options] [-- browser-args...]
130
```
131

132
**Options:**
133
- `--detached` - Launch in detached mode
134
- `--system` - Use system-installed browser instead of cached
135
- `--dumpio` - Forward browser output to console
136

137
**Usage Examples:**
138

139
```bash
140
# Launch installed Chrome
141
npx @puppeteer/browsers launch chrome@stable
142

143
# Launch with browser arguments
144
npx @puppeteer/browsers launch chrome@stable -- --headless --no-sandbox
145

146
# Launch system Chrome
147
npx @puppeteer/browsers launch chrome@stable --system
148

149
# Launch detached browser
150
npx @puppeteer/browsers launch firefox@latest --detached
151

152
# Launch with output forwarding
153
npx @puppeteer/browsers launch chrome@stable --dumpio -- --remote-debugging-port=9222
154
```
155

156
### List Command
157

158
Lists all installed browsers in the cache directory with detailed information.
159

160
**Command Syntax:**
161
```bash
162
npx @puppeteer/browsers list [options]
163
```
164

165
**Options:**
166
- `--path <path>` - Cache directory path
167

168
**Usage Examples:**
169

170
```bash
171
# List all installed browsers
172
npx @puppeteer/browsers list
173

174
# List browsers in custom cache directory
175
npx @puppeteer/browsers list --path ./my-cache
176
```
177

178
**Example Output:**
179
```
180
chrome@118.0.5993.70 linux /path/to/cache/chrome/linux-118.0.5993.70/chrome-linux64/chrome
181
firefox@119.0 linux /path/to/cache/firefox/linux-119.0/firefox/firefox
182
chromedriver@118.0.5993.70 linux /path/to/cache/chromedriver/linux-118.0.5993.70/chromedriver
183
```
184

185
### Clear Command
186

187
Removes all installed browsers from the cache directory with interactive confirmation.
188

189
**Command Syntax:**
190
```bash
191
npx @puppeteer/browsers clear [options]
192
```
193

194
**Options:**
195
- `--path <path>` - Cache directory path
196

197
**Usage Examples:**
198

199
```bash
200
# Clear all browsers (with confirmation prompt)
201
npx @puppeteer/browsers clear
202

203
# Clear custom cache directory
204
npx @puppeteer/browsers clear --path ./my-cache
205
```
206

207
## Browser Version Specifications
208

209
The CLI supports flexible browser version specifications:
210

211
### Version Formats
212

213
- **Release Channels**: `chrome@stable`, `firefox@nightly`, `chromedriver@beta`
214
- **Specific Versions**: `chrome@118.0.5993.70`, `firefox@119.0`
215
- **Milestone Versions**: `chrome@118` (latest in milestone)
216
- **Latest**: `chrome@latest`, `firefox@latest`
217

218
### Supported Browsers and Channels
219

220
**Chrome:**
221
- `stable` - Latest stable release
222
- `beta` - Latest beta release  
223
- `dev` - Latest dev channel release
224
- `canary` - Latest canary release
225
- Specific versions: `118.0.5993.70`
226
- Milestones: `118`, `119`
227

228
**Firefox:**
229
- `stable` - Latest stable release
230
- `nightly` - Latest nightly build
231
- `devedition` - Developer edition
232
- `beta` - Beta channel
233
- `esr` - Extended Support Release
234
- Specific versions: `119.0`, `118.0.1`
235

236
**ChromeDriver:**
237
- Follows Chrome versioning
238
- `stable`, `beta`, `dev`, `canary`
239
- Specific versions matching Chrome
240

241
**Chromium:**
242
- Snapshot builds from tip-of-tree
243
- Specific revision numbers: `1097615`
244

245
**Chrome Headless Shell:**
246
- Follows Chrome versioning
247
- Same channels as Chrome
248

249
## CLI Help System
250

251
The CLI provides comprehensive help for all commands:
252

253
```bash
254
# General help
255
npx @puppeteer/browsers --help
256

257
# Command-specific help
258
npx @puppeteer/browsers install --help
259
npx @puppeteer/browsers launch --help
260
npx @puppeteer/browsers list --help
261
npx @puppeteer/browsers clear --help
262
```
263

264
## Configuration and Customization
265

266
### Cache Directory Configuration
267

268
Default cache directory follows platform conventions:
269

270
- **Linux/macOS**: `~/.cache/puppeteer/browsers`
271
- **Windows**: `%LOCALAPPDATA%/puppeteer/browsers`
272

273
Override with `--path` option or `PUPPETEER_CACHE_DIR` environment variable.
274

275
### Environment Variables
276

277
- `PUPPETEER_CACHE_DIR` - Default cache directory
278
- `HTTP_PROXY` / `HTTPS_PROXY` - Proxy configuration for downloads
279
- `NO_PROXY` - Proxy bypass configuration
280

281
### Version Specification
282

283
Use `npx` with specific versions:
284

285
```bash
286
# Always use latest from registry
287
npx @puppeteer/browsers@latest install chrome@stable
288

289
# Use specific package version
290
npx @puppeteer/browsers@2.10.8 install chrome@stable
291

292
# Auto-confirm installation
293
npx --yes @puppeteer/browsers@latest install chrome@stable
294
```
295

296
## Programmatic CLI Usage
297

298
Embed the CLI in Node.js applications:
299

300
```typescript
301
import { CLI } from "@puppeteer/browsers";
302

303
async function manageBrowsers() {
304
  const cli = new CLI({
305
    cachePath: "./app-browsers",
306
    scriptName: "app-browser-manager"
307
  });
308
  
309
  // Install Chrome programmatically
310
  await cli.run(["node", "app.js", "install", "chrome@stable"]);
311
  
312
  // List installed browsers
313
  await cli.run(["node", "app.js", "list"]);
314
  
315
  // Launch browser with custom args
316
  await cli.run([
317
    "node", "app.js", 
318
    "launch", "chrome@stable", 
319
    "--", "--headless", "--no-sandbox"
320
  ]);
321
}
322

323
manageBrowsers().catch(console.error);
324
```
325

326
## Error Handling and Debugging
327

328
The CLI provides detailed error messages and debugging information:
329

330
### Common Error Scenarios
331

332
**Installation Errors:**
333
- Network connectivity issues
334
- Disk space problems
335
- Permission errors
336
- Invalid version specifications
337

338
**Launch Errors:**
339
- Browser not installed
340
- Invalid executable paths
341
- System compatibility issues
342
- Process startup failures
343

344
**Cache Errors:**
345
- Directory access problems
346
- Corrupted cache metadata
347
- Insufficient permissions
348

349
### Debug Output
350

351
Enable debug output with environment variables:
352

353
```bash
354
# Debug browser installation
355
DEBUG=puppeteer:browsers:install npx @puppeteer/browsers install chrome@stable
356

357
# Debug browser launching
358
DEBUG=puppeteer:browsers:launcher npx @puppeteer/browsers launch chrome@stable
359

360
# Debug cache operations
361
DEBUG=puppeteer:browsers:cache npx @puppeteer/browsers list
362
```
363

364
## Integration Examples
365

366
### CI/CD Pipeline
367

368
```bash
369
#!/bin/bash
370
# Install specific browser versions for testing
371
npx @puppeteer/browsers install chrome@118.0.5993.70
372
npx @puppeteer/browsers install firefox@119.0
373

374
# Run tests with installed browsers
375
npm test
376
```
377

378
### Docker Container
379

380
```dockerfile
381
FROM node:18
382
RUN npx @puppeteer/browsers install chrome@stable --install-deps
383
COPY . .
384
CMD ["npm", "start"]
385
```
386

387
### Development Workflow
388

389
```bash
390
# Setup development environment
391
npx @puppeteer/browsers install chrome@stable
392
npx @puppeteer/browsers install chrome@canary
393
npx @puppeteer/browsers install firefox@nightly
394

395
# Launch for debugging
396
npx @puppeteer/browsers launch chrome@stable -- --remote-debugging-port=9222
397
```