0
# Configuration and Utilities
1

2
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.
3

4
## Capabilities
5

6
### Telemetry Management
7

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

10
```bash { .api }
11
medusa telemetry [options]
12
```
13

14
**Options:**
15
- `--enable`: Enable telemetry data collection (default behavior)
16
- `--disable`: Disable telemetry data collection
17

18
**Usage Examples:**
19

20
```bash
21
# Enable telemetry (default)
22
medusa telemetry --enable
23

24
# Disable telemetry
25
medusa telemetry --disable
26

27
# Check current telemetry status (no options)
28
medusa telemetry
29
```
30

31
**Behavior:**
32
- Settings are stored globally and persist across CLI sessions
33
- Changes take effect immediately for all future CLI operations
34
- Provides confirmation message about current telemetry status
35
- Respects user privacy preferences
36

37
## Telemetry System
38

39
### Data Collection
40

41
The telemetry system collects anonymous usage information:
42

43
**Collected Data:**
44
- Command usage patterns (which commands are used)
45
- Error occurrence rates (for reliability improvement)
46
- Performance metrics (command execution times)
47
- Feature adoption rates (which features are popular)
48

49
**Privacy Protection:**
50
- No personally identifiable information collected
51
- No project code or business data transmitted
52
- No file paths, names, or contents collected
53
- Anonymous identifiers only (no user tracking)
54

55
**Data Usage:**
56
- Improve CLI performance and reliability
57
- Prioritize feature development based on usage
58
- Identify and fix common error scenarios
59
- Enhance user experience through data-driven insights
60

61
### Configuration Storage
62

63
Telemetry preferences are managed through persistent configuration:
64

65
**Storage Location:**
66
- Global configuration store using ConfigStore library
67
- Platform-appropriate configuration directory
68
- Separate from project-specific settings
69
- Accessible across all CLI sessions
70

71
**Configuration Management:**
72
- Settings persist across CLI updates
73
- Can be manually reset or modified
74
- Respects system-wide privacy preferences
75
- Integrates with package manager preferences
76

77
## Package Manager Configuration
78

79
The CLI automatically manages package manager preferences:
80

81
### Package Manager Detection
82

83
**Automatic Detection:**
84
- Detects npm vs yarn based on lock files (package-lock.json vs yarn.lock)
85
- Recognizes npm_config_user_agent for npm-initiated sessions
86
- Stores detected preference for consistent behavior
87
- Falls back to npm if detection is inconclusive
88

89
**Preference Storage:**
90
```typescript { .api }
91
// Package manager utility functions
92
function getPackageManager(): string;
93
function setPackageManager(packageManager: string): void;
94
```
95

96
**Supported Package Managers:**
97
- `npm`: Node Package Manager (default)
98
- `yarn`: Yarn Package Manager
99
- Automatic detection and preference learning
100
- Consistent usage across all CLI operations
101

102
### Configuration Persistence
103

104
Package manager preferences are stored globally:
105

106
**Storage Mechanism:**
107
- Uses ConfigStore for persistent configuration
108
- Global configuration accessible from any directory
109
- Survives CLI updates and system restarts
110
- Integrates with telemetry and other preference systems
111

112
**Preference Application:**
113
- Applied to all package installation operations
114
- Used in project creation workflows
115
- Consistent across development server operations
116
- Affects dependency management commands
117

118
## Global CLI Options
119

120
All Medusa CLI commands support these global configuration options:
121

122
### Logging and Output Control
123

124
```bash { .api }
125
--verbose          # Enable verbose output with detailed information
126
--no-color         # Disable colored output for plain text
127
--no-colors        # Alias for --no-color option
128
--json             # Enable structured JSON logging format
129
```
130

131
**Output Modes:**
132
- **Standard**: Default colored output with progress indicators
133
- **Verbose**: Extended logging with detailed operation information
134
- **No-Color**: Plain text output suitable for log files and CI/CD
135
- **JSON**: Structured output for programmatic consumption
136

137
**Use Cases:**
138
- Development debugging with --verbose flag
139
- CI/CD integration with --no-color and --json
140
- Log file generation with structured output
141
- Accessibility considerations with plain text output
142

143
### Help and Version Information
144

145
```bash { .api }
146
--help, -h         # Display command help and usage information
147
--version, -v      # Show CLI and project version information
148
```
149

150
**Help System:**
151
- Context-aware help display based on available commands
152
- Command-specific help with option descriptions
153
- Examples and usage patterns for each command
154
- Integration with "did you mean" suggestion system
155

156
**Version Information:**
157
- CLI version from package.json
158
- Local Medusa version (when in project context)
159
- Project path information for context
160
- Compatibility information between CLI and project versions
161

162
## Utility Functions
163

164
### Command Suggestion System
165

166
The CLI includes intelligent command suggestion for mistyped commands:
167

168
**Suggestion Algorithm:**
169
- Uses Levenshtein distance for similarity matching
170
- Suggests up to 3 most similar commands
171
- Context-aware suggestions based on available commands
172
- Helpful error messages with correction suggestions
173

174
**Implementation:**
175
```typescript { .api }
176
function didYouMean(command: string, availableCommands: string[]): string;
177
```
178

179
**User Experience:**
180
- Immediate feedback for typos and mistakes
181
- Learning aid for discovering available commands
182
- Reduces frustration from command-line errors
183
- Integrates with help system for comprehensive assistance
184

185
### Activity and Progress Management
186

187
The CLI includes sophisticated progress reporting:
188

189
**Activity System:**
190
- Spinner-based progress indicators for long operations
191
- Hierarchical activity tracking with nested operations
192
- Time tracking for performance monitoring
193
- Success/failure reporting with detailed messages
194

195
**Progress Features:**
196
- Real-time feedback during operations
197
- Contextual messages describing current activity
198
- Error recovery guidance when operations fail
199
- Integration with logging system for debugging
200

201
## Configuration File Integration
202

203
### Project Configuration Detection
204

205
The CLI automatically detects and integrates with project configurations:
206

207
**Detection Mechanisms:**
208
- package.json analysis for Medusa dependency detection
209
- medusa-config.js reading for project-specific settings
210
- Environment variable integration (.env file support)
211
- Automatic context switching based on current directory
212

213
**Configuration Precedence:**
214
1. Command-line options (highest priority)
215
2. Environment variables
216
3. Project configuration files
217
4. Global CLI preferences
218
5. Default values (lowest priority)
219

220
### Environment Variable Support
221

222
The CLI respects numerous environment variables:
223

224
**Database Configuration:**
225
- `DATABASE_URL`: Primary database connection string
226
- `DB_*`: Individual database connection parameters
227
- `NODE_ENV`: Environment-specific behavior control
228

229
**Development Configuration:**
230
- `PORT`: Default server port for development commands
231
- `CPUS`: Default CPU count for cluster mode
232
- `LOG_LEVEL`: Logging verbosity control
233
- `LOG_FILE`: Log output file specification