nushell-plugins/guides/update-installed-plugins-guide.md

Update Installed Plugins Guide\n\n## Overview\n\nThe scripts/update_installed_plugins.nu script manages updating Nushell plugins that are already installed in ~/.local/bin. It:\n\n1. Detects which plugins are installed\n2. Matches them with source code in the repository\n3. Removes old plugin binaries\n4. Rebuilds plugins from source\n5. Installs new versions to ~/.local/bin\n6. Registers plugins with Nushell\n\nThis is different from update_all_plugins.nu which only updates Cargo.toml dependencies.\n\n## Quick Start\n\n### Update All Installed Plugins\n\nbash\n# Check what would be updated (dry-run)\n./scripts/update_installed_plugins.nu --check\n\n# Update all installed plugins (with confirmation)\n./scripts/update_installed_plugins.nu\n\n# Update with verification\n./scripts/update_installed_plugins.nu --verify\n\n# Force rebuild (ignore cache)\n./scripts/update_installed_plugins.nu --force\n\n\n### Update Specific Plugin\n\nbash\n# Check if plugin can be updated\n./scripts/update_installed_plugins.nu --plugin nu_plugin_auth --check\n\n# Update specific plugin\n./scripts/update_installed_plugins.nu --plugin nu_plugin_auth\n\n# Update specific plugin without registering\n./scripts/update_installed_plugins.nu --plugin nu_plugin_auth --no-register\n\n\n## Full Command Reference\n\n### Basic Options\n\n| Option | Short | Purpose | Default |\n|--------|-------|---------|---------|\n| --check | -c | Dry-run mode, no actual changes | false |\n| --verify | -v | Verify registration after update | false |\n| --force | -f | Force rebuild (clean build artifacts) | false |\n| --plugin NAME | - | Update only specific plugin | All installed |\n| --no-register | - | Skip registration step | false |\n\n### Examples\n\nbash\n# 1. Dry-run to see what would happen\n./scripts/update_installed_plugins.nu --check\n\n# 2. Update all plugins with verification\n./scripts/update_installed_plugins.nu --verify\n\n# 3. Update with force rebuild and verification\n./scripts/update_installed_plugins.nu --force --verify\n\n# 4. Update specific plugin\n./scripts/update_installed_plugins.nu --plugin nu_plugin_kms\n\n# 5. Check specific plugin only\n./scripts/update_installed_plugins.nu --plugin nu_plugin_orchestrator --check\n\n# 6. Update and skip registration (register manually later)\n./scripts/update_installed_plugins.nu --no-register\n\n\n## What This Script Does\n\n### Step 1: Detection\n\nplaintext\n📋 Step 1: Detecting installed plugins...\nFound 3 installed plugin(s):\n • nu_plugin_auth (installed: /Users/user/.local/bin/nu_plugin_auth)\n • nu_plugin_kms (installed: /Users/user/.local/bin/nu_plugin_kms)\n • nu_plugin_orchestrator (installed: /Users/user/.local/bin/nu_plugin_orchestrator)\n\n\nScans ~/.local/bin for executables matching nu_plugin_* pattern.\n\n### Step 2: Source Discovery\n\nplaintext\n🔍 Step 2: Finding plugin sources...\nFound 5 plugin source(s)\n\n\nFinds all nu_plugin_* directories in the current repository.\n\n### Step 3: Matching\n\nplaintext\n🔗 Step 3: Matching installed plugins with sources...\nReady to update 3 plugin(s):\n • nu_plugin_auth\n Source: /path/to/nu_plugin_auth\n Target: ~/.local/bin/nu_plugin_auth\n\n\nMatches installed plugins with their source directories.\n\n### Step 4: Removal\n\nplaintext\n🗑️ Step 4: Removing old plugin binaries...\n Removing: nu_plugin_auth\n ✓ Deleted\n\n\nRemoves old plugin binaries from ~/.local/bin.\n\n### Step 5: Building\n\nplaintext\n🔨 Step 5: Building updated plugins...\n Building: nu_plugin_auth\n Cleaning build artifacts...\n Compiling...\n ✓ Built successfully\n\n\nRebuilds plugins with cargo build --release (optional cleanup with --force).\n\n### Step 6: Installation\n\nplaintext\n📦 Step 6: Installing new plugin binaries...\n Installing: nu_plugin_auth\n ✓ Installed to ~/.local/bin/nu_plugin_auth\n\n\nCopies new binaries to ~/.local/bin with execute permission.\n\n### Step 7: Registration\n\nplaintext\n🔌 Step 7: Registering plugins with nushell...\n Registering: nu_plugin_auth\n ✓ Registered\n ✓ Verified\n\n\nRegisters plugins with Nushell (removes old registration first).\n\n## Workflow Examples\n\n### Complete Update Cycle\n\nbash\n# 1. Check what would be updated\n./scripts/update_installed_plugins.nu --check\n\n# 2. Update all plugins\n./scripts/update_installed_plugins.nu\n\n# 3. Restart shell to load new plugins\nexit\n\n# 4. Verify plugins are working\nnu -c "plugin list"\nnu -c "auth login --help" # Test a specific plugin\n\n\n### Update With Force Rebuild\n\nUse this if you have suspicious cache or want clean build:\n\nbash\n# Force clean rebuild with verification\n./scripts/update_installed_plugins.nu --force --verify\n\n# Then restart and verify\nexit\nnu -c "plugin list"\n\n\n### Update Specific Plugin for Testing\n\nbash\n# Check if plugin can be updated\n./scripts/update_installed_plugins.nu --plugin nu_plugin_auth --check\n\n# Update just this plugin\n./scripts/update_installed_plugins.nu --plugin nu_plugin_auth\n\n# Restart and test\nexit\nnu -c "plugin list | where name =~ auth"\n\n\n### Manual Registration (if using --no-register)\n\nbash\n# Update without registration\n./scripts/update_installed_plugins.nu --no-register\n\n# Register manually later\nnu -c "plugin add ~/.local/bin/nu_plugin_auth"\nnu -c "plugin add ~/.local/bin/nu_plugin_kms"\nnu -c "plugin add ~/.local/bin/nu_plugin_orchestrator"\n\n\n## Troubleshooting\n\n### Plugin Not Found\n\nProblem: "Plugin not found or not installed"\n\nSolution:\n\nbash\n# List what's installed\nls ~/.local/bin/nu_plugin_*\n\n# List what's available in repo\nls -d nu_plugin_*\n\n# Install plugin first\n./scripts/update_installed_plugins.nu # Updates only installed plugins\n\n\n### Build Failure\n\nProblem: Build fails during step 5\n\nSolution:\n\nbash\n# Try with verbose output\ncd nu_plugin_NAME\ncargo build --release\n\n# Or use force rebuild\n./scripts/update_installed_plugins.nu --force\n\n\n### Registration Fails\n\nProblem: Plugin registers but doesn't work\n\nSolution:\n\nbash\n# Remove and re-register manually\nnu -c "plugin rm auth"\nnu -c "plugin add ~/.local/bin/nu_plugin_auth"\n\n# Restart shell\nexit\nnu -c "plugin list"\n\n\n### Permission Denied\n\nProblem: "Permission denied" when trying to execute\n\nSolution:\n\nbash\n# Ensure ~/.local/bin is in PATH\necho $env.PATH | str split (char esep)\n\n# Fix permissions\nchmod +x ~/.local/bin/nu_plugin_*\n\n# Ensure ~/.local/bin directory exists and is accessible\nls -ld ~/.local/bin\n\n\n## Integration with Justfile\n\nAdd to justfile for easy access:\n\nmakefile\n# Update installed plugins with full workflow\nupdate-installed-plugins:\n @echo "🔄 Updating installed plugins..."\n @./scripts/update_installed_plugins.nu --verify\n\n# Update specific plugin\nupdate-plugin-from-installed PLUGIN:\n @./scripts/update_installed_plugins.nu --plugin {{PLUGIN}}\n\n# Dry-run before update\ncheck-plugin-updates:\n @./scripts/update_installed_plugins.nu --check\n\n\nThen use:\n\nbash\njust update-installed-plugins\njust update-plugin-from-installed nu_plugin_auth\njust check-plugin-updates\n\n\n## Comparison: Update Scripts\n\n### update_all_plugins.nu\n\n- Purpose: Update Cargo.toml dependencies\n- When to use: Updating Nushell version in cargo files\n- Scope: Changes source files only\n- Output: Modified Cargo.toml files\n- Next step: Must rebuild with just build\n\n### update_installed_plugins.nu ✨ NEW\n\n- Purpose: Update already-installed binaries\n- When to use: Refresh binaries in ~/.local/bin\n- Scope: Full cycle: build → install → register\n- Output: New binaries in ~/.local/bin\n- Includes: Automatic registration with Nushell\n\n### Typical Workflow\n\n1. Update source dependencies\n\n bash\n ./scripts/update_all_plugins.nu 0.108.0\n \n\n2. Rebuild and install\n\n bash\n ./scripts/update_installed_plugins.nu --force --verify\n \n\n3. Restart and test\n\n bash\n exit\n nu -c "plugin list"\n \n\n## Advanced Usage\n\n### Custom Install Directory (Future Enhancement)\n\nCurrently hardcoded to ~/.local/bin. To support custom directory:\n\nbash\n# Future: Would allow\nPLUGIN_INSTALL_DIR=/custom/path ./scripts/update_installed_plugins.nu\n\n\n### Batch Update Multiple Plugins\n\nbash\n# Update in sequence\nfor plugin in auth kms orchestrator; do\n ./scripts/update_installed_plugins.nu --plugin nu_plugin_$plugin\ndone\n\n\n### Verify After Update\n\nbash\n# Update with verification\n./scripts/update_installed_plugins.nu --verify\n\n# Or verify separately\nnu -c "plugin list | format table"\nnu -c "plugin list | each {|p| $\"($p.name): ($p.filename)\" }"\n\n\n## Configuration Files\n\n- Plugin Registry: etc/plugin_registry.toml - Track plugin metadata\n- Common Library: scripts/lib/common_lib.nu - Shared logging functions\n- Build Config: Cargo.toml in each plugin directory\n\n## Support & Issues\n\nFor issues or enhancements:\n\n1. Check troubleshooting section above\n2. Review script output for specific error messages\n3. Run with --check first to preview changes\n4. Check build output: cd nu_plugin_NAME && cargo build --release\n\n## Quick Reference Card\n\nbash\n# DRY RUN (safe, no changes)\n./scripts/update_installed_plugins.nu --check\n\n# UPDATE ALL (interactive confirmation)\n./scripts/update_installed_plugins.nu\n\n# UPDATE WITH VERIFICATION\n./scripts/update_installed_plugins.nu --verify\n\n# UPDATE ONE PLUGIN\n./scripts/update_installed_plugins.nu --plugin nu_plugin_NAME\n\n# FORCE REBUILD\n./scripts/update_installed_plugins.nu --force\n\n# SKIP REGISTRATION\n./scripts/update_installed_plugins.nu --no-register\n\n# THEN RESTART\nexit\n\n\n---\n\nScript Location: scripts/update_installed_plugins.nu\nInstall Directory: ~/.local/bin\nCreated: 2025-10-22\nNushell Version: 0.107.1+