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\n```bash\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\n```bash\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\n```bash\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\n```plaintext\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\n```plaintext\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\n```plaintext\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\n```plaintext\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\n```plaintext\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\n```plaintext\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\n```plaintext\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\n```bash\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\n```bash\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\n```bash\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\n```bash\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\n**Problem**: "Plugin not found or not installed"\n\n**Solution**:\n\n```bash\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\n**Problem**: Build fails during step 5\n\n**Solution**:\n\n```bash\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\n**Problem**: Plugin registers but doesn't work\n\n**Solution**:\n\n```bash\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\n**Problem**: "Permission denied" when trying to execute\n\n**Solution**:\n\n```bash\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\n```makefile\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\n```bash\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\n```bash\n# Future: Would allow\nPLUGIN_INSTALL_DIR=/custom/path ./scripts/update_installed_plugins.nu\n```\n\n### Batch Update Multiple Plugins\n\n```bash\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\n```bash\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\n```bash\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\n**Script Location**: `scripts/update_installed_plugins.nu`\n**Install Directory**: `~/.local/bin`\n**Created**: 2025-10-22\n**Nushell Version**: 0.107.1+