nushell-plugins/guides/UPDATE_INSTALLED_PLUGINS_GUIDE.md

Update Installed Plugins Guide

Overview

The scripts/update_installed_plugins.nu script manages updating Nushell plugins that are already installed in ~/.local/bin. It:

1. Detects which plugins are installed
2. Matches them with source code in the repository
3. Removes old plugin binaries
4. Rebuilds plugins from source
5. Installs new versions to ~/.local/bin
6. Registers plugins with Nushell

This is different from update_all_plugins.nu which only updates Cargo.toml dependencies.

Quick Start

Update All Installed Plugins

# Check what would be updated (dry-run)
./scripts/update_installed_plugins.nu --check

# Update all installed plugins (with confirmation)
./scripts/update_installed_plugins.nu

# Update with verification
./scripts/update_installed_plugins.nu --verify

# Force rebuild (ignore cache)
./scripts/update_installed_plugins.nu --force

Update Specific Plugin

# Check if plugin can be updated
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth --check

# Update specific plugin
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth

# Update specific plugin without registering
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth --no-register

Full Command Reference

Basic Options

Option	Short	Purpose	Default
--check	-c	Dry-run mode, no actual changes	false
--verify	-v	Verify registration after update	false
--force	-f	Force rebuild (clean build artifacts)	false
--plugin NAME	-	Update only specific plugin	All installed
--no-register	-	Skip registration step	false

Examples

# 1. Dry-run to see what would happen
./scripts/update_installed_plugins.nu --check

# 2. Update all plugins with verification
./scripts/update_installed_plugins.nu --verify

# 3. Update with force rebuild and verification
./scripts/update_installed_plugins.nu --force --verify

# 4. Update specific plugin
./scripts/update_installed_plugins.nu --plugin nu_plugin_kms

# 5. Check specific plugin only
./scripts/update_installed_plugins.nu --plugin nu_plugin_orchestrator --check

# 6. Update and skip registration (register manually later)
./scripts/update_installed_plugins.nu --no-register

What This Script Does

Step 1: Detection

📋 Step 1: Detecting installed plugins...
Found 3 installed plugin(s):
  • nu_plugin_auth (installed: /Users/user/.local/bin/nu_plugin_auth)
  • nu_plugin_kms (installed: /Users/user/.local/bin/nu_plugin_kms)
  • nu_plugin_orchestrator (installed: /Users/user/.local/bin/nu_plugin_orchestrator)

Scans ~/.local/bin for executables matching nu_plugin_* pattern.

Step 2: Source Discovery

🔍 Step 2: Finding plugin sources...
Found 5 plugin source(s)

Finds all nu_plugin_* directories in the current repository.

Step 3: Matching

🔗 Step 3: Matching installed plugins with sources...
Ready to update 3 plugin(s):
  • nu_plugin_auth
    Source: /path/to/nu_plugin_auth
    Target: ~/.local/bin/nu_plugin_auth

Matches installed plugins with their source directories.

Step 4: Removal

🗑️  Step 4: Removing old plugin binaries...
  Removing: nu_plugin_auth
    ✓ Deleted

Removes old plugin binaries from ~/.local/bin.

Step 5: Building

🔨 Step 5: Building updated plugins...
  Building: nu_plugin_auth
    Cleaning build artifacts...
    Compiling...
    ✓ Built successfully

Rebuilds plugins with cargo build --release (optional cleanup with --force).

Step 6: Installation

📦 Step 6: Installing new plugin binaries...
  Installing: nu_plugin_auth
    ✓ Installed to ~/.local/bin/nu_plugin_auth

Copies new binaries to ~/.local/bin with execute permission.

Step 7: Registration

🔌 Step 7: Registering plugins with nushell...
  Registering: nu_plugin_auth
    ✓ Registered
    ✓ Verified

Registers plugins with Nushell (removes old registration first).

Workflow Examples

Complete Update Cycle

# 1. Check what would be updated
./scripts/update_installed_plugins.nu --check

# 2. Update all plugins
./scripts/update_installed_plugins.nu

# 3. Restart shell to load new plugins
exit

# 4. Verify plugins are working
nu -c "plugin list"
nu -c "auth login --help"  # Test a specific plugin

Update With Force Rebuild

Use this if you have suspicious cache or want clean build:

# Force clean rebuild with verification
./scripts/update_installed_plugins.nu --force --verify

# Then restart and verify
exit
nu -c "plugin list"

Update Specific Plugin for Testing

# Check if plugin can be updated
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth --check

# Update just this plugin
./scripts/update_installed_plugins.nu --plugin nu_plugin_auth

# Restart and test
exit
nu -c "plugin list | where name =~ auth"

Manual Registration (if using --no-register)

