nushell-plugins/guides/REGISTER_CORE_PLUGINS.md

# Registering Nushell Core Plugins

**Version**: 1.0.0
**Updated**: 2025-10-22
**Nushell**: 0.108.0+

## Overview

Nushell core plugins are built-in plugins that come with Nushell when you build it with the `--workspace` flag. They provide essential functionality like data analysis, format conversion, Git integration, and more.

**Core plugins include**:
- `nu_plugin_polars` - Data analysis with Polars
- `nu_plugin_formats` - Format conversion
- `nu_plugin_inc` - Increment operations
- `nu_plugin_gstat` - Git status information
- `nu_plugin_query` - Advanced querying
- `nu_plugin_custom_values` - Custom value handling
- `nu_plugin_example` - Example plugin template
- `nu_plugin_stress_internals` - Stress testing

---

## How Plugin Registration Works

When you register a plugin, you're telling Nushell where to find the plugin binary and to load it automatically. This happens by:

1. **Registering**: `nu -c "plugin add /path/to/nu_plugin_*"`
   - Adds plugin path to Nushell config
   - Plugin loads on next Nushell startup

2. **Listing**: `nu -c "plugin list"`
   - Shows all registered plugins
   - Verifies registration worked

3. **Removing**: `nu -c "plugin rm plugin_name"`
   - Removes plugin from config
   - Plugin unloads after restart

---

## Method 1: Manual Registration

### Register a Single Core Plugin

```bash
# After building nushell with --workspace
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_polars"
```

Replace the path with your actual Nushell target directory.

### Register Multiple Core Plugins

```bash
# Register all built plugins
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_polars"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_formats"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_inc"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_gstat"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_query"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_custom_values"
```

### Verify Registration

```bash
nu -c "plugin list"
```

Expected output shows all registered plugins with their versions.

---

## Method 2: Script-Based Registration

### Using the Installation Script

If plugins are in `~/.local/bin/`:

```bash
./install_from_manifest.nu --all --register-only
```

This registers all plugins from the manifest.

### Using a Custom Nushell Script

Create a file `register_core_plugins.nu`:

```nushell
#!/usr/bin/env nu

# Register Nushell core plugins
def register_core_plugins [plugin_dir: string] {
    let core_plugins = [
        "nu_plugin_polars"
        "nu_plugin_formats"
        "nu_plugin_inc"
        "nu_plugin_gstat"
        "nu_plugin_query"
        "nu_plugin_custom_values"
    ]

    for plugin in $core_plugins {
        let plugin_path = $"($plugin_dir)/($plugin)"

        if ($plugin_path | path exists) {
            try {
                # Remove old registration if exists
                nu -c $"plugin rm ($plugin | str replace '^nu_plugin_' '')" out+err>| null
            } catch {}

            # Register new
            nu -c $"plugin add ($plugin_path)"
            print $"✓ Registered: ($plugin)"
        } else {
            print $"✗ Not found: ($plugin_path)"
        }
    }
}

# Main
let plugin_dir = if ($env | get -i NUSHELL_PLUGIN_DIR) != null {
    $env.NUSHELL_PLUGIN_DIR
} else {
    "/path/to/nushell/target/release"
}

register_core_plugins $plugin_dir
```

Run it:
```bash
chmod +x register_core_plugins.nu
./register_core_plugins.nu
```

---

## Method 3: After Building Nushell

### Step-by-Step After `cargo build --workspace`

**1. Build Nushell with workspace (includes core plugins)**:
```bash
cd nushell
cargo build --release --workspace
```

**2. Find where core plugins were built**:
```bash
ls nushell/target/release/nu_plugin_*
```

**3. Copy to installation directory** (optional, for easy access):
```bash
cp nushell/target/release/nu_plugin_* ~/.local/bin/
```

**4. Register plugins**:
```bash
# Option A: Register from build directory
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_polars"
nu -c "plugin add /path/to/nushell/target/release/nu_plugin_formats"
# ... repeat for all core plugins

# Option B: Register from ~/.local/bin/
nu -c "plugin add ~/.local/bin/nu_plugin_polars"
nu -c "plugin add ~/.local/bin/nu_plugin_formats"
# ... repeat for all core plugins
```

**5. Verify**:
```bash
nu -c "plugin list"
```

---

## Method 4: Bulk Registration Script

### Create `register_all_core_plugins.sh`

```bash
#!/bin/bash

# Nushell core plugins registration script
# Usage: ./register_all_core_plugins.sh /path/to/nushell/target/release

PLUGIN_DIR="${1:-.}"

if [ ! -d "$PLUGIN_DIR" ]; then
    echo "Error: Plugin directory not found: $PLUGIN_DIR"
    exit 1
fi

PLUGINS=(
    "nu_plugin_polars"
    "nu_plugin_formats"
    "nu_plugin_inc"
    "nu_plugin_gstat"
    "nu_plugin_query"
    "nu_plugin_custom_values"
)

echo "Registering Nushell core plugins from: $PLUGIN_DIR"
echo ""

for plugin in "${PLUGINS[@]}"; do
    plugin_path="$PLUGIN_DIR/$plugin"

    if [ -f "$plugin_path" ]; then
        echo "Registering: $plugin"

        # Remove old registration
        nu -c "plugin rm ${plugin#nu_plugin_}" 2>/dev/null || true

        # Register new
        nu -c "plugin add $plugin_path"

        if [ $? -eq 0 ]; then
            echo "✓ Success: $plugin"
        else
            echo "✗ Failed: $plugin"
        fi
    else
        echo "✗ Not found: $plugin_path"
    fi
done

echo ""
echo "Registration complete!"
echo ""
echo "Verify with: nu -c \"plugin list\""
```

