Configuration Management

CLI configuration and utility commands for environment information, settings management, and system diagnostics.

Capabilities

Environment Information

Comprehensive environment and system information for debugging and issue reporting.

/**
 * Display environment information for debugging
 * @param options - Information display options
 */
gatsby info [options]

interface InfoOptions {
  clipboard?: boolean;  // -C, --clipboard copy to clipboard automatically
}

Usage Examples:

# Display environment information
gatsby info

# Copy information to clipboard automatically  
gatsby info --clipboard
gatsby info -C

Information Categories:

System Information:

• Operating system and version
• CPU architecture and specifications
• Shell environment

Runtime Information:

• Node.js version
• npm version
• Yarn version (if available)

Browser Information:

• Chrome version
• Edge version
• Firefox version
• Safari version

Development Tools:

• Python version (for native dependencies)
• Git version and configuration

Gatsby Packages:

• All installed gatsby-* packages (local and global)
• Version information for each package
• Dependency tree analysis

Sample Output:

System:
  OS: macOS 13.4.1
  CPU: (8) arm64 Apple M1
  Shell: 5.9 - /bin/zsh

Binaries:
  Node: 18.16.0 - ~/.nvm/versions/node/v18.16.0/bin/node
  npm: 9.5.1 - ~/.nvm/versions/node/v18.16.0/bin/npm
  Yarn: 1.22.19 - ~/.nvm/versions/node/v18.16.0/bin/yarn

Browsers:
  Chrome: 114.0.5735.133
  Edge: Not Found
  Firefox: Not Found
  Safari: 16.5.2

npmPackages:
  gatsby: ^5.14.0 => 5.14.0
  gatsby-cli: ^5.14.0 => 5.14.0
  gatsby-plugin-image: ^3.14.0 => 3.14.0

Clipboard Integration

Automatic copying of environment information for easy sharing and issue reporting.

/**
 * Clipboard functionality for environment information
 * Automatically copies output to system clipboard
 */
interface ClipboardConfig {
  clipboard: boolean;    // Enable automatic clipboard copying
}

Platform Support:

• macOS: Uses pbcopy command
• Windows: Uses PowerShell clipboard functionality
• Linux: Requires X11 display server (automatically disabled on TTY)

Usage Examples:

# Copy to clipboard (works on macOS and Windows)
gatsby info --clipboard

# Linux with GUI
DISPLAY=:0 gatsby info --clipboard

# Linux TTY (clipboard disabled automatically)
gatsby info --clipboard  # Still displays output, no clipboard

CLI Configuration

Manage CLI-specific configuration settings and preferences.

/**
 * CLI configuration management
 * @param cmd - Configuration command (set)
 * @param key - Configuration key to modify
 * @param value - New value for the configuration key
 */
gatsby options <cmd> [key] [value]

type ConfigCommand = "set";
type ConfigKey = "pm" | "package-manager";
type ConfigValue = "npm" | "yarn";

Usage Examples:

# View current configuration
gatsby options

# Set package manager to yarn
gatsby options set pm yarn
gatsby options set package-manager yarn

# Set package manager to npm
gatsby options set pm npm
gatsby options set package-manager npm

Configuration Storage:

/**
 * Configuration storage interface
 * Uses Gatsby's centralized configuration system
 */
interface ConfigStore {
  get(key: string): any;              // Retrieve configuration value
  set(key: string, value: any): void; // Set configuration value
}

/**
 * Package manager configuration
 */
type PackageManager = "yarn" | "npm";

Supported Configuration Keys:

• cli.packageManager - Preferred package manager for gatsby new
• Default values automatically detected from system

Package Manager Configuration

Manage package manager preferences for project creation and dependency management.

/**
 * Package manager preference management
 * Controls which package manager gatsby new uses
 */
interface PackageManagerConfig {
  packageManager: PackageManager;    // Preferred package manager
}

/**
 * Package manager utility functions
 */
function getPackageManager(): PackageManager;
function setPackageManager(packageManager: PackageManager): void;

Package Manager Detection:

• Automatic detection of available package managers
• Preference for yarn if yarn.lock exists in project
• Fallback to npm if yarn not available
• User override via configuration

Configuration Impact:

• Affects gatsby new dependency installation
• Used for plugin installation recommendations
• Influences project scaffolding choices

Version Information

Display version information for Gatsby CLI and related packages.

/**
 * Version information display
 * Shows CLI version and local Gatsby version
 */