# Update without registration
./scripts/update_installed_plugins.nu --no-register

# Register manually later
nu -c "plugin add ~/.local/bin/nu_plugin_auth"
nu -c "plugin add ~/.local/bin/nu_plugin_kms"
nu -c "plugin add ~/.local/bin/nu_plugin_orchestrator"

Troubleshooting

Plugin Not Found

Problem: "Plugin not found or not installed"

Solution:

# List what's installed
ls ~/.local/bin/nu_plugin_*

# List what's available in repo
ls -d nu_plugin_*

# Install plugin first
./scripts/update_installed_plugins.nu  # Updates only installed plugins

Build Failure

Problem: Build fails during step 5

Solution:

# Try with verbose output
cd nu_plugin_NAME
cargo build --release

# Or use force rebuild
./scripts/update_installed_plugins.nu --force

Registration Fails

Problem: Plugin registers but doesn't work

Solution:

# Remove and re-register manually
nu -c "plugin rm auth"
nu -c "plugin add ~/.local/bin/nu_plugin_auth"

# Restart shell
exit
nu -c "plugin list"

Permission Denied

Problem: "Permission denied" when trying to execute

Solution:

# Ensure ~/.local/bin is in PATH
echo $env.PATH | str split (char esep)

# Fix permissions
chmod +x ~/.local/bin/nu_plugin_*

# Ensure ~/.local/bin directory exists and is accessible
ls -ld ~/.local/bin

Integration with Justfile

Add to justfile for easy access:

# Update installed plugins with full workflow
update-installed-plugins:
    @echo "🔄 Updating installed plugins..."
    @./scripts/update_installed_plugins.nu --verify

# Update specific plugin
update-plugin-from-installed PLUGIN:
    @./scripts/update_installed_plugins.nu --plugin {{PLUGIN}}

# Dry-run before update
check-plugin-updates:
    @./scripts/update_installed_plugins.nu --check

Then use:

just update-installed-plugins
just update-plugin-from-installed nu_plugin_auth
just check-plugin-updates

Comparison: Update Scripts

update_all_plugins.nu

• Purpose: Update Cargo.toml dependencies
• When to use: Updating Nushell version in cargo files
• Scope: Changes source files only
• Output: Modified Cargo.toml files
• Next step: Must rebuild with just build

update_installed_plugins.nu ✨ NEW

• Purpose: Update already-installed binaries
• When to use: Refresh binaries in ~/.local/bin
• Scope: Full cycle: build → install → register
• Output: New binaries in ~/.local/bin
• Includes: Automatic registration with Nushell

Typical Workflow

1. Update source dependencies

   ./scripts/update_all_plugins.nu 0.108.0
   

2. Rebuild and install

   ./scripts/update_installed_plugins.nu --force --verify
   

3. Restart and test

   exit
   nu -c "plugin list"
   

Advanced Usage

Custom Install Directory (Future Enhancement)

Currently hardcoded to ~/.local/bin. To support custom directory:

# Future: Would allow
PLUGIN_INSTALL_DIR=/custom/path ./scripts/update_installed_plugins.nu

Batch Update Multiple Plugins

# Update in sequence
for plugin in auth kms orchestrator; do
  ./scripts/update_installed_plugins.nu --plugin nu_plugin_$plugin
done

Verify After Update

# Update with verification
./scripts/update_installed_plugins.nu --verify

# Or verify separately
nu -c "plugin list | format table"
nu -c "plugin list | each {|p| $\"($p.name): ($p.filename)\" }"

Configuration Files

• Plugin Registry: etc/plugin_registry.toml - Track plugin metadata
• Common Library: scripts/lib/common_lib.nu - Shared logging functions
• Build Config: Cargo.toml in each plugin directory

Support & Issues

For issues or enhancements:

1. Check troubleshooting section above
2. Review script output for specific error messages
3. Run with --check first to preview changes
4. Check build output: cd nu_plugin_NAME && cargo build --release

Quick Reference Card

# DRY RUN (safe, no changes)
./scripts/update_installed_plugins.nu --check

# UPDATE ALL (interactive confirmation)
./scripts/update_installed_plugins.nu

# UPDATE WITH VERIFICATION
./scripts/update_installed_plugins.nu --verify

# UPDATE ONE PLUGIN
./scripts/update_installed_plugins.nu --plugin nu_plugin_NAME

# FORCE REBUILD
./scripts/update_installed_plugins.nu --force

# SKIP REGISTRATION
./scripts/update_installed_plugins.nu --no-register

# THEN RESTART
exit

---

Script Location: scripts/update_installed_plugins.nu Install Directory: ~/.local/bin Created: 2025-10-22 Nushell Version: 0.107.1+