nushell-plugins/guides/DISTRIBUTION_INSTALLER_WORKFLOW.md

Nushell Plugin Distribution Installer Workflow

Complete workflow for creating and distributing Nushell plugins with manifest-based installation.

Overview

The distribution installer system has three main components:

1. Manifest Generator - Scans plugins and creates a manifest
2. Manifest File - JSON file listing all available plugins
3. Distribution Installer - Lets users choose which plugins to install/register

Workflow

Step 1: Create Distribution Manifest

When you're packaging the distribution:

# Scan plugin directory and create manifest
./scripts/create_distribution_manifest.nu /path/to/plugins --output DISTRIBUTION_MANIFEST.json

Output: DISTRIBUTION_MANIFEST.json containing:

• All available plugins
• Plugin descriptions
• Plugin paths
• File sizes
• Metadata (version, creation date)

Example manifest structure:

{
  "version": "1.0.0",
  "created": "2025-10-22T10:52:08Z",
  "source_directory": "/path/to/plugins",
  "total_plugins": 13,
  "plugins": [
    {
      "name": "nu_plugin_auth",
      "purpose": "Authentication (JWT, MFA)",
      "path": "/path/to/plugins/nu_plugin_auth",
      "size_bytes": 11846592
    },
    ... more plugins
  ]
}

Step 2: Package Distribution

Include in your distribution:

distribution/
├── bin/
│   ├── nu_plugin_auth
│   ├── nu_plugin_kms
│   ├── ...
├── install_from_manifest.nu    (or ./install.nu - symlink)
└── DISTRIBUTION_MANIFEST.json   (manifest file)

Step 3: User Installation

End users run the installer:

# List available plugins
./install_from_manifest.nu --list

# Install essential preset
./install_from_manifest.nu --preset essential

# Install all plugins
./install_from_manifest.nu --all

# Install specific plugins
./install_from_manifest.nu --select auth kms orchestrator

# Dry-run (preview)
./install_from_manifest.nu --preset development --check

Manifest Generator

Script: ./scripts/create_distribution_manifest.nu

Usage

# Scan current directory
./scripts/create_distribution_manifest.nu

# Scan specific directory
./scripts/create_distribution_manifest.nu /path/to/plugins

# Custom output file
./scripts/create_distribution_manifest.nu /path/to/plugins --output my_manifest.json

What It Does

1. Scans for plugin binaries (files matching nu_plugin_*)
2. Extracts plugin information (name, purpose, path, size)
3. Creates JSON manifest file
4. Ready to be included in distribution

Distribution Installer

Script: ./install_from_manifest.nu

Usage Options

# Interactive menu
./install_from_manifest.nu

# List available plugins
./install_from_manifest.nu --list

# Use preset
./install_from_manifest.nu --preset essential   # 5 core plugins
./install_from_manifest.nu --preset development # 8 plugins
./install_from_manifest.nu --preset full        # All plugins

# Select specific plugins
./install_from_manifest.nu --select auth kms orchestrator

# Install all
./install_from_manifest.nu --all

# Dry-run (preview)
./install_from_manifest.nu --check

# Install only (skip registration)
./install_from_manifest.nu --all --install-only

# Register only (skip install)
./install_from_manifest.nu --all --register-only

What It Does

1. Loads manifest - Reads DISTRIBUTION_MANIFEST.json
2. Displays options - Shows available plugins or presets
3. User selects - Interactive menu or command-line options
4. Installs - Copies selected plugins to ~/.local/bin/
5. Registers - Updates Nushell config (~/.config/nushell/env.nu)
6. Confirms - Asks user before making changes

Available Presets

Essential (5 plugins)

• nu_plugin_auth         - Authentication
• nu_plugin_kms          - Encryption
• nu_plugin_orchestrator - Orchestration
• nu_plugin_kcl          - KCL config
• nu_plugin_tera         - Templates

Development (8 plugins)

All essential +
• nu_plugin_highlight    - Syntax highlighting
• nu_plugin_image        - Image processing
• nu_plugin_clipboard    - Clipboard

Full (All custom plugins)

All 13 custom plugins included in distribution

Example Distribution Package

nushell-plugins-3.5.0-darwin-arm64/
├── README.md
├── LICENSE
├── bin/
│   ├── nu_plugin_auth
│   ├── nu_plugin_clipboard
│   ├── nu_plugin_desktop_notifications
│   ├── nu_plugin_fluent
│   ├── nu_plugin_hashes
│   ├── nu_plugin_highlight
│   ├── nu_plugin_image
│   ├── nu_plugin_kcl
│   ├── nu_plugin_kms
│   ├── nu_plugin_orchestrator
│   ├── nu_plugin_port_extension
│   ├── nu_plugin_qr_maker
│   └── nu_plugin_tera
├── DISTRIBUTION_MANIFEST.json
├── install_from_manifest.nu
└── install.nu -> install_from_manifest.nu (symlink for convenience)

User Quick Start

# Extract distribution
tar -xzf nushell-plugins-3.5.0-darwin-arm64.tar.gz
cd nushell-plugins-3.5.0-darwin-arm64

# See what's available
./install.nu --list

# Install essential plugins
./install.nu --preset essential

# Restart Nushell
exit && nu

# Verify
nu -c "plugin list"

Build & Package Workflow

For Distribution Maintainers

# 1. Build all plugins (custom & core)
cd nushell && cargo build --release --workspace && cd ..
cargo build --release (for each custom plugin)

# 2. Create distribution directory
mkdir -p dist/bin
cp ~/.local/bin/nu_plugin_* dist/bin/
cp nushell/target/release/nu_plugin_* dist/bin/ 2>/dev/null

# 3. Generate manifest
./scripts/create_distribution_manifest.nu dist/bin --output dist/DISTRIBUTION_MANIFEST.json

# 4. Copy installer script
cp scripts/install_from_manifest.nu dist/install_from_manifest.nu
ln -s install_from_manifest.nu dist/install.nu

# 5. Add documentation
cp README.md dist/
cp LICENSE dist/

# 6. Package for distribution
tar -czf nushell-plugins-3.5.0-darwin-arm64.tar.gz dist/

File Reference

File	Purpose
scripts/create_distribution_manifest.nu	Generate manifest from plugins
scripts/install_from_manifest.nu	Install & register from manifest
DISTRIBUTION_MANIFEST.json	JSON list of available plugins
~/.local/bin/nu_plugin_*	Installed plugin binaries
~/.config/nushell/env.nu	Nushell config (plugin registrations added)

Features

✅ Automatic Detection - Scans for all available plugins ✅ Flexible Selection - Presets or individual plugin selection ✅ User Choice - No forced installations ✅ Dry-Run - Preview before installing ✅ Install & Register - Handles both steps ✅ Clean Separation - Install-only and register-only modes ✅ Safe - Confirms before making changes ✅ Easy Distribution - Single JSON manifest file

FAQ

Q: How do I update the manifest after adding new plugins? A: Run create_distribution_manifest.nu again to regenerate the manifest.

Q: Can users install plugins after distribution is created? A: Only if the plugins are included in the distribution. Core Nushell plugins require a rebuild.

Q: What if manifest is missing? A: Installer will fail with clear error message. User needs to generate manifest first.

Q: Can I customize plugin purposes/descriptions? A: Edit the manifest JSON file manually or modify get_plugin_purpose() function before generating.

Q: Do plugins need to be pre-built? A: Yes, distribution contains only binaries. No build tools needed by end users.

---

Version: 3.5.0 Manifest Version: 1.0.0 Created: 2025-10-22 Nushell: 0.108.0+