Configuration and Utilities

The Medusa CLI provides configuration management, telemetry controls, and utility functions for optimal development experience. These features are available globally and help customize the CLI behavior according to user preferences.

Capabilities

Telemetry Management

Control anonymous usage data collection for Medusa CLI analytics and improvement purposes.

medusa telemetry [options]

Options:

• --enable: Enable telemetry data collection (default behavior)
• --disable: Disable telemetry data collection

Usage Examples:

# Enable telemetry (default)
medusa telemetry --enable

# Disable telemetry
medusa telemetry --disable

# Check current telemetry status (no options)
medusa telemetry

Behavior:

• Settings are stored globally and persist across CLI sessions
• Changes take effect immediately for all future CLI operations
• Provides confirmation message about current telemetry status
• Respects user privacy preferences

Telemetry System

Data Collection

The telemetry system collects anonymous usage information:

Collected Data:

• Command usage patterns (which commands are used)
• Error occurrence rates (for reliability improvement)
• Performance metrics (command execution times)
• Feature adoption rates (which features are popular)

Privacy Protection:

• No personally identifiable information collected
• No project code or business data transmitted
• No file paths, names, or contents collected
• Anonymous identifiers only (no user tracking)

Data Usage:

• Improve CLI performance and reliability
• Prioritize feature development based on usage
• Identify and fix common error scenarios
• Enhance user experience through data-driven insights

Configuration Storage

Telemetry preferences are managed through persistent configuration:

Storage Location:

• Global configuration store using ConfigStore library
• Platform-appropriate configuration directory
• Separate from project-specific settings
• Accessible across all CLI sessions

Configuration Management:

• Settings persist across CLI updates
• Can be manually reset or modified
• Respects system-wide privacy preferences
• Integrates with package manager preferences

Package Manager Configuration

The CLI automatically manages package manager preferences:

Package Manager Detection

Automatic Detection:

• Detects npm vs yarn based on lock files (package-lock.json vs yarn.lock)
• Recognizes npm_config_user_agent for npm-initiated sessions
• Stores detected preference for consistent behavior
• Falls back to npm if detection is inconclusive

Preference Storage:

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

Supported Package Managers:

• npm: Node Package Manager (default)
• yarn: Yarn Package Manager
• Automatic detection and preference learning
• Consistent usage across all CLI operations

Configuration Persistence

Package manager preferences are stored globally:

Storage Mechanism:

• Uses ConfigStore for persistent configuration
• Global configuration accessible from any directory
• Survives CLI updates and system restarts
• Integrates with telemetry and other preference systems

Preference Application:

• Applied to all package installation operations
• Used in project creation workflows
• Consistent across development server operations
• Affects dependency management commands

Global CLI Options

All Medusa CLI commands support these global configuration options:

Logging and Output Control

--verbose          # Enable verbose output with detailed information
--no-color         # Disable colored output for plain text
--no-colors        # Alias for --no-color option
--json             # Enable structured JSON logging format

Output Modes:

• Standard: Default colored output with progress indicators
• Verbose: Extended logging with detailed operation information
• No-Color: Plain text output suitable for log files and CI/CD
• JSON: Structured output for programmatic consumption

Use Cases:

• Development debugging with --verbose flag
• CI/CD integration with --no-color and --json
• Log file generation with structured output
• Accessibility considerations with plain text output

Help and Version Information

--help, -h         # Display command help and usage information
--version, -v      # Show CLI and project version information

Help System:

• Context-aware help display based on available commands
• Command-specific help with option descriptions
• Examples and usage patterns for each command
• Integration with "did you mean" suggestion system

Version Information:

• CLI version from package.json
• Local Medusa version (when in project context)
• Project path information for context
• Compatibility information between CLI and project versions

Utility Functions

Command Suggestion System

The CLI includes intelligent command suggestion for mistyped commands:

Suggestion Algorithm:

• Uses Levenshtein distance for similarity matching
• Suggests up to 3 most similar commands
• Context-aware suggestions based on available commands
• Helpful error messages with correction suggestions

Implementation:

function didYouMean(command: string, availableCommands: string[]): string;

User Experience:

• Immediate feedback for typos and mistakes
• Learning aid for discovering available commands
• Reduces frustration from command-line errors
• Integrates with help system for comprehensive assistance

Activity and Progress Management

The CLI includes sophisticated progress reporting:

Activity System:

• Spinner-based progress indicators for long operations
• Hierarchical activity tracking with nested operations
• Time tracking for performance monitoring
• Success/failure reporting with detailed messages

Progress Features:

• Real-time feedback during operations
• Contextual messages describing current activity
• Error recovery guidance when operations fail
• Integration with logging system for debugging

Configuration File Integration

Project Configuration Detection

The CLI automatically detects and integrates with project configurations:

Detection Mechanisms:

• package.json analysis for Medusa dependency detection
• medusa-config.js reading for project-specific settings
• Environment variable integration (.env file support)
• Automatic context switching based on current directory

Configuration Precedence:

1. Command-line options (highest priority)
2. Environment variables
3. Project configuration files
4. Global CLI preferences
5. Default values (lowest priority)

Environment Variable Support

The CLI respects numerous environment variables:

Database Configuration:

• DATABASE_URL: Primary database connection string
• DB_*: Individual database connection parameters
• NODE_ENV: Environment-specific behavior control

Development Configuration:

• PORT: Default server port for development commands
• CPUS: Default CPU count for cluster mode
• LOG_LEVEL: Logging verbosity control
• LOG_FILE: Log output file specification