Command Reference

Complete reference for all PCU commands and options. Learn about every command, flag, and configuration option available.

Command Overview

PCU provides several main commands with both full names and convenient shortcuts:

Special Shortcuts

pcu init - Initialize Workspace

Initialize a complete PNPM workspace environment with PCU configuration.

pcu init
pcu i

Options

Configuration Templates

PCU provides pre-configured templates for common project types:

Template Types

• minimal - Basic configuration with essential settings only
• standard - Balanced configuration suitable for most projects
• full - Comprehensive configuration with all available options
• monorepo - Optimized for large monorepos with advanced features
• enterprise - Enterprise-ready with security and governance features

# Use minimal template
pcu init --template minimal

# Enterprise monorepo setup
pcu init --template enterprise --interactive

# React project with TypeScript
pcu init --template standard --react --typescript

Interactive Configuration Wizard

The interactive mode (--interactive) provides a guided setup experience:

Wizard Features

• Project Detection: Automatically detects project type (React, Vue, TypeScript)
• Workspace Structure: Discovers existing packages and suggests optimal configuration
• Package Rule Setup: Interactive selection of package rules and update strategies
• Registry Configuration: Setup for custom NPM registries and authentication
• Performance Tuning: Optimize settings based on project size and requirements
• Theme Selection: Choose color themes and progress bar styles
• Validation Setup: Configure quality gates and safety checks

Wizard Flow

1. Project Analysis: Scans existing files to understand project structure
2. Template Selection: Recommends appropriate templates based on analysis
3. Package Rules: Interactive setup of package-specific update strategies
4. Advanced Settings: Optional configuration of caching, performance, and UI settings
5. Validation: Pre-flight checks and configuration validation
6. Files Creation: Creates all necessary files with confirmation

Files and Directories Created

Core Files

Directory Structure

Template-Specific Files

Advanced Initialization

Framework-Specific Setup

# React with TypeScript monorepo
pcu init --template monorepo --react --typescript --interactive

Custom Workspace Structure

# Custom package directory and structure
pcu init --packages-dir "libs" --create-workspace --verbose

# Multiple package directories (monorepo template)
pcu init --template monorepo
# Creates: apps/, packages/, tools/, docs/

Validation and Health Checks

The init command performs comprehensive validation:

Pre-Initialization Checks

• Directory Permissions: Ensures write access to workspace directory
• PNPM Installation: Verifies PNPM is installed and accessible
• Existing Configuration: Detects and offers to merge existing configurations
• Git Repository: Checks if directory is a git repository

Post-Initialization Validation

• Configuration Syntax: Validates generated configuration files
• Workspace Structure: Ensures PNPM workspace is properly configured
• Package Discovery: Verifies PCU can discover workspace packages
• Dependency Analysis: Basic health check of existing dependencies

Usage Examples

Quick Start

pcu init

Initializes with standard template using automatic project detection.

Interactive Setup

pcu init --interactive

Launches the full configuration wizard with guided setup.

Monorepo Initialization

pcu init --template monorepo --typescript --verbose

Creates enterprise-ready monorepo with TypeScript support and detailed output.

Custom Enterprise Setup

pcu init --template enterprise --interactive --force

Interactive enterprise setup that overwrites existing configuration.

pcu check - Check for Updates

Check for outdated dependencies in your pnpm workspace catalogs.

pcu check
pcu -c
pcu chk

Options

Output Formats

• table: Rich table format with colors and details
• minimal: Simple npm-check-updates style (package → version)
• json: JSON output for programmatic use
• yaml: YAML output for configuration files

pcu update - Update Dependencies

Update catalog dependencies to newer versions.

pcu update --interactive
pcu -u -i
pcu u -i

Options

Interactive Features

The interactive mode (--interactive or -i) provides advanced package selection capabilities:

Package Selection Interface

• Multi-select with checkboxes for individual package updates
• Search functionality to filter packages by name or description
• Batch operations to select/deselect multiple packages
• Update strategy selection for each package (latest, greatest, minor, patch)

Smart Conflict Resolution

• Peer dependency detection with resolution suggestions
• Breaking change warnings based on semantic versioning analysis
• Impact analysis showing affected workspace packages
• Rollback capabilities if updates cause issues

