4b92aa764a
Some checks failed
Build and Test / Validate Setup (push) Has been cancelled
Build and Test / Build (darwin-amd64) (push) Has been cancelled
Build and Test / Build (darwin-arm64) (push) Has been cancelled
Build and Test / Build (linux-amd64) (push) Has been cancelled
Build and Test / Build (windows-amd64) (push) Has been cancelled
Build and Test / Build (linux-arm64) (push) Has been cancelled
Build and Test / Security Audit (push) Has been cancelled
Build and Test / Package Results (push) Has been cancelled
Build and Test / Quality Gate (push) Has been cancelled
452 lines
10 KiB
Markdown
452 lines
10 KiB
Markdown
# 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.
|