or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli-interface.md configuration.md index.md release-types.md version-bumping.md

tile.json

CLI Interface

Command-line interface with argument parsing, interactive prompts, and comprehensive error handling for terminal-based version bumping workflows.

Note: CLI functions are internal implementation details and not part of the public programmatic API. Use the bumpp command directly or the main API functions (versionBump, versionBumpInfo) for programmatic access.

Capabilities

CLI Executable

The bumpp command-line interface provides terminal-based version bumping workflows.

Usage:

The CLI is accessed via the bumpp executable installed with the package:

# Via npx
npx bumpp

# Via global install
npm install -g bumpp
bumpp

# With arguments
bumpp patch --no-push --commit="fix: update version"

Exit Codes

The CLI uses standard exit codes to indicate operation results:

0 - Success: Operation completed successfully
1 - Fatal Error: Version bump failed due to error
9 - Invalid Argument: Invalid command-line arguments provided

CLI Usage Patterns

Interactive Mode

Default behavior prompts user for version selection.

# Interactive prompt
$ npx bumpp

? Select release type: (Use arrow keys)
❯ patch (1.2.3 → 1.2.4)
  minor (1.2.3 → 1.3.0)  
  major (1.2.3 → 2.0.0)
  prepatch (1.2.3 → 1.2.4-0)
  preminor (1.2.3 → 1.3.0-0)
  premajor (1.2.3 → 2.0.0-0)
  prerelease (1.2.3-0 → 1.2.3-1)
  custom

Direct Version Specification

Specify release type or version directly.

# Release type
npx bumpp patch
npx bumpp minor  
npx bumpp major

# Explicit version
npx bumpp 2.1.0
npx bumpp 1.0.0-beta.5

# Extended types
npx bumpp next
npx bumpp conventional

Configuration Arguments

Override configuration with command-line flags.

# Git operations
npx bumpp patch --no-commit     # Skip git commit
npx bumpp minor --no-tag        # Skip git tag
npx bumpp major --no-push       # Skip git push
npx bumpp patch --sign          # Sign commit and tag

# Custom messages
npx bumpp patch --commit="fix: resolve critical bug"
npx bumpp minor --tag="release-v%s"

# File specification
npx bumpp patch --files=package.json,version.ts,README.md

# Execution options
npx bumpp minor --execute="npm run build && npm test"
npx bumpp patch --recursive     # Monorepo mode
npx bumpp minor --install       # Run npm install

# Confirmation and output
npx bumpp patch --no-confirm    # Skip confirmation prompt
npx bumpp minor --quiet         # Suppress progress output

CLI Configuration

Argument Structure

Available command-line arguments and their mappings to VersionBumpOptions.

Version Arguments:

[release] - Positional argument for release type or version
--preid <id> - Prerelease identifier
--current-version <version> - Override current version detection

Git Arguments:

--commit [message] - Enable git commit with optional custom message
--no-commit - Disable git commit
--tag [format] - Enable git tag with optional format
--no-tag - Disable git tag
--push / --no-push - Enable/disable git push
--sign / --no-sign - Enable/disable git signing
--all - Include all files in git commit
--no-verify - Skip git hooks

File Arguments:

--files <list> - Comma-separated list of files to update
--recursive - Enable monorepo recursive mode
--cwd <path> - Set working directory

Execution Arguments:

--execute <command> - Execute command before commit
--install - Run package manager install
--ignore-scripts - Skip npm lifecycle scripts

Interface Arguments:

--confirm / --no-confirm - Enable/disable confirmation prompt
--quiet - Suppress progress output
--print-commits [count] - Show recent commit history

Utility Arguments:

--help - Show help information
--version - Show version information

Environment Variables

CLI behavior can be influenced by environment variables.

# Debug mode - show full stack traces
DEBUG=1 npx bumpp patch

# Development mode - enhanced error information  
NODE_ENV=development npx bumpp minor

# CI mode - disable interactive prompts
CI=true npx bumpp patch --no-confirm