Progress Tracking

• Real-time progress bars with multiple visual styles
• Batch processing status showing completed/pending updates
• Error recovery with skip/retry options for failed updates
• Success confirmation with summary of all changes made

Advanced Update Strategies

# Only patch and minor updates
pcu update --target minor --confirm-major

Usage Examples

Safe Interactive Update

pcu update --interactive --create-backup --target minor

Updates dependencies interactively with automatic backups, limiting to minor version bumps only.

Production-Safe Update

pcu update --exclude "*-dev" --confirm-major --dry-run

Shows what would be updated in production dependencies, requiring confirmation for major updates.

Framework-Specific Updates

pcu update --include "react*,@types/*" --prerelease

Updates React ecosystem packages including TypeScript definitions, allowing prerelease versions.

pcu analyze - Impact Analysis

Analyze the impact of updating a specific dependency to understand potential breaking changes and affected packages.

pcu analyze default react
pcu a default react 18.3.0
pcu -a react17 @types/react

Arguments

Options

Analysis Information

The analyze command provides:

• Dependencies affected by the update
• Breaking changes detected between versions
• Workspace packages that use this dependency
• Update recommendations and risk assessment
• Version compatibility analysis

Usage Examples

Analyze Latest Version Impact

pcu analyze default react

Analyzes the impact of updating React to the latest version in the default catalog.

Analyze Specific Version

pcu analyze default typescript 5.0.0

Analyzes the impact of updating TypeScript to version 5.0.0.

JSON Output for Automation

pcu analyze default lodash --format json

Outputs analysis results as JSON for programmatic processing.

pcu workspace - Workspace Info

Show workspace information and validation with comprehensive workspace analysis.

pcu workspace
pcu w

Options

Output Information

Basic Info Mode (default)

• Workspace name and path
• Total package count
• Number of catalogs
• List of catalog names

Validation Mode (--validate)

• Configuration file validation
• Workspace structure validation
• Package.json consistency checks
• Catalog integrity verification
• Exit codes: 0 (valid), 1 (issues found)

Statistics Mode (--stats)

• Detailed package breakdown
• Dependency analysis
• Catalog usage statistics
• Workspace health metrics

Usage Examples

Basic Workspace Information

pcu workspace

Displays workspace name, path, package count, and available catalogs.

Comprehensive Validation

pcu workspace --validate

Validates workspace configuration and structure, exits with appropriate code.

Detailed Statistics

pcu workspace --stats --format json

Shows detailed workspace statistics in JSON format.

Combined Analysis

pcu w --validate --stats

Performs validation and shows statistics together.

pcu security - Security Vulnerability Scanning

Comprehensive security vulnerability scanning using npm audit and optional Snyk integration, with automated fix capabilities.

pcu security
pcu sec

Options

Security Report Features

The security command provides comprehensive vulnerability analysis:

• Multi-Scanner Integration: Combines npm audit and Snyk for thorough coverage
• Severity Classification: Categorizes vulnerabilities as critical, high, moderate, low, and info
• Automated Remediation: Applies security patches automatically with --fix-vulns
• Package Recommendations: Suggests specific version updates to resolve vulnerabilities
• Development Dependencies: Optional inclusion/exclusion of dev dependencies
• CWE/CVE Information: Detailed vulnerability identifiers and descriptions
• Exit Codes: Returns appropriate codes (0 for clean, 1 for vulnerabilities found)
• CI/CD Ready: JSON output and non-interactive mode for automation

Usage Examples

Basic Vulnerability Scan

pcu security

Performs a standard security scan using npm audit, displaying results in a formatted table.

Scan with Automatic Fixes

pcu security --fix-vulns

Scans for vulnerabilities and automatically applies available security fixes.

High Severity Filter

pcu security --severity high

Shows only high and critical severity vulnerabilities, filtering out lower priority issues.

Comprehensive Scan with Snyk

pcu security --snyk --include-dev --verbose

Runs both npm audit and Snyk scan, including development dependencies with detailed vulnerability information.

CI/CD Pipeline Integration

pcu security --format json --severity critical --no-color > security-report.json

