nushell-plugins/INSTALLATION_QUICK_START.md

# Nushell Distribution - Quick Start

## 📦 For End Users

### 1. Extract Distribution
```bash
tar -xzf nushell-plugins-distribution.tar.gz
cd nushell-plugins-distribution
```

### 2. See Available Plugins
```bash
./install_from_manifest.nu --list
```

### 3. Install Preferred Option

**Option A: Install Essential Plugins (Recommended)**
```bash
./install_from_manifest.nu --preset essential
```

**Option B: Install Development Tools**
```bash
./install_from_manifest.nu --preset development
```

**Option C: Install Everything**
```bash
./install_from_manifest.nu --all
```

**Option D: Install Specific Plugins**
```bash
./install_from_manifest.nu --select auth kms orchestrator
```

**Option E: Preview First (Dry-Run)**
```bash
./install_from_manifest.nu --all --check
```

### 4. Verify Installation
```bash
nu -c "plugin list"
```

### 5. Restart Shell
```bash
exit && nu
```

---

## 🔧 For Distribution Creators

### 1. Create Distribution Directory
```bash
mkdir -p distribution/bin
# Copy nushell binary and plugins here
cp nu distribution/
cp nu_plugin_* distribution/bin/
```

### 2. Generate Manifest
```bash
./scripts/create_distribution_manifest.nu distribution/bin \
  --output distribution/DISTRIBUTION_MANIFEST.json
```

### 3. Add Installer
```bash
cp scripts/install_from_manifest.nu distribution/
```

### 4. Package Distribution
```bash
tar -czf nushell-plugins-distribution.tar.gz distribution/
```

### 5. Distribute Package
```bash
# Share the tar.gz file with users
# They extract it and run: ./install_from_manifest.nu
```

---

## 🎯 Common Scenarios

### "I want the essential plugins to get started"
```bash
./install_from_manifest.nu --preset essential
```

### "I want to preview what will be installed first"
```bash
./install_from_manifest.nu --all --check
```

### "I want to install only Nushell binary, no plugins"
```bash
./install_from_manifest.nu --nu-only
```

### "I want to install plugins only, skip Nushell"
```bash
./install_from_manifest.nu --plugins-only --all
```

### "I want to install but skip registration"
```bash
./install_from_manifest.nu --all --install-only
# Then manually register: nu -c "plugin add ~/.local/bin/nu_plugin_auth"
```

### "Just register plugins that are already installed"
```bash
./install_from_manifest.nu --all --register-only
```

---

## 📋 Plugin Descriptions

| Plugin | Purpose |
|--------|---------|
| `nu_plugin_auth` | Authentication (JWT, MFA) |
| `nu_plugin_kms` | Encryption & KMS |
| `nu_plugin_orchestrator` | Orchestration operations |
| `nu_plugin_kcl` | KCL configuration |
| `nu_plugin_tera` | Template rendering |
| `nu_plugin_highlight` | Syntax highlighting |
| `nu_plugin_image` | Image processing |
| `nu_plugin_clipboard` | Clipboard operations |
| `nu_plugin_hashes` | Hash functions |
| `nu_plugin_qr_maker` | QR code generation |
| `nu_plugin_fluent` | Localization |
| `nu_plugin_desktop_notifications` | Desktop notifications |
| `nu_plugin_port_extension` | Port extensions |

---

## 🆘 Troubleshooting

**Q: "Manifest not found" error?**
A: Ensure `DISTRIBUTION_MANIFEST.json` is in the same directory as the installer, or use `--manifest` flag:
```bash
./install_from_manifest.nu --manifest /path/to/manifest.json
```

**Q: Plugins installed but not appearing in `plugin list`?**
A: They need to be registered. Use:
```bash
./install_from_manifest.nu --all --register-only
```

**Q: Want to uninstall plugins?**
A: Manually remove them:
```bash
rm ~/.local/bin/nu_plugin_*
nu -c "plugin rm auth kms"  # Remove from config
```

**Q: Something went wrong, want to try again?**
A: Use dry-run first:
```bash
./install_from_manifest.nu --all --check
```

---

## ✨ Next Steps

After installation:

1. **Restart your shell**: `exit && nu`
2. **Verify plugins**: `nu -c "plugin list"`
3. **Use new plugins**: Check plugin documentation
4. **Configure**: Edit `~/.config/nushell/env.nu` if needed

Enjoy your enhanced Nushell environment! 🚀