nushell-plugins/guides/QUICK_START.md

# Quick Start Guide - Nushell 0.108.0 Update

**Fast track to updating Nushell and creating distributions**

---

## ⚡ ONE-LINER UPDATE

Update everything (Nushell + all plugins + distributions) in one command:

```bash
# Update to specific version (recommended)
./scripts/complete_update.nu 0.108.0

# Or use justfile
just complete-update 0.108.0
```

**What it does:**
1. ✅ Downloads Nushell 0.108.0
2. ✅ Builds with MCP + all features (~3 minutes)
3. ✅ Updates all plugin dependencies
4. ✅ Builds all plugins
5. ✅ Creates full distribution packages
6. ✅ Creates bin archives
7. ✅ Validates everything

**Total time**: ~20-30 minutes (mostly build time)

---

## 🎯 ANSWER: "How do I update everything in one go?"

**YES!** We have a complete automation system:

### Option 1: All-in-One Script (Fastest)

```bash
# Update to 0.108.0 and create everything
./scripts/complete_update.nu 0.108.0

# Update to latest release
./scripts/complete_update.nu --latest

# Auto-approve (no prompts)
./scripts/complete_update.nu 0.108.0 --auto-approve
```

### Option 2: Using Justfile (Easier to remember)

```bash
# Complete update
just complete-update 0.108.0

# Or update to latest
just update-latest

# Show all version update commands
just update-help
```

### Option 3: Step-by-Step (More control)

```bash
# Step 1: Update Nushell core
just update-nushell 0.108.0

# Step 2: Update all plugins
just update-plugins 0.108.0

# Step 3: Create distributions
just create-distribution

# Step 4: Create bin archives
just create-bin-archives
```

---

## 📦 ANSWER: "How do I create distributions and bin_archives?"

### Quick Method

```bash
# Create everything (full distributions + bin archives)
just create-distribution

# Create for all platforms
just create-distribution-all

# Create only bin archives
just create-bin-archives

# Rebuild and redistribute
just rebuild-all
```

### What Gets Created

**Full Distributions** (in `distribution/packages/`):
```
nushell-full-darwin-arm64-0.108.0.tar.gz     # macOS ARM (120 MB)
nushell-full-linux-x86_64-0.108.0.tar.gz     # Linux x64 (110 MB)
nushell-full-windows-x86_64-0.108.0.zip      # Windows (115 MB)
checksums.txt                                 # SHA256 checksums
```

**Bin Archives** (in `bin_archives/`):
```
nu_plugin_clipboard-0.108.0-darwin-arm64.tar.gz   # Individual plugins
nu_plugin_image-0.108.0-darwin-arm64.tar.gz       # (~2-8 MB each)
nu_plugin_hashes-0.108.0-darwin-arm64.tar.gz
... (one for each custom plugin)
```

---

## 🚀 Common Workflows

### Workflow 1: Fresh Update to New Version

```bash
# All-in-one command
just complete-update 0.109.0

# That's it! Everything is done.
```

### Workflow 2: Update Only Plugins

```bash
# Update plugin dependencies to match nushell
just sync-plugins

# Or specify version
just update-plugins 0.108.0

# Check for version mismatches
just check-versions
```

### Workflow 3: Create Distributions Only

```bash
# Build if needed
just build-nushell
just build

# Create distributions
just create-distribution

# Verify
just dist-status
```

### Workflow 4: Quick Development Iteration

```bash
# Make changes to plugins...

# Rebuild and redistribute
just rebuild-all

# This rebuilds nushell + plugins + creates fresh distributions
```

---

## 📊 Status Commands

Check what's happening at any time:

```bash
# Overall update status
just update-status

# Distribution status
just dist-status

# Plugin versions
just list-versions

# Check for version mismatches
just check-versions

# Dependency audit
just audit-deps
```

---

## 🔍 Analysis & Validation

### Before Update

```bash
# Detect breaking changes
just detect-breaking

# Analyze available features
just analyze-features

# Show dependency tree for a feature
just feature-tree mcp

# Audit current dependencies
just audit-deps
```

### After Update

```bash
# Validate installation
just validate-code

# Run quality checks
just quality-flow

# Test plugin registration
just verify-plugins
```

---

## 🆘 Troubleshooting

### "My update failed halfway through"

```bash
# Check status
just update-status

# Clean up and retry
just clean-update
just complete-update 0.108.0
```

### "Plugins have version mismatches"

```bash
# Auto-sync to nushell submodule version
just sync-plugins

# Or check what's wrong
just check-versions
just audit-deps
```

### "Distribution packages are missing"

```bash
# Check status
just dist-status

# Rebuild distributions
just rebuild-all
```

### "Need to rollback"

```bash
# Git rollback
git stash save "backup current state"

# Or reset to previous commit
git reset --hard HEAD~1

# Rebuild old version
just clean
just build
```

---

## 📚 Complete Documentation

For detailed information, see:

| Document | Purpose |
|----------|---------|
| `guides/COMPLETE_VERSION_UPDATE_GUIDE.md` | Complete step-by-step guide |
| `updates/108/NUSHELL_0.108_UPDATE_SUMMARY.md` | What changed in 0.108.0 |
| `updates/108/MIGRATION_0.108.0.md` | Migration guide |
| `updates/108/NUSHELL_UPDATE_AUTOMATION.md` | Automation details |
| `CHANGELOG.md` | All changes |
| `README.md` | Repository overview |

---

## 🎯 Quick Reference Card

```bash
# UPDATE EVERYTHING
just complete-update 0.108.0     # All-in-one update

# STEP-BY-STEP
just download-nushell 0.108.0    # 1. Download source
just build-nu                     # 2. Build nushell
just update-plugins 0.108.0       # 3. Update plugins
just build                        # 4. Build plugins
just create-distribution          # 5. Create packages

# STATUS & VALIDATION
just update-status                # Update system status
just dist-status                  # Distribution status
just check-versions               # Version consistency
just audit-deps                   # Dependency audit

# DISTRIBUTIONS
just create-distribution          # Current platform
just create-distribution-all      # All platforms
just create-bin-archives          # Plugins only
just rebuild-all                  # Rebuild everything

# HELP
just update-help                  # Quick command reference
just update-docs                  # Documentation paths
```

---

## ✅ Success Checklist

After running `just complete-update 0.108.0`, verify:

- [ ] Nushell binary built: `./nushell/target/release/nu --version`
- [ ] Plugins built: `ls nu_plugin_*/target/release/nu_plugin_*`
- [ ] Distribution packages created: `ls distribution/packages/`
- [ ] Bin archives created: `ls bin_archives/`
- [ ] Version is correct: `just check-versions`
- [ ] No dependency issues: `just audit-deps`

---

**Last Updated**: 2025-10-18
**Nushell Version**: 0.108.0
**Status**: ✅ Complete automation system ready