Exports critical security vulnerabilities as JSON for automated processing in CI/CD pipelines.

Auto-fix for Production

pcu security --auto-fix --severity moderate --exclude-dev

Automatically fixes moderate and higher severity vulnerabilities in production dependencies only.

Security Workflow Integration

Pre-deployment Security Check

# Fail build if critical vulnerabilities exist
pcu security --severity critical
if [ $? -ne 0 ]; then
  echo "Critical security vulnerabilities found. Build failed."
  exit 1
fi

Automated Security Maintenance

# Weekly security maintenance
pcu security --fix-vulns --severity moderate --create-backup

pcu theme - Theme Configuration

Configure color themes and UI appearance.

pcu theme --list
pcu -t --set modern
pcu theme --interactive

Options

Available Themes

Core Themes

• default - Balanced colors optimized for general terminal use
• modern - Vibrant colors perfect for development environments with syntax highlighting
• minimal - Clean monochrome design ideal for production environments and CI/CD
• neon - High contrast cyberpunk colors designed for presentations and demos

Progress Bar Styles

• default - Standard progress indication
• gradient - Smooth color transitions
• fancy - Rich visual effects with animations
• minimal - Simple clean progress bars
• rainbow - Multi-color animated progress
• neon - Glowing effect progress bars

Environment Presets

• development - Full color, detailed progress, verbose output
• production - Minimal colors, essential information only
• presentation - High contrast, large fonts, dramatic effects

Advanced Theme Features

Semantic Color Mapping

• Success - Green tones for completed operations
• Warning - Yellow/amber for caution states
• Error - Red tones for failures and critical issues
• Info - Blue tones for informational messages
• Progress - Dynamic colors for in-progress operations
• Highlight - Accent colors for important information

Interactive Theme Configuration

The interactive mode provides:

• Live preview of themes with sample output
• Custom color selection with hex code support
• Environment detection with automatic optimal settings
• Progress bar testing to see different styles in action
• Export/import theme configurations
• Per-workspace themes for project-specific styling

Usage Examples

List Available Themes

pcu theme --list

Shows all available themes with descriptions.

Set Theme Directly

pcu theme --set modern
pcu -t --set neon

Directly set a specific theme.

Interactive Theme Configuration

pcu theme --interactive
pcu -t -i

Launches a guided theme selection wizard that allows you to preview themes and configure UI settings interactively.

pcu security - Security Vulnerability Scanning

Scan for security vulnerabilities using npm audit and optional Snyk integration, with automated fix capabilities.

pcu security
pcu sec

Options

Security Report Features

• Comprehensive Scanning: Integrates npm audit and Snyk for thorough vulnerability detection
• Severity Classification: Critical, high, moderate, low, and info level vulnerabilities
• Automated Fixes: Apply security patches automatically with --fix-vulns
• Package Recommendations: Suggests specific version updates to resolve vulnerabilities
• Development Dependencies: Option to include or exclude dev dependencies from scan
• Exit Codes: Returns appropriate exit codes (0 for clean, 1 for vulnerabilities found)

Usage Examples

Basic Vulnerability Scan

pcu security

Performs a standard security scan using npm audit.

Scan with Automatic Fixes

pcu security --fix-vulns

Scans for vulnerabilities and automatically applies available fixes.

High Severity Filter

pcu security --severity high

Shows only high and critical severity vulnerabilities.

Comprehensive Scan with Snyk

pcu security --snyk --include-dev --verbose

Runs both npm audit and Snyk scan, including development dependencies with detailed output.

JSON Export for CI/CD

pcu security --format json > security-report.json

Exports security scan results as JSON for automated processing.

Interactive Features & Progress Tracking

PCU provides advanced interactive capabilities and sophisticated progress tracking across all commands.

Interactive Command Interface

Package Selection System

• Smart Multi-Select: Choose specific packages with visual checkboxes and keyboard shortcuts
• Search & Filter: Real-time package filtering with pattern matching and fuzzy search
• Batch Operations: Select/deselect entire groups with category-based selection
• Impact Preview: See potential changes before applying any updates

Configuration Wizard

The interactive configuration wizard (pcu init --interactive) provides:

