0
# Maintenance & Utilities
1

2
Commands for maintaining the moon workspace, managing artifacts, and keeping moon itself up to date.
3

4
## Capabilities
5

6
### Clean Workspace
7

8
Remove stale or invalid artifacts from the workspace to free up disk space and ensure a clean state.
9

10
```bash { .api }
11
moon clean [--lifetime <DURATION>]
12
```
13

14
**Options:**
15
- `--lifetime <DURATION>` - Maximum age of cached artifacts to keep (default: "7 days")
16

17
**Usage Examples:**
18

19
```bash
20
# Clean with default 7-day lifetime
21
moon clean
22

23
# Clean artifacts older than 3 days
24
moon clean --lifetime "3 days"
25

26
# Clean all artifacts (immediate cleanup)
27
moon clean --lifetime "0 seconds"
28

29
# Clean artifacts older than 2 weeks
30
moon clean --lifetime "14 days"
31

32
# Clean with different time units
33
moon clean --lifetime "24 hours"
34
moon clean --lifetime "1 week"
35
moon clean --lifetime "30 minutes"
36
```
37

38
**What Gets Cleaned:**
39
- Stale build caches
40
- Unused hash manifests
41
- Temporary execution files
42
- Old dependency resolution caches
43
- Expired remote cache entries
44
- Unused toolchain downloads
45

46
### Upgrade Moon
47

48
Update moon to the latest available version.
49

50
```bash { .api }
51
moon upgrade
52
```
53

54
**Alias:** `moon up`
55

56
**Usage Examples:**
57

58
```bash
59
# Upgrade to latest version
60
moon upgrade
61

62
# Use short alias
63
moon up
64
```
65

66
**Upgrade Process:**
67
1. Checks for the latest available version
68
2. Downloads the new version
69
3. Performs backup of current installation
70
4. Installs the new version
71
5. Migrates configuration if needed
72
6. Verifies the installation
73

74
## Workspace Maintenance
75

76
### Cache Management
77

78
Moon automatically manages various caches for optimal performance:
79

80
**Build Cache:**
81
- Stores task output based on input hashes
82
- Enables incremental builds
83
- Shared across team members via remote cache
84

85
**Dependency Cache:**
86
- Caches resolved dependency graphs
87
- Speeds up project discovery
88
- Updated when configurations change
89

90
**Tool Cache:**
91
- Stores downloaded toolchain binaries
92
- Avoids re-downloading identical versions
93
- Organized by tool and version
94

95
### Storage Locations
96

97
Moon stores data in platform-specific locations:
98

99
**macOS:**
100
```
101
~/.moon/                    # User configuration and data
102
  ├── cache/               # Build and dependency caches
103
  ├── tools/               # Downloaded toolchain binaries
104
  ├── templates/           # User-defined templates
105
  └── extensions/          # Extension plugins
106

107
Workspace-specific:
108
.moon/                     # Workspace configuration
109
  ├── cache/              # Local workspace cache
110
  ├── toolchain.yml       # Tool configurations
111
  └── workspace.yml       # Workspace settings
112
```
113

114
### Disk Space Management
115

116
Monitor and manage moon's disk usage:
117

118
```bash
119
# Check cache sizes
120
du -sh ~/.moon/cache
121
du -sh .moon/cache
122

123
# Clean specific cache types
124
moon clean --lifetime "1 day"    # Recent cleanup
125
moon clean --lifetime "0"        # Full cleanup
126

127
# Manual cleanup of specific directories
128
rm -rf ~/.moon/cache/builds/*    # Clear build cache
129
rm -rf ~/.moon/tools/node/*/     # Clear old Node.js versions
130
```
131

132
### Configuration Backup
133

134
Before major changes, backup moon configuration:
135

136
```bash
137
# Backup workspace configuration
138
cp -r .moon/ .moon.backup/
139

140
# Backup user configuration  
141
cp -r ~/.moon/ ~/.moon.backup/
142

143
# Version control workspace config
144
git add .moon/
145
git commit -m "Update moon configuration"
146
```
147

148
## Debug Commands
149

150
Moon provides debug commands for inspecting internal state and troubleshooting issues.
151

152
### Debug Configuration
153

154
Display loaded moon configuration and environment settings.
155

156
```bash { .api }
157
moon debug config
158
```
159

160
This command shows:
161
- Loaded workspace configuration
162
- Toolchain settings and versions
163
- Environment variables and paths
164
- Cache locations and sizes
165
- Project discovery information
166

