tessl/npm-release-it

Generic CLI tool to automate versioning and package publishing-related tasks.

—

Pending

Overview

Eval results

Files

CLI Interface

Name: tessl/npm-release-it
Author: tessl

Release It!'s command-line interface provides a comprehensive set of options for automating release workflows. The CLI supports both interactive and non-interactive modes, with extensive configuration options.

Capabilities

Main CLI Function

Primary command-line interface entry point.

/**
 * Main CLI entry point that processes options and delegates to appropriate handler
 * @param options - Parsed CLI options object
 * @returns Promise that resolves when CLI operation completes
 */
function cli(options: CLIOptions): Promise<any>;

interface CLIOptions {
  /** Show version information */
  version?: boolean;
  /** Show help information */
  help?: boolean;
  /** Version increment or explicit version */
  increment?: string;
  /** Dry run mode - show operations without executing */
  "dry-run"?: boolean;
  /** Verbose output (can be boolean or number for level) */
  verbose?: boolean | number;
  /** CI mode - non-interactive operation */
  ci?: boolean;
  /** Prompt only for version selection */
  "only-version"?: boolean;
  /** Print release version and exit */
  "release-version"?: boolean;
  /** Print changelog and exit */
  changelog?: boolean;
  /** Configuration file path */
  config?: string;
  /** Configuration directory */
  "config-dir"?: string;
  /** Configuration to extend */
  extends?: string;
  [key: string]: any;
}

Argument Parsing

Command-line argument parsing and validation.

/**
 * Parse command-line arguments into structured options object
 * @param args - Array of command-line arguments (typically process.argv.slice(2))
 * @returns Parsed options object with normalized keys
 */
function parseCliArguments(args: string[]): CLIOptions;

Information Commands

Commands for displaying version and help information.

/**
 * Print Release It! version information
 * Outputs version number to console and exits
 */
function version(): void;

/**
 * Print comprehensive help text with usage examples
 * Outputs help information to console and exits
 */
function help(): void;

CLI Command Examples

Release It! provides a flexible command-line interface with numerous options:

Basic Usage:

# Interactive release with prompts
release-it

# Release with specific increment
release-it patch
release-it minor
release-it major
release-it prerelease

# Explicit version specification
release-it 2.1.0
release-it 1.0.0-beta.1

Mode Options:

# Dry run - show what would happen without executing
release-it --dry-run
release-it -d

# CI mode - non-interactive, fail on prompts
release-it --ci

# Only prompt for version, skip other interactions
release-it --only-version

# Print version that would be released and exit
release-it --release-version

# Print changelog for upcoming release and exit
release-it --changelog

Configuration Options:

# Use specific configuration file
release-it --config .release-it.production.json
release-it -c custom-config.js

# Disable configuration file loading
release-it --no-config

# Specify configuration directory
release-it --config-dir ./configs

# Extend specific configuration
release-it --extends @company/release-config

Verbosity Options:

# Enable verbose output
release-it --verbose
release-it -V

# Extra verbose output (shows internal commands)
release-it -VV

# Numeric verbosity levels
release-it --verbose=1
release-it --verbose=2

Plugin Options:

# Disable specific plugins
release-it --no-git
release-it --no-npm
release-it --no-github

# Plugin-specific configuration via CLI
release-it --git.requireCleanWorkingDir=false
release-it --npm.publish=false
release-it --github.release=true

Combined Examples:

# CI release with specific version and dry-run
release-it 1.2.0 --ci --dry-run --verbose

# Pre-release with custom config and GitHub disabled
release-it prerelease --config .release-it.beta.json --no-github

# Interactive release with verbose output and custom commit message
release-it --verbose --git.commitMessage="chore: release v\${version}"

Exit Codes

Release It! uses standard exit codes to indicate operation results:

interface ExitCodes {
  /** Successful completion */
  SUCCESS: 0;
  /** General error or operation failed */
  ERROR: 1;
  /** User interrupted operation (Ctrl+C) */
  INTERRUPTED: 130;
}

Exit Code Usage:

0 - Release completed successfully
1 - Error occurred during release (validation failed, command failed, etc.)
130 - User interrupted the process (Ctrl+C)

Help Text

The CLI provides comprehensive help documentation:

Release It! v19.0.4

Usage: release-it <increment> [options]

Use e.g. "release-it minor" directly as shorthand for "release-it --increment=minor".

-c --config            Path to local configuration options [default: ".release-it.json"]
-d --dry-run           Do not touch or write anything, but show the commands
-h --help              Print this help
-i --increment         Increment "major", "minor", "patch", or "pre*" version; or specify version [default: "patch"]
   --ci                No prompts, no user interaction; activated automatically in CI environments
   --only-version      Prompt only for version, no further interaction
-v --version           Print release-it version number
   --release-version   Print version number to be released
   --changelog         Print changelog for the version to be released
-V --verbose           Verbose output (user hooks output)
-VV                    Extra verbose output (also internal commands output)

For more details, please see https://github.com/release-it/release-it

Environment Detection

The CLI automatically detects and adapts to different environments:

interface EnvironmentDetection {
  /** Detect CI environment and enable CI mode */
  detectCI(): boolean;
  
  /** Detect TTY availability for interactive features */
  detectTTY(): boolean;
  
  /** Detect debug mode from NODE_DEBUG environment variable */
  detectDebug(): boolean;
}

Supported CI Environments:

GitHub Actions
GitLab CI
Travis CI
CircleCI
Jenkins
Azure DevOps
Bitbucket Pipelines
AWS CodeBuild
And many others via ci-info package

Configuration Precedence

CLI options follow a specific precedence order (highest to lowest):

CLI Arguments: Direct command-line flags and options
Environment Variables: CI=true, NODE_DEBUG=release-it, etc.
Configuration Files: .release-it.json, .release-it.js, etc.
package.json: release-it property
Default Configuration: Built-in defaults

Error Handling and Validation

The CLI includes comprehensive validation and error handling:

Argument Validation: Invalid options and combinations are caught early
Configuration Validation: Configuration files are validated on load
Environment Validation: Git repository, npm authentication, etc.
Graceful Degradation: Fallback behavior for unsupported environments

Interactive Features

In interactive mode, the CLI provides:

Version Selection: Choose from increment options or specify custom version
Operation Confirmation: Confirm each major operation (commit, tag, push, publish)
Error Recovery: Options to retry or skip failed operations
Progress Indication: Spinners and progress bars for long-running operations

Integration Examples

Package.json Script:

{
  "scripts": {
    "release": "release-it",
    "release:patch": "release-it patch",
    "release:minor": "release-it minor",
    "release:major": "release-it major",
    "release:beta": "release-it prerelease --preReleaseId=beta",
    "release:dry": "release-it --dry-run"
  }
}

GitHub Actions:

- name: Release
  run: npx release-it --ci
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Pre-commit Hook:

#!/bin/sh
# Validate release configuration
npx release-it --dry-run --ci > /dev/null

Install with Tessl CLI

npx tessl i tessl/npm-release-it

docs

cli-interface.md

configuration.md

core-orchestration.md

git-operations.md

github-integration.md

gitlab-integration.md