• Workspace Detection: Automatic discovery of existing PNPM workspaces
• Template Selection: Choose between minimal and full configuration templates
• Package Rule Setup: Configure rules for different package categories (React, Vue, TypeScript)
• Registry Configuration: Set up custom NPM registries and authentication
• Validation Settings: Configure quality gates and safety checks

Directory & File Browser

• Workspace Navigation: Built-in file system browser for workspace selection
• Path Validation: Real-time validation of workspace paths and structures
• Preview Mode: See workspace contents before confirming selection

Advanced Progress Tracking

Multi-Style Progress Bars

PCU offers six different progress bar styles, configurable per command or globally:

# Use gradient progress bars
pcu update --progress-style gradient

# Rainbow animated progress
pcu check --progress-style rainbow

# Minimal for CI/CD environments
pcu security --progress-style minimal

Progress Features

• Multi-step Tracking: Shows progress across different phases (scan → analyze → update)
• Parallel Operation Status: Individual progress bars for concurrent operations
• Performance Metrics: Real-time speed indicators, ETA calculations, elapsed time
• Memory-Safe Display: Stable multi-line output that reduces terminal flickering

Batch Processing Status

• Queue Management: Shows pending, active, and completed package operations
• Conflict Resolution: Interactive handling of peer dependency conflicts
• Error Recovery: Skip/retry options for failed operations with detailed error context
• Rollback Capabilities: Undo changes if issues are detected during updates

Error Handling & Recovery

Smart Error Detection

• Validation Errors: Pre-flight checks with helpful suggestions for common mistakes
• Network Issues: Automatic retry with exponential backoff for registry failures
• Dependency Conflicts: Detailed conflict analysis with resolution recommendations
• Permission Problems: Clear guidance for file system permission issues

Interactive Recovery Options

• Skip & Continue: Skip problematic packages and continue with remaining updates
• Retry with Options: Retry failed operations with different parameters
• Rollback Changes: Undo partial changes if issues occur during batch operations
• Export Error Report: Generate detailed error reports for troubleshooting

Workspace Integration

Auto-Discovery Features

• PNPM Workspace Detection: Automatically finds and validates workspace configurations
• Catalog Discovery: Detects existing catalogs and their package mappings
• Package Analysis: Analyzes workspace structure and dependency relationships
• Configuration Inheritance: Applies workspace-specific settings automatically

Validation & Health Checks

• Structure Validation: Ensures workspace follows PNPM best practices
• Dependency Consistency: Checks for version mismatches across packages
• Configuration Integrity: Validates PCU configuration against workspace structure
• Health Metrics: Provides comprehensive workspace health assessment

Usage Examples

Interactive Update with Advanced Features

pcu update --interactive --progress-style fancy --batch-size 15

Launches interactive update with fancy progress bars and optimized batch processing.

Configuration with Preview

pcu init --interactive --preview --verbose

Runs configuration wizard with preview mode and detailed logging.

Error Recovery Workflow

pcu update --interactive --create-backup --confirm-major

Updates with interactive error recovery, automatic backups, and major version confirmation.

Global Options

These options work with all commands and can be set via environment variables:

Environment Variable Usage

All global options and command-specific settings can be configured via environment variables:

Core Environment Variables

Command-Specific Environment Variables

Theme & Display Environment Variables

Security & Cache Environment Variables

Advanced Configuration Environment Variables

Environment Variable Examples

# Development setup with full features
export PCU_WORKSPACE="./my-workspace"
export PCU_VERBOSE=true
export PCU_THEME="modern"
export PCU_PROGRESS_STYLE="fancy"
export PCU_INTERACTIVE=true
export PCU_CREATE_BACKUP=true

Configuration Priority

Settings are applied in this order (later overrides earlier):

1. Built-in defaults
2. Global config (~/.pcurc.json)
3. Project config (.pcurc.json)
4. Environment variables (PCU_*)
5. Command-line flags (highest priority)

Auto-Update System

PCU includes a sophisticated auto-update mechanism that keeps the CLI tool current with the latest features and security patches.

Automatic Update Checking

By default, PCU checks for updates when you run any command:

# PCU automatically checks for updates
pcu check
# Output may include: "📦 PCU v0.8.0 is available (current: v0.7.15)"

