CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pacote

JavaScript package downloader and fetcher that serves as the core package handling library for npm

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

cli.mddocs/

Command Line Interface

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

Capabilities

Installation and Usage

The CLI is included with the pacote package:

npm install -g pacote
pacote --help

Or use without installation:

npx pacote <command> <args>

Resolve Command

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

# Basic resolution
pacote resolve <spec>

# Extended resolution with metadata
pacote resolve <spec> --long

Usage Examples:

# Resolve registry package
pacote resolve express@latest
# Output: https://registry.npmjs.org/express/-/express-4.18.2.tgz

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

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

# Resolve local file
pacote resolve file:./package.tgz
# Output: file:///absolute/path/to/package.tgz

Manifest Command

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

# Fetch package manifest
pacote manifest <spec>

Usage Examples:

# Get manifest for latest version
pacote manifest express@latest

# Get manifest for specific version
pacote manifest lodash@4.17.21

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

# Output format (JSON):
# {
#   "name": "express",
#   "version": "4.18.2",
#   "description": "Fast, unopinionated, minimalist web framework",
#   "main": "index.js",
#   "dependencies": { ... },
#   "_resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
#   "_integrity": "sha512-...",
#   "_from": "express@latest"
# }

Packument Command

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

# Fetch package packument
pacote packument <spec>

Usage Examples:

# Get full packument
pacote packument express

# Get packument for scoped package
pacote packument @angular/core

# Output includes all versions, dist-tags, and metadata:
# {
#   "name": "express",
#   "versions": {
#     "4.18.0": { ... },
#     "4.18.1": { ... },
#     "4.18.2": { ... }
#   },
#   "dist-tags": {
#     "latest": "4.18.2",
#     "beta": "5.0.0-beta.1"
#   },
#   "time": {
#     "4.18.0": "2022-04-25T...",
#     "4.18.1": "2022-04-29T..."
#   }
# }

Tarball Command

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

# Save tarball to file
pacote tarball <spec> <filename>

# Stream tarball to stdout  
pacote tarball <spec>
pacote tarball <spec> -

Usage Examples:

# Download tarball to file
pacote tarball express@4.18.2 express-4.18.2.tgz

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

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

# Download to stdout and save
pacote tarball express@latest > express-latest.tgz

Extract Command

Extract a package to a destination folder.

# Extract package to folder
pacote extract <spec> <folder>

Usage Examples:

# Extract registry package
pacote extract express@4.18.2 ./node_modules/express

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

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

# Extract local tarball
pacote extract file:./package.tgz ./extracted

Configuration Flags

All npm configuration options are supported as command line flags:

# Cache directory
pacote manifest express --cache=/custom/cache

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

# Offline mode
pacote manifest react --offline

# Prefer online
pacote packument vue --prefer-online

# Full metadata
pacote packument @angular/core --full-metadata

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

# Integrity verification
pacote extract express@4.18.2 ./express --integrity=sha512-...

Output Control Flags

Control output format and verbosity:

# JSON output (default for non-TTY)
pacote manifest express --json

# Extended resolve information
pacote resolve express --long

# Help information
pacote --help
pacote -h

Global Options

Options that work with any command:

# Custom cache directory
--cache=/path/to/cache

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

# Network preferences
--offline
--prefer-offline  
--prefer-online

# Metadata options
--full-metadata
--full-read-json

# Security options
--verify-signatures
--verify-attestations

# File permissions (extract only)
--umask=0022
--fmode=0666
--dmode=0777

CLI Module Usage

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

/**
 * CLI module exports for programmatic usage
 */
const cli = require('pacote/bin/index.js');

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

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

/**
 * Get CLI usage help text
 * @returns {string} Usage help text
 */
function usage();

/**
 * Parse single command line argument
 * @param {string} arg - Command line argument
 * @returns {Object} Parsed argument object
 */
function parseArg(arg);

/**
 * Parse arguments array to configuration object
 * @param {string[]} args - Command line arguments
 * @returns {Object} Configuration object
 */
function parse(args);

interface CLIConfiguration {
  /** CLI command to execute */
  command: 'resolve' | 'manifest' | 'packument' | 'tarball' | 'extract';
  /** Package specifier argument */
  spec: string;
  /** Additional positional arguments */
  args: string[];
  /** Parsed configuration options */
  opts: Object;
  /** Whether to show extended output (--long flag) */
  long?: boolean;
  /** Whether to format output as JSON */
  json?: boolean;
  /** Exit code (0 for success) */
  exitCode?: number;
}

Programmatic Usage Examples:

const cli = require('pacote/bin/index.js');

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

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

// Get help text
const helpText = cli.usage();
console.log(helpText);

Exit Codes

The CLI uses standard exit codes:

  • 0: Success
  • 1: General error (package not found, network error, etc.)
  • 2: Invalid arguments or usage
  • 130: Interrupted by user (Ctrl+C)

Examples by Package Type

Registry Packages

# Standard registry package
pacote resolve express@4.18.2
pacote manifest @angular/core@15.0.0
pacote extract lodash@latest ./lodash

# Scoped packages
pacote packument @types/node
pacote tarball @vue/cli@latest vue-cli.tgz

Git Repositories

# GitHub shorthand
pacote resolve github:facebook/react#v18.0.0
pacote extract github:npm/cli#latest ./npm-cli

# Full git URLs
pacote manifest git+https://github.com/lodash/lodash.git#4.17.21
pacote tarball git+ssh://git@github.com/user/repo.git#main repo.tgz

Local Files and Directories

# Local tarballs
pacote manifest file:./dist/package.tgz
pacote extract file:../packages/my-pkg.tgz ./my-pkg

# Local directories
pacote resolve file:./src
pacote tarball file:./my-package my-package.tgz

Remote URLs

# Remote tarballs
pacote manifest https://cdn.example.com/package.tgz
pacote extract https://files.example.com/pkg.tgz ./pkg

Install with Tessl CLI

npx tessl i tessl/npm-pacote

docs

cli.md

configuration.md

core-api.md

fetchers.md

index.md

utility-functions.md

tile.json