nushell-plugins/installers/bootstrap/README.md

# Nushell + Plugins Bootstrap Installers

Universal installers for Nushell and plugins that work without any prerequisites. These scripts solve the bootstrap problem by providing one-command installation that works on fresh systems.

## Quick Start

### Linux/macOS (POSIX Shell)
```bash
curl -L https://your-url/install.sh | sh
```

### Windows (PowerShell)
```powershell
Invoke-WebRequest -Uri "https://your-url/install.ps1" | Invoke-Expression
```

## Features

- **Zero Prerequisites**: Works on fresh systems without Rust, Git, or other dependencies
- **Multi-Platform**: Supports Linux, macOS, and Windows (x86_64, ARM64)
- **Complete Distribution**: Installs Nushell + all workspace and custom plugins
- **Automatic Configuration**: Sets up PATH, creates default config, registers plugins
- **Installation Modes**: User (~/.local/bin) or system (/usr/local/bin) installation
- **Build Options**: Pre-built binaries or build from source
- **Verification**: Optional installation verification and testing
- **Uninstallation**: Clean removal of all installed components

## Installation Options

### Basic Installation
Default installation to user directory with all plugins:

```bash
# Linux/macOS
curl -L install-url/install.sh | sh

# Windows
iwr install-url/install.ps1 | iex
```

### System Installation
Install to system directories (requires admin privileges):

```bash
# Linux/macOS (requires sudo)
curl -L install-url/install.sh | sudo sh -s -- --system

# Windows (requires admin PowerShell)
iwr install-url/install.ps1 | iex -ArgumentList "-System"
```

### Build from Source
Build Nushell and plugins from source code:

```bash
# Linux/macOS
curl -L install-url/install.sh | sh -s -- --build-from-source

# Windows
iwr install-url/install.ps1 | iex -ArgumentList "-BuildFromSource"
```

### Minimal Installation
Install only Nushell without plugins:

```bash
# Linux/macOS
curl -L install-url/install.sh | sh -s -- --no-plugins

# Windows
iwr install-url/install.ps1 | iex -ArgumentList "-NoPlugins"
```

## Command Line Options

### Linux/macOS (install.sh)

| Option | Description |
|--------|-------------|
| `--system` | Install to system directory (/usr/local/bin, requires sudo) |
| `--user` | Install to user directory (~/.local/bin) [default] |
| `--no-path` | Don't modify shell PATH configuration |
| `--no-config` | Don't create initial nushell configuration |
| `--no-plugins` | Install only nushell, skip plugins |
| `--build-from-source` | Build from source instead of downloading binaries |
| `--verify` | Verify installation after completion |
| `--uninstall` | Remove nushell and plugins |
| `--version VERSION` | Install specific version (default: latest) |
| `--help` | Show help message |

### Windows (install.ps1)

| Parameter | Description |
|-----------|-------------|
| `-System` | Install to system directory (C:\Program Files\Nushell, requires admin) |
| `-User` | Install to user directory (~\.local\bin) [default] |
| `-NoPath` | Don't modify PATH environment variable |
| `-NoConfig` | Don't create initial nushell configuration |
| `-NoPlugins` | Install only nushell, skip plugins |
| `-BuildFromSource` | Build from source instead of downloading binaries |
| `-Verify` | Verify installation after completion |
| `-Uninstall` | Remove nushell and plugins |
| `-Version <version>` | Install specific version (default: latest) |
| `-Help` | Show help message |

## Installation Locations

### User Installation (Default)
- **Linux/macOS**: `~/.local/bin`
- **Windows**: `%USERPROFILE%\.local\bin`
- No admin privileges required
- Affects only current user

### System Installation
- **Linux/macOS**: `/usr/local/bin`
- **Windows**: `C:\Program Files\Nushell\bin`
- Requires admin privileges
- Available to all users

### Configuration Directory
- **Linux/macOS**: `~/.config/nushell`
- **Windows**: `%USERPROFILE%\.config\nushell`

## What Gets Installed

### Core Components
- **nushell binary**: Main shell executable
- **Workspace plugins**: Built-in nushell plugins
  - `nu_plugin_custom_values`
  - `nu_plugin_example`
  - `nu_plugin_formats`
  - `nu_plugin_gstat`
  - `nu_plugin_inc`
  - `nu_plugin_polars`
  - `nu_plugin_query`
  - `nu_plugin_stress_internals`
- **Custom plugins**: Additional community plugins
  - `nu_plugin_clipboard`
  - `nu_plugin_desktop_notifications`
  - `nu_plugin_hashes`
  - `nu_plugin_highlight`
  - `nu_plugin_image`
  - `nu_plugin_kcl`
  - `nu_plugin_tera`
  - And more...

### Configuration Files
- `config.nu`: Main nushell configuration
- `env.nu`: Environment configuration
- Scripts directory for custom commands
- Plugins directory for plugin configurations

### PATH Integration
Automatically updates shell configuration files:
- **Bash**: `~/.bashrc`, `~/.bash_profile`
- **Zsh**: `~/.zshrc`
- **Fish**: `~/.config/fish/config.fish`
- **Nushell**: `~/.config/nushell/env.nu`
- **Generic**: `~/.profile`
- **Windows**: System/User PATH environment variable