Update Behavior

CI/CD Environment Detection

PCU automatically detects CI/CD environments and skips update checks to avoid disrupting automated pipelines:

• GitHub Actions: Detected via GITHUB_ACTIONS environment variable
• CircleCI: Detected via CIRCLECI environment variable
• Jenkins: Detected via JENKINS_URL environment variable
• GitLab CI: Detected via GITLAB_CI environment variable
• Azure DevOps: Detected via TF_BUILD environment variable
• Generic CI: Detected via CI environment variable

Update Installation

PCU supports multiple package managers with automatic fallback:

# PCU tries in order: npm → pnpm → yarn
npm install -g pcu@latest
# If npm fails, tries:
pnpm add -g pnpm-catalog-updates@latest
# If pnpm fails, tries:
yarn global add pnpm-catalog-updates@latest

Configuration Options

Environment Variables

Configuration File Settings

{
  "updates": {
    "checkForUpdates": true,
    "autoUpdate": false,
    "checkInterval": 86400000,
    "timeout": 5000,
    "skipInCI": true,
    "notifyPrerelease": false
  }
}

Update Notifications

Standard Notification

pcu check
# ✨ PCU v0.8.0 is available (current: v0.7.15)
# Run 'npm install -g pcu@latest' to update
# Use --no-update-check to disable this message

Security Update Notification

pcu security
# 🔒 SECURITY UPDATE: PCU v0.7.16 contains security fixes (current: v0.7.15)
# Update immediately: npm install -g pcu@latest

Prerelease Notification

# Only shown if notifyPrerelease: true
pcu check
# 🧪 PCU v0.8.0-beta.1 is available for testing (current: v0.7.15)
# Install with: npm install -g pcu@beta

Manual Update Commands

# Check current version and available updates
pcu --version
pcu -V

Troubleshooting Updates

Update Check Failures

# If update check fails due to network issues
PCU_UPDATE_TIMEOUT=10000 pcu check

# Force update check even in CI
PCU_SKIP_VERSION_CHECK=false CI=false pcu check

Cache Clearing

# Clear update check cache
rm -rf ~/.pcu/cache/version-check

# Or disable caching entirely
PCU_CACHE_ENABLED=false pcu check

Permission Issues

# Fix npm permission issues
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# Or use pnpm/yarn which handle permissions better
pnpm add -g pnpm-catalog-updates@latest

Cache Management System

PCU includes a comprehensive caching system to optimize performance and reduce network requests.

Cache Types

Registry Cache

Stores NPM package metadata and version information:

• Default TTL: 1 hour (3,600,000ms)
• Max Size: 10MB per cache type
• Max Entries: 500 packages
• Disk Persistence: Enabled

Workspace Cache

Stores workspace configuration and package.json parsing results:

• Default TTL: 5 minutes (300,000ms)
• Max Size: 5MB
• Max Entries: 200 workspaces
• Disk Persistence: Disabled (memory only)

Cache Configuration

Environment Variables

Configuration File Settings

{
  "cache": {
    "enabled": true,
    "ttl": 3600000,
    "maxSize": 52428800,
    "maxEntries": 10000,
    "persistToDisk": true,
    "cacheDir": "~/.pcu/cache",
    "registry": {
      "ttl": 3600000,
      "maxSize": 10485760,
      "maxEntries": 500
    },
    "workspace": {
      "ttl": 300000,
      "maxSize": 5242880,
      "maxEntries": 200,
      "persistToDisk": false
    }
  }
}

Cache Management Commands

# View cache statistics (via verbose mode)
pcu check --verbose
# Shows: Cache hits: 85%, Size: 15.2MB, Entries: 342

Cache Performance

Optimization Features

• LRU Eviction: Least Recently Used items removed first
• Automatic Cleanup: Expired entries removed every 5 minutes
• Size Monitoring: Automatic eviction when size limits exceeded
• Parallel Processing: Cache operations don't block main thread

Performance Benefits

• Registry Requests: 60-90% reduction in NPM registry calls
• Workspace Parsing: 80-95% faster workspace analysis on repeat runs
• Network Dependency: Reduced reliance on network connectivity
• Startup Time: 2-5x faster startup for subsequent operations