# Provisioning Plugins Usage Guide\n\n## Overview\n\nThree high-performance Nushell plugins have been integrated into the provisioning system to provide **10-50x performance improvements** over\nHTTP-based operations:\n\n- **nu_plugin_auth** - JWT authentication with system keyring integration\n- **nu_plugin_kms** - Multi-backend KMS encryption\n- **nu_plugin_orchestrator** - Local orchestrator operations\n\n## Installation\n\n### Prerequisites\n\n- Nushell 0.107.1 or later\n- All plugins are pre-compiled in `provisioning/core/plugins/nushell-plugins/`\n\n### Quick Install\n\nRun the installation script in a new Nushell session:\n\n```\nnu provisioning/core/plugins/install-and-register.nu\n```\n\nThis will:\n\n1. Copy plugins to `~/.local/share/nushell/plugins/`\n2. Register plugins with Nushell\n3. Verify installation\n\n### Manual Installation\n\nIf the script doesn't work, run these commands:\n\n```\n# Copy plugins\ncp provisioning/core/plugins/nushell-plugins/nu_plugin_auth/target/release/nu_plugin_auth ~/.local/share/nushell/plugins/\ncp provisioning/core/plugins/nushell-plugins/nu_plugin_kms/target/release/nu_plugin_kms ~/.local/share/nushell/plugins/\ncp provisioning/core/plugins/nushell-plugins/nu_plugin_orchestrator/target/release/nu_plugin_orchestrator ~/.local/share/nushell/plugins/\n\nchmod +x ~/.local/share/nushell/plugins/nu_plugin_*\n\n# Register with Nushell (run in a fresh session)\nplugin add ~/.local/share/nushell/plugins/nu_plugin_auth\nplugin add ~/.local/share/nushell/plugins/nu_plugin_kms\nplugin add ~/.local/share/nushell/plugins/nu_plugin_orchestrator\n```\n\n## Usage\n\n### Authentication Plugin\n\n**10x faster than HTTP fallback**\n\n#### Login\n\n```\nprovisioning auth login <username> [password]\n\n# Examples\nprovisioning auth login admin\nprovisioning auth login admin mypassword\nprovisioning auth login --url http://localhost:8081 admin\n```\n\n#### Verify Token\n\n```\nprovisioning auth verify [--local]\n\n# Examples\nprovisioning auth verify\nprovisioning auth verify --local\n```\n\n#### Logout\n\n```\nprovisioning auth logout\n\n# Example\nprovisioning auth logout\n```\n\n#### List Sessions\n\n```\nprovisioning auth sessions [--active]\n\n# Examples\nprovisioning auth sessions\nprovisioning auth sessions --active\n```\n\n### KMS Plugin\n\n**10x faster than HTTP fallback**\n\nSupports multiple backends: RustyVault, Age, AWS KMS, HashiCorp Vault, Cosmian\n\n#### Encrypt Data\n\n```\nprovisioning kms encrypt <data> [--backend <backend>] [--key <key>]\n\n# Examples\nprovisioning kms encrypt "secret-data"\nprovisioning kms encrypt "secret" --backend age\nprovisioning kms encrypt "secret" --backend rustyvault --key my-key\n```\n\n#### Decrypt Data\n\n```\nprovisioning kms decrypt <encrypted_data> [--backend <backend>] [--key <key>]\n\n# Examples\nprovisioning kms decrypt $encrypted_data\nprovisioning kms decrypt $encrypted --backend age\n```\n\n#### KMS Status\n\n```\nprovisioning kms status\n\n# Output shows current backend and availability\n```\n\n#### List Backends\n\n```\nprovisioning kms list-backends\n\n# Shows all available KMS backends\n```\n\n### Orchestrator Plugin\n\n**30x faster than HTTP fallback**\n\nLocal file-based orchestration without network overhead.\n\n#### Check Status\n\n```\nprovisioning orch status [--data-dir <path>]\n\n# Examples\nprovisioning orch status\nprovisioning orch status --data-dir /custom/data\n```\n\n#### List Tasks\n\n```\nprovisioning orch tasks [--status <status>] [--limit <n>] [--data-dir <path>]\n\n# Examples\nprovisioning orch tasks\nprovisioning orch tasks --status pending\nprovisioning orch tasks --status running --limit 10\n```\n\n#### Validate Workflow\n\n```\nprovisioning orch validate <workflow.ncl> [--strict]\n\n# Examples\nprovisioning orch validate workflows/deployment.ncl\nprovisioning orch validate workflows/deployment.ncl --strict\n```\n\n#### Submit Workflow\n\n```\nprovisioning orch submit <workflow.ncl> [--priority <0-100>] [--check]\n\n# Examples\nprovisioning orch submit workflows/deployment.ncl\nprovisioning orch submit workflows/critical.ncl --priority 90\nprovisioning orch submit workflows/test.ncl --check\n```\n\n#### Monitor Task\n\n```\nprovisioning orch monitor <task_id> [--once] [--interval <ms>] [--timeout <s>]\n\n# Examples\nprovisioning orch monitor task-123\nprovisioning orch monitor task-123 --once\nprovisioning orch monitor task-456 --interval 5000 --timeout 600\n```\n\n## Plugin Status\n\nCheck which plugins are installed:\n\n```\nprovisioning plugin status\n\n# Output:\n# Provisioning Plugins Status\n# ============================\n# [OK]  nu_plugin_auth        - JWT authentication with keyring\n# [OK]  nu_plugin_kms         - Multi-backend encryption\n# [OK]  nu_plugin_orchestrator - Local orchestrator (30x faster)\n#\n# All plugins loaded - using native high-performance mode\n```\n\n### Testing Plugins\n\n```\nprovisioning plugin test\n\n# Runs quick tests on all installed plugins\n# Output shows which plugins are responding\n```\n\n### List Registered Plugins\n\n```\nprovisioning plugin list\n\n# Shows all provisioning plugins registered with Nushell\n```\n\n## Performance Comparison\n\n| Operation | With Plugin | HTTP Fallback | Speedup |\n| ----------- | ------------ | -------------- | --------- |\n| Auth verify | ~10 ms | ~50 ms | 5x |\n| Auth login | ~15 ms | ~100 ms | 7x |\n| KMS encrypt | ~5-8 ms | ~50 ms | 10x |\n| KMS decrypt | ~5-8 ms | ~50 ms | 10x |\n| Orch status | ~1-5 ms | ~30 ms | 30x |\n| Orch tasks list | ~2-10 ms | ~50 ms | 25x |\n\n## Graceful Fallback\n\nIf plugins are not installed or fail to load, all commands automatically fall back to HTTP-based operations:\n\n```\n# With plugins installed (fast)\n$ provisioning auth verify\nToken is valid\n\n# Without plugins (slower, but functional)\n$ provisioning auth verify\n[HTTP fallback mode]\nToken is valid (slower)\n```\n\nThis ensures the system remains functional even if plugins aren't available.\n\n## Troubleshooting\n\n### Plugins not found after installation\n\nMake sure you:\n\n1. Have a fresh Nushell session\n2. Ran `plugin add` for all three plugins\n3. The plugin files are executable: `chmod +x ~/.local/share/nushell/plugins/nu_plugin_*`\n\n### "Command not found" errors\n\nIf you see "command not found" when running `provisioning auth login`, the auth plugin is not loaded. Run:\n\n```\nplugin list | grep nu_plugin\n```\n\nIf you don't see the plugins, register them:\n\n```\nplugin add ~/.local/share/nushell/plugins/nu_plugin_auth\nplugin add ~/.local/share/nushell/plugins/nu_plugin_kms\nplugin add ~/.local/share/nushell/plugins/nu_plugin_orchestrator\n```\n\n### Plugins crash or are unresponsive\n\nCheck the plugin logs:\n\n```\nprovisioning plugin test\n```\n\nIf a plugin fails, the system will automatically fall back to HTTP mode.\n\n## Integration with Provisioning CLI\n\nAll plugin commands are integrated into the main provisioning CLI:\n\n```\n# Shortcuts available\nprovisioning auth login admin        # Full command\nprovisioning login admin             # Alias\n\nprovisioning kms encrypt secret      # Full command\nprovisioning encrypt secret          # Alias\n\nprovisioning orch status             # Full command\nprovisioning orch-status             # Alias\n```\n\n## Advanced Configuration\n\n### Custom Data Directory\n\nFor orchestrator operations, specify custom data directory:\n\n```\nprovisioning orch status --data-dir /custom/orchestrator/data\nprovisioning orch tasks --data-dir /custom/orchestrator/data\n```\n\n### Custom Auth URL\n\nFor auth operations with custom endpoint:\n\n```\nprovisioning auth login admin --url http://custom-auth-server:8081\nprovisioning auth verify --url http://custom-auth-server:8081\n```\n\n### KMS Backend Selection\n\nSpecify which KMS backend to use:\n\n```\n# Use Age encryption\nprovisioning kms encrypt "data" --backend age\n\n# Use RustyVault\nprovisioning kms encrypt "data" --backend rustyvault\n\n# Use AWS KMS\nprovisioning kms encrypt "data" --backend aws\n\n# Decrypt with same backend\nprovisioning kms decrypt $encrypted --backend age\n```\n\n## Building Plugins from Source\n\nIf you need to rebuild plugins:\n\n```\ncd provisioning/core/plugins/nushell-plugins\n\n# Build auth plugin\ncd nu_plugin_auth && cargo build --release && cd ..\n\n# Build KMS plugin\ncd nu_plugin_kms && cargo build --release && cd ..\n\n# Build orchestrator plugin\ncd nu_plugin_orchestrator && cargo build --release && cd ..\n\n# Run install script\ncd ../..\nnu install-and-register.nu\n```\n\n## Architecture\n\nThe plugins follow Nushell's plugin protocol:\n\n1. **Plugin Binary**: Compiled Rust binary in `target/release/`\n2. **Registration**: Via `plugin add` command\n3. **IPC**: Communication via Nushell's JSON protocol\n4. **Fallback**: HTTP API fallback if plugins unavailable\n\n## Security Notes\n\n- **Auth tokens** are stored in system keyring (Keychain/Credential Manager/Secret Service)\n- **KMS keys** are protected by the selected backend's security\n- **Orchestrator** operations are local file-based (no network exposure)\n- All operations are logged in provisioning audit logs\n\n## Support\n\nFor issues or questions:\n\n1. Check plugin status: `provisioning plugin test`\n2. Review logs: `provisioning logs` or `/var/log/provisioning/`\n3. Test HTTP fallback by temporarily unregistering plugins\n4. Contact the provisioning team with plugin test output