## Examples

### Standard Installation with Verification
```bash
# Linux/macOS
curl -L install-url/install.sh | sh -s -- --verify

# Windows
iwr install-url/install.ps1 | iex -ArgumentList "-Verify"
```

### Corporate/Enterprise Installation
```bash
# System installation without auto-config
curl -L install-url/install.sh | sudo sh -s -- --system --no-config

# Windows system installation
# Run as Administrator:
iwr install-url/install.ps1 | iex -ArgumentList "-System", "-NoConfig"
```

### Development Installation
```bash
# Build from source with verification
curl -L install-url/install.sh | sh -s -- --build-from-source --verify

# Windows development
iwr install-url/install.ps1 | iex -ArgumentList "-BuildFromSource", "-Verify"
```

### Specific Version Installation
```bash
# Install specific version
curl -L install-url/install.sh | sh -s -- --version v0.107.1

# Windows specific version
iwr install-url/install.ps1 | iex -ArgumentList "-Version", "v0.107.1"
```

## Troubleshooting

### Common Issues

#### "Command not found" after installation
- Restart your terminal/command prompt
- Or reload shell configuration: `source ~/.bashrc` (Linux/macOS)
- Check if installation directory is in PATH

#### Permission denied errors
- For system installation, ensure you have admin privileges
- Use `sudo` on Linux/macOS or run PowerShell as Administrator on Windows
- Try user installation instead: `--user` or `-User`

#### Download failures
- Check internet connection
- Try building from source: `--build-from-source` or `-BuildFromSource`
- Manual download: Save installer script and run locally

#### Plugin registration failures
- Verify nushell binary works: `nu --version`
- Try manual plugin registration: `nu -c "plugin add /path/to/plugin"`
- Check plugin binary permissions (should be executable)

### Build from Source Issues

#### Missing dependencies
Install required tools:

**Linux (Ubuntu/Debian)**:
```bash
sudo apt update
sudo apt install git curl build-essential
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

**Linux (RHEL/CentOS/Fedora)**:
```bash
sudo dnf install git curl gcc
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

**macOS**:
```bash
# Install Xcode command line tools
xcode-select --install

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

**Windows**:
1. Install Git from https://git-scm.com/
2. Install Rust from https://rustup.rs/
3. Install Visual Studio Build Tools

### Verification Steps

Test your installation:

```bash
# Check nushell version
nu --version

# Test basic functionality
nu -c "echo 'Hello from Nushell'"

# List installed plugins
nu -c "plugin list"

# Check PATH
which nu    # Linux/macOS
where nu    # Windows
```

## Uninstallation

### Complete Removal
```bash
# Linux/macOS
curl -L install-url/install.sh | sh -s -- --uninstall

# Windows
iwr install-url/install.ps1 | iex -ArgumentList "-Uninstall"
```

### Manual Removal
1. Remove binaries from installation directory
2. Remove configuration directory (optional)
3. Remove PATH entries from shell configuration files
4. Remove environment variable modifications (Windows)

## Security Considerations

### Script Verification
Before running any installer, you should:
1. Review the script source code
2. Verify the download URL and SSL certificate
3. Check script signatures if available
4. Consider downloading and running locally instead of piping

### Permissions
- User installations don't require admin privileges
- System installations require elevated privileges
- Scripts only modify necessary files and directories
- No automatic execution of arbitrary code from external sources

### Network Security
- Scripts use HTTPS for all downloads
- Verify SSL certificates before downloading
- Consider using corporate proxies or mirrors
- Firewall may need to allow downloads from GitHub/your hosting

## Distribution Details

### Binary Packages
Pre-built binaries are available for:
- Linux x86_64 (GNU libc)
- Linux aarch64 (GNU libc)
- macOS x86_64 (Intel)
- macOS arm64 (Apple Silicon)
- Windows x86_64
- Windows aarch64

### Package Structure
```
nushell-plugins-{platform}-{version}.tar.gz/
├── nu(.exe)                    # Main nushell binary
├── nu_plugin_*(.exe)          # Plugin binaries
├── config/                    # Default configuration
│   ├── config.nu
│   └── env.nu
├── scripts/                   # Installation scripts
├── docs/                      # Documentation
├── LICENSE                    # License file
└── manifest.json              # Package manifest
```

## Contributing

### Testing Installers
Test the installers on various platforms:
1. Fresh VM or container
2. Different operating system versions
3. Various shell configurations
4. With and without prerequisites

### Reporting Issues
When reporting problems, include:
- Operating system and version
- Shell type and version
- Installation command used
- Complete error messages
- Network/firewall configuration

### Improvements
Areas for enhancement:
- Additional platform support
- Mirror/CDN support for faster downloads
- Package manager integration
- Corporate deployment features
- Automated testing workflows

## License

These bootstrap installers are part of the nushell-plugins project and are licensed under the same terms. See the main project LICENSE file for details.

## Support

- **Documentation**: https://nushell.sh
- **Community**: https://discord.gg/nushell
- **Issues**: https://github.com/your-org/nushell-plugins/issues
- **Discussions**: https://github.com/your-org/nushell-plugins/discussions

---

**Happy shell scripting with Nushell! 🚀**