Packaging

Package oclif CLIs into distributable formats including tarballs, installers, and platform-specific packages for cross-platform distribution.

Capabilities

Package Tarballs

Creates compressed tarballs containing the CLI and its dependencies for multiple target platforms.

oclif pack tarballs

Flags:

• --parallel (boolean) - Build targets in parallel for faster packaging
• --prune-lockfiles (boolean) - Remove lockfiles from packaged output
• --root, -r (string) - Root directory of the CLI project (default: ".")
• --sha (string) - Git SHA to include in package metadata
• --tarball, -l (string) - Path to existing NPM tarball
• --targets, -t (string) - Comma-separated list of target platforms
• --xz (boolean) - Use xz compression instead of gzip

Usage Examples:

# Package for all default targets
oclif pack tarballs

# Package specific targets
oclif pack tarballs --targets=linux-x64,darwin-x64,win32-x64

# Package with parallel builds and xz compression
oclif pack tarballs --parallel --xz

# Package with custom SHA
oclif pack tarballs --sha=abc123def456

Supported Targets:

type Target = 
  | 'linux-x64' | 'linux-arm' | 'linux-arm64'
  | 'darwin-x64' | 'darwin-arm64' 
  | 'win32-x64' | 'win32-x86' | 'win32-arm64';

Package Debian

Creates .deb packages for Debian and Ubuntu distributions.

oclif pack deb

Flags:

• --root, -r (string) - Root directory of the CLI project (default: ".")
• --compression, -z (gzip|none|xz|zstd) - Override default compression
• --prune-lockfiles (boolean) - Remove lockfiles from packaged output
• --sha (string) - Git SHA to include in package metadata
• --tarball, -t (string) - Path to existing tarball

Usage Examples:

# Create Debian package
oclif pack deb

# Create with custom compression
oclif pack deb --compression=xz

# Package will be created in ./dist/deb/

Debian Package Structure:

• Creates .deb files in ./dist/deb/ directory
• Includes proper Debian control files and metadata
• Sets up appropriate file permissions and directories
• Configures post-install scripts for CLI registration

Package macOS

Creates macOS installer packages (.pkg files) for distribution through the Mac App Store or direct download.

oclif pack macos

Flags:

• --root, -r (string) - Root directory of the CLI project (default: ".")
• --additional-cli (string) - Additional CLI to make available
• --prune-lockfiles (boolean) - Remove lockfiles from packaged output
• --sha (string) - Git SHA to include in package metadata
• --tarball, -t (string) - Path to existing tarball
• --targets (string) - Comma-separated targets to pack

Usage Examples:

# Create macOS installer
oclif pack macos

# Create for specific targets
oclif pack macos --targets=darwin-x64,darwin-arm64

# Installer will be created in ./dist/macos/

macOS Package Features:

• Creates signed .pkg installer files
• Supports macOS code signing and notarization
• Handles both Intel and Apple Silicon architectures
• Configures proper installation paths and permissions

Package Windows

Creates Windows installer packages including MSI and executable installers.

oclif pack win

Flags:

• --root, -r (string) - Root directory of the CLI project (default: ".")
• --additional-cli (string) - Additional CLI to make available
• --defender-exclusion (checked|unchecked|hidden) - Windows Defender exclusion setting
• --prune-lockfiles (boolean) - Remove lockfiles from packaged output
• --sha (string) - Git SHA to include in package metadata
• --tarball, -t (string) - Path to existing tarball
• --targets (string) - Comma-separated targets to pack

Usage Examples:

# Create Windows installer
oclif pack win

# Create with Windows Defender exclusion
oclif pack win --defender-exclusion=checked

# Installers will be created in ./dist/win32/

Windows Package Features:

• Creates .exe and .msi installer files
• Supports Windows code signing
• Handles both x64 and x86 architectures
• Configures Windows registry entries and PATH updates

Build Configuration

Packaging behavior is controlled through the oclif configuration and build settings.

Build Config Interface

interface BuildConfig {
  /** Root directory of the project */
  root: string;
  /** Target platforms to build for */
  targets: Target[];
  /** Git SHA for versioning */
  sha?: string;
  /** S3 configuration for uploads */
  s3Config?: S3Config;
  /** Update mechanism configuration */
  updateConfig?: UpdateConfig;
  /** Node.js version to bundle */
  nodeVersion?: string;
  /** Whether to use xz compression */
  xz?: boolean;
}

interface S3Config {
  bucket: string;
  folder?: string;
  host?: string;
  acl?: string;
  xz?: boolean;
}

interface UpdateConfig {
  autoupdate?: {
    /** Percentage rollout for updates */
    rollout?: number;
    /** Debounce time in minutes */
    debounce?: number;
  };
  /** Node.js configuration */
  node?: {
    version: string;
  };
  /** S3 update configuration */
  s3?: S3Config;
}

Package.json Configuration

Configure packaging behavior in package.json:

{
  "oclif": {
    "update": {
      "s3": {
        "bucket": "my-cli-releases",
        "folder": "releases",
        "host": "https://releases.mycli.com",
        "xz": true
      },
      "node": {
        "version": "18.17.1"
      }
    },
    "macos": {
      "identifier": "com.company.mycli"
    },
    "topics": {
      "pack": {
        "description": "Package CLI for distribution"
      }
    }
  },
  "files": [
    "oclif.manifest.json",
    "./bin",
    "./lib"
  ]
}

Build Targets and Platforms

oclif supports building for multiple target platforms with specific Node.js versions and architectures.

Available Targets

const TARGETS: Target[] = [
  'linux-x64',    // Linux x86_64
  'linux-arm',    // Linux ARM 32-bit
  'linux-arm64',  // Linux ARM 64-bit
  'darwin-x64',   // macOS Intel
  'darwin-arm64', // macOS Apple Silicon
  'win32-x64',    // Windows x86_64
  'win32-x86',    // Windows x86 32-bit
  'win32-arm64'   // Windows ARM 64-bit
];

Build Process

The packaging process involves several steps:

1. Dependency Resolution: Installs production dependencies
2. Code Compilation: Compiles TypeScript to JavaScript if needed
3. Node.js Bundling: Includes Node.js runtime for standalone execution
4. Binary Creation: Creates platform-specific executables
5. Compression: Applies gzip or xz compression
6. Metadata Generation: Includes version info and checksums

Output Structure

Packaged files are organized in the ./dist/ directory:

dist/
├── channels/          # Update channel metadata
├── tarballs/         # Compressed tarballs
│   ├── mycli-v1.0.0-linux-x64.tar.gz
│   ├── mycli-v1.0.0-darwin-x64.tar.gz
│   └── mycli-v1.0.0-win32-x64.tar.gz
├── deb/              # Debian packages
│   └── mycli_1.0.0_amd64.deb
├── macos/            # macOS installers
│   └── mycli-v1.0.0.pkg
└── win32/            # Windows installers
    ├── mycli-v1.0.0-x64.exe
    └── mycli-v1.0.0-x64.msi

Utility Functions

Helper functions for build configuration and packaging operations.

/**
 * Create build configuration from project settings
 * @param root - Project root directory
 * @param options - Build options
 * @returns Complete build configuration
 */
function buildConfig(root: string, options?: BuildOptions): BuildConfig;

/**
 * Get current git SHA for versioning
 * @param cwd - Working directory
 * @param options - Git options
 * @returns Git SHA string
 */
function gitSha(cwd: string, options?: { short?: boolean }): string;

interface BuildOptions {
  targets?: Target[];
  sha?: string;
  xz?: boolean;
  parallel?: boolean;
}