0
# Command Line Interface
1

2
Command line tool for package operations without requiring programmatic usage. The pacote CLI provides direct access to all core functionality through simple commands.
3

4
## Capabilities
5

6
### Installation and Usage
7

8
The CLI is included with the pacote package:
9

10
```bash
11
npm install -g pacote
12
pacote --help
13
```
14

15
Or use without installation:
16

17
```bash
18
npx pacote <command> <args>
19
```
20

21
### Resolve Command
22

23
Resolve a package specifier to a concrete location (tarball URL, file path, or git repository).
24

25
```bash { .api }
26
# Basic resolution
27
pacote resolve <spec>
28

29
# Extended resolution with metadata
30
pacote resolve <spec> --long
31
```
32

33
**Usage Examples:**
34

35
```bash
36
# Resolve registry package
37
pacote resolve express@latest
38
# Output: https://registry.npmjs.org/express/-/express-4.18.2.tgz
39

40
# Resolve with extended information
41
pacote resolve lodash@4.17.21 --long
42
# Output: {
43
#   "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
44
#   "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==",
45
#   "from": "lodash@4.17.21"
46
# }
47

48
# Resolve git repository
49
pacote resolve github:facebook/react#v18.0.0
50
# Output: git+ssh://git@github.com/facebook/react.git#v18.0.0
51

52
# Resolve local file
53
pacote resolve file:./package.tgz
54
# Output: file:///absolute/path/to/package.tgz
55
```
56

57
### Manifest Command
58

59
Fetch and display a package's manifest (package.json plus metadata).
60

61
```bash { .api }
62
# Fetch package manifest
63
pacote manifest <spec>
64
```
65

66
**Usage Examples:**
67

68
```bash
69
# Get manifest for latest version
70
pacote manifest express@latest
71

72
# Get manifest for specific version
73
pacote manifest lodash@4.17.21
74

75
# Get git repository manifest
76
pacote manifest github:npm/cli#latest
77

78
# Output format (JSON):
79
# {
80
#   "name": "express",
81
#   "version": "4.18.2",
82
#   "description": "Fast, unopinionated, minimalist web framework",
83
#   "main": "index.js",
84
#   "dependencies": { ... },
85
#   "_resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
86
#   "_integrity": "sha512-...",
87
#   "_from": "express@latest"
88
# }
89
```
90

91
### Packument Command
92

93
Fetch and display a package's packument (full package document with all versions).
94

95
```bash { .api }
96
# Fetch package packument
97
pacote packument <spec>
98
```
99

100
**Usage Examples:**
101

102
```bash
103
# Get full packument
104
pacote packument express
105

106
# Get packument for scoped package
107
pacote packument @angular/core
108

109
# Output includes all versions, dist-tags, and metadata:
110
# {
111
#   "name": "express",
112
#   "versions": {
113
#     "4.18.0": { ... },
114
#     "4.18.1": { ... },
115
#     "4.18.2": { ... }
116
#   },
117
#   "dist-tags": {
118
#     "latest": "4.18.2",
119
#     "beta": "5.0.0-beta.1"
120
#   },
121
#   "time": {
122
#     "4.18.0": "2022-04-25T...",
123
#     "4.18.1": "2022-04-29T..."
124
#   }
125
# }
126
```
127

128
### Tarball Command
129

130
Download a package tarball and save it to a file or stream to stdout.
131

132
```bash { .api }
133
# Save tarball to file
134
pacote tarball <spec> <filename>
135

136
# Stream tarball to stdout  
137
pacote tarball <spec>
138
pacote tarball <spec> -
139
```
140

141
**Usage Examples:**
142

143
```bash
144
# Download tarball to file
145
pacote tarball express@4.18.2 express-4.18.2.tgz
146

147
# Stream to stdout (for piping)
148
pacote tarball lodash@latest | gzip -d | tar -t
149

150
# Download git repository as tarball
151
pacote tarball github:facebook/react#v18.0.0 react-18.0.0.tgz
152

153
# Download to stdout and save
154
pacote tarball express@latest > express-latest.tgz
155
```
156

157
### Extract Command
158

159
Extract a package to a destination folder.
160

161
```bash { .api }
162
# Extract package to folder
163
pacote extract <spec> <folder>
164
```
165

166
**Usage Examples:**
167

168
```bash
169
# Extract registry package
170
pacote extract express@4.18.2 ./node_modules/express
171

172
# Extract git repository  
173
pacote extract github:npm/cli#latest ./packages/npm-cli
174

175
# Extract to current directory
176
pacote extract lodash@latest ./lodash
177

178
# Extract local tarball
179
pacote extract file:./package.tgz ./extracted
180
```
181

182
### Configuration Flags
183

184
All npm configuration options are supported as command line flags:
185

