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)

curl -L https://your-url/install.sh | sh

Windows (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:

# 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):

# 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:

# 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:

# 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

# Linux/macOS
curl -L install-url/install.sh | sh -s -- --verify

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

Corporate/Enterprise Installation

# 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

# 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

# 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):

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):

sudo dnf install git curl gcc
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

macOS:

# 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:

# 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

# 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! 🚀