Error Handling

CLI Error Management

The CLI provides comprehensive error handling with appropriate exit codes.

Error Categories:

Fatal Errors (Exit Code 1):
- Git operation failures
- File permission errors
- Network connectivity issues
- Invalid configuration
Invalid Arguments (Exit Code 9):
- Unknown command-line flags
- Invalid release type values
- Conflicting argument combinations
User Cancellation (Exit Code 1):
- User cancels confirmation prompt
- Interrupted interactive session

Error Output Examples

Git Working Tree Error:

$ npx bumpp patch
Git working tree is not clean:
 M src/modified-file.ts
 ?? untracked-file.js

Invalid Release Type:

$ npx bumpp invalid-type
Invalid release type: invalid-type
Valid types: major, minor, patch, premajor, preminor, prepatch, prerelease, next, conventional

Permission Error:

$ npx bumpp patch
Error: EACCES: permission denied, open 'package.json'

Progress Reporting

CLI Progress Display

The CLI automatically displays progress during version bump operations.

$ npx bumpp patch

✔ Updated package.json to 1.2.4
✔ Updated package-lock.json to 1.2.4  
✔ Npm run build
✔ Git commit
✔ Git tag
✔ Git push

Quiet Mode

Suppress progress output with --quiet flag.

# Minimal output
$ npx bumpp patch --quiet
1.2.4

Verbose Mode

Enhanced output shows detailed operation information.

$ npx bumpp patch --print-commits

Recent commits:
  feat: add new API endpoint (2 hours ago)
  fix: resolve memory leak (1 day ago) 
  docs: update README (2 days ago)

   files package.json
          package-lock.json
  commit chore: release v1.2.4
     tag v1.2.4
    push yes

    from 1.2.3
      to 1.2.4

? Bump? (Y/n)

CI/CD Integration

Non-Interactive Mode

Configure for automated environments.

# CI-friendly configuration
npx bumpp patch \
  --no-confirm \          # Skip confirmation
  --quiet \               # Minimal output
  --no-push \             # Let CI handle pushing
  --execute="npm run build && npm test"

Exit Code Handling

Handle CLI exit codes in scripts.

#!/bin/bash

# Run bumpp and capture exit code
npx bumpp patch --no-confirm
EXIT_CODE=$?

case $EXIT_CODE in
  0)
    echo "Version bump successful"
    ;;
  1) 
    echo "Version bump failed"
    exit 1
    ;;
  9)
    echo "Invalid arguments provided"
    exit 1
    ;;
esac

GitHub Actions Integration

Example GitHub Actions workflow:

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0
          
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          
      - run: npm ci
      
      - name: Version bump
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          npx bumpp conventional --no-confirm
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Programmatic Integration

Using the Main API

For programmatic version bumping, use the main API functions instead of CLI internals:

import { versionBump } from "bumpp";

// Custom wrapper using the public API
async function customBump() {
  try {
    // Add custom pre-bump logic
    console.log("Running custom pre-bump tasks...");
    await runCustomTasks();
    
    // Execute version bump with configuration
    const result = await versionBump({
      release: "patch",
      commit: true,
      tag: true,
      push: false,
      execute: "npm run build"
    });
    
    console.log(`Bumped to ${result.newVersion}`);
    
  } catch (error) {
    console.error("Version bump failed:", error.message);
    process.exit(1);
  }
}

Configuration-Based Approach

Use configuration objects for flexible programmatic control:

import { versionBump, defineConfig } from "bumpp";

// Define reusable configurations
const prodConfig = defineConfig({
  commit: "chore(release): %s",
  tag: "v%s", 
  push: true,
  sign: true,
  execute: "npm run build && npm test"
});

const devConfig = defineConfig({
  commit: "chore: bump to %s",
  push: false,
  execute: "npm run build"
});

// Use based on environment
const config = process.env.NODE_ENV === "production" ? prodConfig : devConfig;
await versionBump({ ...config, release: "patch" });