186
```bash { .api }
187
# Cache directory
188
pacote manifest express --cache=/custom/cache
189

190
# Registry URL
191
pacote resolve lodash --registry=https://custom-registry.com
192

193
# Offline mode
194
pacote manifest react --offline
195

196
# Prefer online
197
pacote packument vue --prefer-online
198

199
# Full metadata
200
pacote packument @angular/core --full-metadata
201

202
# Before date filter
203
pacote packument express --before=2022-01-01
204

205
# Integrity verification
206
pacote extract express@4.18.2 ./express --integrity=sha512-...
207
```
208

209
### Output Control Flags
210

211
Control output format and verbosity:
212

213
```bash { .api }
214
# JSON output (default for non-TTY)
215
pacote manifest express --json
216

217
# Extended resolve information
218
pacote resolve express --long
219

220
# Help information
221
pacote --help
222
pacote -h
223
```
224

225
### Global Options
226

227
Options that work with any command:
228

229
```bash
230
# Custom cache directory
231
--cache=/path/to/cache
232

233
# Registry URL
234
--registry=https://registry.npmjs.org
235

236
# Network preferences
237
--offline
238
--prefer-offline  
239
--prefer-online
240

241
# Metadata options
242
--full-metadata
243
--full-read-json
244

245
# Security options
246
--verify-signatures
247
--verify-attestations
248

249
# File permissions (extract only)
250
--umask=0022
251
--fmode=0666
252
--dmode=0777
253
```
254

255
## CLI Module Usage
256

257
The CLI can also be used programmatically by requiring the CLI module:
258

259
```javascript { .api }
260
/**
261
 * CLI module exports for programmatic usage
262
 */
263
const cli = require('pacote/bin/index.js');
264

265
/**
266
 * Main CLI entry point
267
 * @param {string[]} args - Command line arguments
268
 * @returns {Promise<void>} CLI execution promise
269
 */
270
function main(args);
271

272
/**
273
 * Execute CLI command with parsed configuration
274
 * @param {Object} conf - Parsed configuration object
275
 * @returns {Promise<void>} Command execution promise
276
 */
277
function run(conf);
278

279
/**
280
 * Get CLI usage help text
281
 * @returns {string} Usage help text
282
 */
283
function usage();
284

285
/**
286
 * Parse single command line argument
287
 * @param {string} arg - Command line argument
288
 * @returns {Object} Parsed argument object
289
 */
290
function parseArg(arg);
291

292
/**
293
 * Parse arguments array to configuration object
294
 * @param {string[]} args - Command line arguments
295
 * @returns {Object} Configuration object
296
 */
297
function parse(args);
298

299
interface CLIConfiguration {
300
  /** CLI command to execute */
301
  command: 'resolve' | 'manifest' | 'packument' | 'tarball' | 'extract';
302
  /** Package specifier argument */
303
  spec: string;
304
  /** Additional positional arguments */
305
  args: string[];
306
  /** Parsed configuration options */
307
  opts: Object;
308
  /** Whether to show extended output (--long flag) */
309
  long?: boolean;
310
  /** Whether to format output as JSON */
311
  json?: boolean;
312
  /** Exit code (0 for success) */
313
  exitCode?: number;
314
}
315
```
316

317
**Programmatic Usage Examples:**
318

319
```javascript
320
const cli = require('pacote/bin/index.js');
321

322
// Run CLI programmatically
323
await cli.main(['resolve', 'express@latest']);
324

325
// Parse and run with custom config
326
const config = cli.parse(['manifest', 'lodash@4.17.21', '--json']);
327
await cli.run(config);
328

329
// Get help text
330
const helpText = cli.usage();
331
console.log(helpText);
332
```
333

334
## Exit Codes
335

336
The CLI uses standard exit codes:
337

338
- `0`: Success
339
- `1`: General error (package not found, network error, etc.)
340
- `2`: Invalid arguments or usage
341
- `130`: Interrupted by user (Ctrl+C)
342

343
## Examples by Package Type
344

345
### Registry Packages
346

347
```bash
348
# Standard registry package
349
pacote resolve express@4.18.2
350
pacote manifest @angular/core@15.0.0
351
pacote extract lodash@latest ./lodash
352

353
# Scoped packages
354
pacote packument @types/node
355
pacote tarball @vue/cli@latest vue-cli.tgz
356
```
357

358
### Git Repositories
359

360
```bash
361
# GitHub shorthand
362
pacote resolve github:facebook/react#v18.0.0
363
pacote extract github:npm/cli#latest ./npm-cli
364

365
# Full git URLs
366
pacote manifest git+https://github.com/lodash/lodash.git#4.17.21
367
pacote tarball git+ssh://git@github.com/user/repo.git#main repo.tgz
368
```
369

370
### Local Files and Directories
371

372
```bash
373
# Local tarballs
374
pacote manifest file:./dist/package.tgz
375
pacote extract file:../packages/my-pkg.tgz ./my-pkg
376

377
# Local directories
378
pacote resolve file:./src
379
pacote tarball file:./my-package my-package.tgz
380
```
381

382
### Remote URLs
383

384
```bash
385
# Remote tarballs
386
pacote manifest https://cdn.example.com/package.tgz
387
pacote extract https://files.example.com/pkg.tgz ./pkg
388
```