Run it:
```bash
chmod +x register_all_core_plugins.sh
./register_all_core_plugins.sh /path/to/nushell/target/release
```

---

## Finding Core Plugins

### After Building with `--workspace`

Core plugins are built in the same directory as the `nu` binary:

```bash
# Find where they're built
find nushell/target/release -name "nu_plugin_*" -type f

# List them
ls -lh nushell/target/release/nu_plugin_*
```

### Checking Installed Plugins

```bash
# See what's currently registered
nu -c "plugin list"

# Get detailed info
nu -c "plugin list | each { |it| {name: $it.name, version: $it.version, path: $it.path} }"
```

---

## Troubleshooting

### Problem: "Plugin not found"

**Cause**: Plugin binary doesn't exist at specified path

**Solution**:
1. Verify you built with `--workspace`: `cargo build --release --workspace`
2. Check plugin exists: `ls nushell/target/release/nu_plugin_*`
3. Use correct full path: `nu -c "plugin add /full/path/to/nu_plugin_name"`

### Problem: "Plugin already registered"

**Solution**: Remove old registration first:
```bash
nu -c "plugin rm polars"  # Remove by short name
```

Then register new path:
```bash
nu -c "plugin add /path/to/nu_plugin_polars"
```

### Problem: Plugin not loading after registration

**Solution**:
1. Restart Nushell: `exit && nu`
2. Check registration: `nu -c "plugin list"`
3. Verify plugin path exists: `ls -l /path/to/plugin`
4. Check permissions: `chmod +x /path/to/nu_plugin_*`

### Problem: Multiple versions of same plugin

**Solution**: Remove old versions before registering new:
```bash
# Remove
nu -c "plugin rm polars"

# Verify removed
nu -c "plugin list"

# Register new path
nu -c "plugin add /new/path/to/nu_plugin_polars"
```

---

## Common Registration Scenarios

### Scenario 1: Fresh Nushell Build

```bash
# 1. Build with workspace
cd ~/nushell
cargo build --release --workspace

# 2. Register all core plugins
for plugin in ~/nushell/target/release/nu_plugin_*; do
    nu -c "plugin add $plugin"
done

# 3. Verify
nu -c "plugin list"
```

### Scenario 2: Multiple Nushell Versions

```bash
# Register from specific version
nu -c "plugin add /opt/nushell-0.108.0/nu_plugin_polars"
```

Each Nushell version can have different plugins.

### Scenario 3: Distribution Installation

```bash
# If plugins are in distribution
./install_from_manifest.nu --all --register-only

# Or manually
nu -c "plugin add ./bin/nu_plugin_polars"
nu -c "plugin add ./bin/nu_plugin_formats"
```

### Scenario 4: Development Workflow

```bash
# After each build during development
cargo build --release --workspace -p nu_plugin_polars

# Re-register
nu -c "plugin rm polars"
nu -c "plugin add ./target/release/nu_plugin_polars"

# Test in new shell
exit && nu
```

---

## Plugin Configuration

### Where Registration Happens

Plugins are registered in:
```
~/.config/nushell/env.nu
```

Each registration adds a line like:
```nushell
plugin add /path/to/nu_plugin_polars
```

### Manual Configuration

If needed, you can manually edit `env.nu`:
```bash
$EDITOR ~/.config/nushell/env.nu

# Add:
plugin add /path/to/nu_plugin_polars
plugin add /path/to/nu_plugin_formats
```

Then restart Nushell.

---

## Best Practices

✅ **DO**:
- Use absolute paths: `/full/path/to/nu_plugin_name`
- Remove old registration before re-registering
- Verify plugins exist before registering
- Check permissions: `chmod +x /path/to/plugin`
- Test after registration: `exit && nu`
- Use consistent plugin directory (e.g., `~/.local/bin/`)

❌ **DON'T**:
- Use relative paths (they may not work after shell restart)
- Register plugins that don't exist
- Register without absolute paths
- Forget to restart shell after registration
- Keep multiple copies of same plugin in different locations

---

## Quick Reference

| Task | Command |
|------|---------|
| Register single | `nu -c "plugin add /path/to/nu_plugin_name"` |
| Register all | Use loop or script (see above) |
| List all | `nu -c "plugin list"` |
| Remove | `nu -c "plugin rm plugin_name"` |
| Verify | `nu -c "plugin list"` or restart shell |
| Check path | `nu -c "plugin list \| get path"` |

---

## Related Documentation

- **Nushell Official**: https://www.nushell.sh/book/plugins.html
- **Distribution System**: See `DISTRIBUTION_SYSTEM.md`
- **Installation**: See `INSTALLATION_QUICK_START.md`
- **Full Workflow**: See `DISTRIBUTION_INSTALLER_WORKFLOW.md`

---

## Summary

**To register Nushell core plugins**:

1. **Build with workspace**: `cargo build --release --workspace`
2. **Register each plugin**: `nu -c "plugin add /path/to/nu_plugin_name"`
3. **Verify**: `nu -c "plugin list"`
4. **Restart**: `exit && nu`

That's it! Core plugins work exactly like external plugins - just `plugin add` with the full path to the binary.