gatsby --version
gatsby -v

Usage Examples:

# Show version information
gatsby --version
gatsby -v

Version Display Logic:

/**
 * Version information structure
 */
interface VersionInfo {
  cliVersion: string;           // gatsby-cli package version
  gatsbyVersion?: string;       // Local gatsby version (if in project)
  projectPath?: string;         // Current project path
}

Sample Output:

# Outside Gatsby project
Gatsby CLI version: 5.14.0

# Inside Gatsby project  
Gatsby CLI version: 5.14.0
Gatsby version: 5.14.0
  Note: this is the Gatsby version for the site at: /Users/dev/my-gatsby-site

Telemetry Management (Deprecated)

Telemetry and analytics configuration (feature deprecated and disabled).

/**
 * Telemetry configuration (deprecated)
 * All telemetry is now disabled by default
 */
gatsby telemetry [options]

interface TelemetryOptions {
  enable?: boolean;   // Enable telemetry (no effect)
  disable?: boolean;  // Disable telemetry (no effect)
}

Usage Examples:

# Check telemetry status (always disabled)
gatsby telemetry

# Attempt to enable (no effect)
gatsby telemetry --enable

# Attempt to disable (no effect)  
gatsby telemetry --disable

Telemetry Status:

• Telemetry collection permanently disabled
• Commands preserved for backward compatibility
• No data collection or transmission occurs
• Privacy-focused approach adopted

Feedback Preferences

Manage user feedback and survey preferences for Gatsby CLI development.

/**
 * Feedback preference management
 * Controls whether user feedback prompts are shown
 */
gatsby feedback [options]

interface FeedbackOptions {
  enable?: boolean;   // --enable feedback requests
  disable?: boolean;  // --disable feedback requests
}

Usage Examples:

# Check current feedback preferences
gatsby feedback

# Enable feedback requests
gatsby feedback --enable

# Disable feedback requests
gatsby feedback --disable

Feedback System:

• Periodic feedback prompts during development
• User survey invitations for feature research
• Bug report and improvement suggestions
• Opt-in/opt-out preference management
• Privacy-respecting data collection

Feedback Types:

• Development workflow surveys
• Feature usage analytics
• Performance feedback requests
• User experience research
• Community engagement initiatives

System Diagnostics

Advanced diagnostic information for troubleshooting complex issues.

Node.js Version Validation:

• Minimum version requirement checking (Node.js 18.0.0+)
• Version compatibility warnings
• Prerelease version notifications
• Upgrade recommendations

Dependency Analysis:

• Package version conflicts
• Missing dependency detection
• Peer dependency validation
• Security vulnerability warnings

Environment Validation:

• Required system tools availability
• Build tool compatibility
• Platform-specific requirements
• Development environment setup

Configuration File Management

Management of Gatsby CLI configuration files and settings persistence.

/**
 * Configuration file management
 * Handles persistent storage of CLI preferences
 */
interface ConfigFileManager {
  configPath: string;                    // Configuration file location
  load(): Record<string, any>;          // Load configuration from file
  save(config: Record<string, any>): void; // Save configuration to file
  reset(): void;                         // Reset to default configuration
}

Configuration Locations:

• macOS: ~/Library/Preferences/gatsby-cli/
• Windows: %APPDATA%/gatsby-cli/
• Linux: ~/.config/gatsby-cli/

Configuration Persistence:

• JSON-based configuration storage
• Atomic write operations for safety
• Backup and recovery capabilities
• Migration support for format changes

Error Handling

Configuration management includes comprehensive error handling:

Configuration Errors:

• Invalid configuration values
• File permission issues
• Corrupted configuration files
• Missing configuration directories

Environment Errors:

• Unsupported Node.js versions
• Missing system dependencies
• Platform compatibility issues
• Network connectivity problems

Recovery Strategies:

• Automatic configuration repair
• Default value fallbacks
• Configuration reset options
• Detailed error reporting with solutions

Integration with Development Workflow

Configuration management integrates with common development workflows:

Project Initialization:

• Package manager preference application
• Environment validation before setup
• Configuration inheritance from global settings
• Project-specific overrides

CI/CD Integration:

• Environment variable override support
• Automated configuration validation
• Build environment optimization
• Configuration export and import

Team Collaboration:

• Shared configuration templates
• Project-specific settings documentation
• Configuration version control integration
• Team preference synchronization