167
**Usage Examples:**
168

169
```bash
170
# Show complete configuration
171
moon debug config
172

173
# Filter for cache information
174
moon debug config | grep -i cache
175

176
# Check tool configurations
177
moon debug config | grep -i toolchain
178
```
179

180
### Debug VCS Integration
181

182
Display information about VCS (Version Control System) integration and settings.
183

184
```bash { .api }
185
moon debug vcs
186
```
187

188
This command shows:
189
- Git configuration and status
190
- VCS hooks configuration
191
- Remote repository information
192
- Branch and commit details
193
- Touch file detection settings
194

195
**Usage Examples:**
196

197
```bash
198
# Show VCS debug information
199
moon debug vcs
200

201
# Use in CI/CD for debugging
202
moon debug vcs > vcs-debug.log
203
```
204

205
**Note:** Debug commands are primarily intended for troubleshooting and may produce verbose output. They are useful for understanding moon's internal state and diagnosing configuration issues.
206

207
## Troubleshooting
208

209
### Common Issues
210

211
**Cache Corruption:**
212
```bash
213
# Clear all caches and rebuild
214
moon clean --lifetime "0"
215
moon setup
216
moon run build --force
217
```
218

219
**Tool Installation Issues:**
220
```bash
221
# Reinstall tools
222
moon teardown
223
moon setup
224

225
# Check tool status
226
moon toolchain info node
227
```
228

229
**Permission Problems:**
230
```bash
231
# Fix permissions on moon directories
232
chmod -R 755 ~/.moon/
233
chmod -R 755 .moon/
234
```
235

236
### Diagnostic Information
237

238
Gather diagnostic information for troubleshooting:
239

240
```bash
241
# Show moon version and environment
242
moon --version
243
moon debug config
244

245
# Check workspace health
246
moon check --all --summary
247

248
# Verify tool installations
249
moon toolchain info node
250
moon bin node
251
```
252

253
### Performance Optimization
254

255
Optimize moon performance:
256

257
```bash
258
# Use appropriate concurrency
259
moon run build --concurrency 8
260

261
# Enable remote caching
262
export MOON_CACHE=readwrite
263
moon run build
264

265
# Clean old caches regularly
266
moon clean --lifetime "3 days"
267
```
268

269
## Update Management
270

271
### Version Checking
272

273
Check for available updates:
274

275
```bash
276
# Current version
277
moon --version
278

279
# Check for updates (done automatically by upgrade)
280
moon upgrade
281
```
282

283
### Release Notes
284

285
Moon upgrade shows relevant changes:
286

287
```
288
Upgrading moon from v1.39.0 to v1.40.1
289

290
New Features:
291
- Added MCP server support
292
- Enhanced Docker integration
293
- Improved query performance
294

295
Breaking Changes:
296
- None
297

298
Migration Notes:
299
- Configuration format unchanged
300
- Cache format compatible
301
```
302

303
### Rollback
304

305
If issues occur after upgrade, rollback:
306

307
```bash
308
# Moon automatically creates backups
309
# Restore from backup (example paths)
310
cp ~/.moon.backup/bin/moon ~/.moon/bin/moon
311

312
# Or reinstall specific version
313
npm install @moonrepo/cli@1.39.0
314
```
315

316
## Automation
317

318
### Scheduled Maintenance
319

320
Automate regular maintenance tasks:
321

322
```bash
323
#!/bin/bash
324
# weekly-maintenance.sh
325

326
# Clean old caches
327
moon clean --lifetime "1 week"
328

329
# Check for updates
330
moon upgrade
331

332
# Verify workspace health
333
moon check --all
334
```
335

336
### CI/CD Integration
337

338
Include maintenance in CI/CD pipelines:
339

340
```yaml
341
# GitHub Actions example
342
- name: Clean moon cache
343
  run: moon clean --lifetime "1 day"
344

345
- name: Update moon
346
  run: moon upgrade
347

348
- name: Verify installation
349
  run: moon --version
350
```
351

352
### Monitoring
353

354
Monitor moon workspace health:
355

356
```bash
357
# Check cache sizes
358
moon debug config | grep -i cache
359

360
# Monitor build performance
361
moon run build --summary
362

363
# Check tool status
364
for tool in node npm; do
365
  echo "$tool: $(moon bin $tool)"
366
done
367
```