Nushell Plugin Integration Guide

Version: 1.0.0 Last Updated: 2025-10-09 Target Audience: Developers, DevOps Engineers, System Administrators

Table of Contents

1. Overview
2. Why Native Plugins?
3. Prerequisites
4. Installation
5. Quick Start (5 Minutes)
6. Authentication Plugin (nu_plugin_auth)
7. KMS Plugin (nu_plugin_kms)
8. Orchestrator Plugin (nu_plugin_orchestrator)
9. Integration Examples
10. Best Practices
11. Troubleshooting
12. Migration Guide
13. Advanced Configuration
14. Security Considerations
15. FAQ

Overview

The Provisioning Platform provides three native Nushell plugins that dramatically improve performance and user experience compared to traditional HTTP API calls:

Architecture Benefits

Traditional HTTP Flow:
User Command → HTTP Request → Network → Server Processing → Response → Parse JSON
  Total: ~50-100ms per operation

Plugin Flow:
User Command → Direct Rust Function Call → Return Nushell Data Structure
  Total: ~1-10ms per operation

Key Features

✅ Performance: 10-50x faster than HTTP API ✅ Type Safety: Full Nushell type system integration ✅ Pipeline Support: Native Nushell data structures ✅ Offline Capability: KMS and orchestrator work without network ✅ OS Integration: Native keyring for secure token storage ✅ Graceful Fallback: HTTP still available if plugins not installed

Why Native Plugins?

Performance Comparison

Real-world benchmarks from production workload:

Use Case: Batch Processing

Scenario: Encrypt 100 configuration files

# HTTP API approach
ls configs/*.yaml | each { |file|
    http post http://localhost:9998/encrypt { data: (open $file) }
} | save encrypted/
# Total time: ~5 seconds (50ms × 100)

# Plugin approach
ls configs/*.yaml | each { |file|
    kms encrypt (open $file) --backend rustyvault
} | save encrypted/
# Total time: ~0.5 seconds (5ms × 100)
# Result: 10x faster

Developer Experience Benefits

1. Native Nushell Integration

# HTTP: Parse JSON, check status codes
let result = http post http://localhost:9998/encrypt { data: "secret" }
if $result.status == "success" {
    $result.encrypted
} else {
    error make { msg: $result.error }
}

# Plugin: Direct return values
kms encrypt "secret"
# Returns encrypted string directly, errors use Nushell's error system

2. Pipeline Friendly

# HTTP: Requires wrapping, JSON parsing
["secret1", "secret2"] | each { |s|
    (http post http://localhost:9998/encrypt { data: $s }).encrypted
}

# Plugin: Natural pipeline flow
["secret1", "secret2"] | each { |s| kms encrypt $s }

3. Tab Completion

# All plugin commands have full tab completion
kms <TAB>
# → encrypt, decrypt, generate-key, status, backends

kms encrypt --<TAB>
# → --backend, --key, --context

Prerequisites

Required Software

Optional Dependencies

Platform Support

Installation

Step 1: Clone or Navigate to Plugin Directory

cd /Users/Akasha/project-provisioning/provisioning/core/plugins/nushell-plugins

Step 2: Build All Plugins

# Build in release mode (optimized for performance)
cargo build --release --all

# Or build individually
cargo build --release -p nu_plugin_auth
cargo build --release -p nu_plugin_kms
cargo build --release -p nu_plugin_orchestrator

Expected output:

   Compiling nu_plugin_auth v0.1.0
   Compiling nu_plugin_kms v0.1.0
   Compiling nu_plugin_orchestrator v0.1.0
    Finished release [optimized] target(s) in 2m 15s

Step 3: Register Plugins with Nushell

# Register all three plugins
plugin add target/release/nu_plugin_auth
plugin add target/release/nu_plugin_kms
plugin add target/release/nu_plugin_orchestrator

# On macOS, full paths:
plugin add $PWD/target/release/nu_plugin_auth
plugin add $PWD/target/release/nu_plugin_kms
plugin add $PWD/target/release/nu_plugin_orchestrator

Step 4: Verify Installation

# List registered plugins
plugin list | where name =~ "auth|kms|orch"

# Test each plugin
auth --help
kms --help
orch --help

Expected output:

╭───┬─────────────────────────┬─────────┬───────────────────────────────────╮
│ # │          name           │ version │           filename                │
├───┼─────────────────────────┼─────────┼───────────────────────────────────┤
│ 0 │ nu_plugin_auth          │ 0.1.0   │ .../nu_plugin_auth                │
│ 1 │ nu_plugin_kms           │ 0.1.0   │ .../nu_plugin_kms                 │
│ 2 │ nu_plugin_orchestrator  │ 0.1.0   │ .../nu_plugin_orchestrator        │
╰───┴─────────────────────────┴─────────┴───────────────────────────────────╯

Step 5: Configure Environment (Optional)

# Add to ~/.config/nushell/env.nu
$env.RUSTYVAULT_ADDR = "http://localhost:8200"
$env.RUSTYVAULT_TOKEN = "your-vault-token"
$env.CONTROL_CENTER_URL = "http://localhost:3000"
$env.ORCHESTRATOR_DATA_DIR = "/opt/orchestrator/data"

Quick Start (5 Minutes)

1. Authentication Workflow

# Login (password prompted securely)
auth login admin
# ✓ Login successful
# User: admin
# Role: Admin
# Expires: 2025-10-09T14:30:00Z

# Verify session
auth verify
# {
#   "active": true,
#   "user": "admin",
#   "role": "Admin",
#   "expires_at": "2025-10-09T14:30:00Z"
# }

# Enroll in MFA (optional but recommended)
auth mfa enroll totp
# QR code displayed, save backup codes

# Verify MFA
auth mfa verify --code 123456
# ✓ MFA verification successful

# Logout
auth logout
# ✓ Logged out successfully

2. KMS Operations

# Encrypt data
kms encrypt "my secret data"
# vault:v1:8GawgGuP...

# Decrypt data
kms decrypt "vault:v1:8GawgGuP..."
# my secret data

# Check available backends
kms status
# {
#   "backend": "rustyvault",
#   "status": "healthy",
#   "url": "http://localhost:8200"
# }

# Encrypt with specific backend
kms encrypt "data" --backend age --key age1xxxxxxx

3. Orchestrator Operations

# Check orchestrator status (no HTTP call)
orch status
# {
#   "active_tasks": 5,
#   "completed_tasks": 120,
#   "health": "healthy"
# }

# Validate workflow
orch validate workflows/deploy.k
# {
#   "valid": true,
#   "workflow": { "name": "deploy_k8s", "operations": 5 }
# }

# List running tasks
orch tasks --status running
# [ { "task_id": "task_123", "name": "deploy_k8s", "progress": 45 } ]

4. Combined Workflow

# Complete authenticated deployment pipeline
auth login admin
    | if $in.success { auth verify }
    | if $in.active {
        orch validate workflows/production.k
            | if $in.valid {
                kms encrypt (open secrets.yaml | to json)
                    | save production-secrets.enc
              }
      }
# ✓ Pipeline completed successfully

Authentication Plugin (nu_plugin_auth)

The authentication plugin manages JWT-based authentication, MFA enrollment/verification, and session management with OS-native keyring integration.

Available Commands

Command Reference

auth login <username> [password]

Login to provisioning platform and store JWT tokens securely in OS keyring.

Arguments:

• username (required): Username for authentication
• password (optional): Password (prompted if not provided)

Flags:

• --url <url>: Control center URL (default: http://localhost:3000)
• --password <password>: Password (alternative to positional argument)

Examples:

# Interactive password prompt (recommended)
auth login admin
# Password: ••••••••
# ✓ Login successful
# User: admin
# Role: Admin
# Expires: 2025-10-09T14:30:00Z

# Password in command (not recommended for production)
auth login admin mypassword

# Custom control center URL
auth login admin --url https://control-center.example.com

# Pipeline usage
let creds = { username: "admin", password: (input --suppress-output "Password: ") }
auth login $creds.username $creds.password

Token Storage Locations:

• macOS: Keychain Access (login keychain)
• Linux: Secret Service API (gnome-keyring, kwallet)
• Windows: Windows Credential Manager

Security Notes:

• Tokens encrypted at rest by OS
• Requires user authentication to access (macOS Touch ID, Linux password)
• Never stored in plain text files

auth logout

Logout from current session and remove stored tokens from keyring.

Examples:

# Simple logout
auth logout
# ✓ Logged out successfully

# Conditional logout
if (auth verify | get active) {
    auth logout
    echo "Session terminated"
}

# Logout all sessions (requires admin role)
auth sessions | each { |sess|
    auth logout --session-id $sess.session_id
}

auth verify

Verify current session status and check token validity.

Returns:

• active (bool): Whether session is active
• user (string): Username
• role (string): User role
• expires_at (datetime): Token expiration
• mfa_verified (bool): MFA verification status

Examples:

# Check if logged in
auth verify
# {
#   "active": true,
#   "user": "admin",
#   "role": "Admin",
#   "expires_at": "2025-10-09T14:30:00Z",
#   "mfa_verified": true
# }

# Pipeline usage
if (auth verify | get active) {
    echo "✓ Authenticated"
} else {
    auth login admin
}

# Check expiration
let session = auth verify
if ($session.expires_at | into datetime) < (date now) {
    echo "Session expired, re-authenticating..."
    auth login $session.user
}

auth sessions

List all active sessions for current user.

Examples:

# List all sessions
auth sessions
# [
#   {
#     "session_id": "sess_abc123",
#     "created_at": "2025-10-09T12:00:00Z",
#     "expires_at": "2025-10-09T14:30:00Z",
#     "ip_address": "192.168.1.100",
#     "user_agent": "nushell/0.107.1"
#   }
# ]

# Filter recent sessions (last hour)
auth sessions | where created_at > ((date now) - 1hr)

# Find sessions by IP
auth sessions | where ip_address =~ "192.168"

# Count active sessions
auth sessions | length

auth mfa enroll <type>

Enroll in Multi-Factor Authentication (TOTP or WebAuthn).

Arguments:

• type (required): MFA type (totp or webauthn)

TOTP Enrollment:

auth mfa enroll totp
# ✓ TOTP enrollment initiated
#
# Scan this QR code with your authenticator app:
#
#   ████ ▄▄▄▄▄ █▀█ █▄▀▀▀▄ ▄▄▄▄▄ ████
#   ████ █   █ █▀▀▀█▄ ▀▀█ █   █ ████
#   ████ █▄▄▄█ █ █▀▄ ▀▄▄█ █▄▄▄█ ████
#   (QR code continues...)
#
# Or enter manually:
# Secret: JBSWY3DPEHPK3PXP
# URL: otpauth://totp/Provisioning:admin?secret=JBSWY3DPEHPK3PXP&issuer=Provisioning
#
# Backup codes (save securely):
# 1. ABCD-EFGH-IJKL
# 2. MNOP-QRST-UVWX
# 3. YZAB-CDEF-GHIJ
# (8 more codes...)

WebAuthn Enrollment:

auth mfa enroll webauthn
# ✓ WebAuthn enrollment initiated
#
# Insert your security key and touch the button...
# (waiting for device interaction)
#
# ✓ Security key registered successfully
# Device: YubiKey 5 NFC
# Created: 2025-10-09T13:00:00Z

Supported Authenticator Apps:

• Google Authenticator
• Microsoft Authenticator
• Authy
• 1Password
• Bitwarden

Supported Hardware Keys:

• YubiKey (all models)
• Titan Security Key
• Feitian ePass
• macOS Touch ID
• Windows Hello

auth mfa verify --code <code>

Verify MFA code (TOTP or backup code).

Flags:

• --code <code> (required): 6-digit TOTP code or backup code

Examples:

# Verify TOTP code
auth mfa verify --code 123456
# ✓ MFA verification successful

# Verify backup code
auth mfa verify --code ABCD-EFGH-IJKL
# ✓ MFA verification successful (backup code used)
# Warning: This backup code cannot be used again

# Pipeline usage
let code = input "MFA code: "
auth mfa verify --code $code

Error Cases:

# Invalid code
auth mfa verify --code 999999
# Error: Invalid MFA code
# → Verify time synchronization on your device

# Rate limited
auth mfa verify --code 123456
# Error: Too many failed attempts
# → Wait 5 minutes before trying again

# No MFA enrolled
auth mfa verify --code 123456
# Error: MFA not enrolled for this user
# → Run: auth mfa enroll totp

Environment Variables

Troubleshooting Authentication

“No active session”

# Solution: Login first
auth login <username>

“Keyring error” (macOS)

# Check Keychain Access permissions
# System Preferences → Security & Privacy → Privacy → Full Disk Access
# Add: /Applications/Nushell.app (or /usr/local/bin/nu)

# Or grant access manually
security unlock-keychain ~/Library/Keychains/login.keychain-db

“Keyring error” (Linux)

# Install keyring service
sudo apt install gnome-keyring      # Ubuntu/Debian
sudo dnf install gnome-keyring      # Fedora
sudo pacman -S gnome-keyring        # Arch

# Or use KWallet (KDE)
sudo apt install kwalletmanager

# Start keyring daemon
eval $(gnome-keyring-daemon --start)
export $(gnome-keyring-daemon --start --components=secrets)

“MFA verification failed”

# Check time synchronization (TOTP requires accurate time)
# macOS:
sudo sntp -sS time.apple.com

# Linux:
sudo ntpdate pool.ntp.org
# Or
sudo systemctl restart systemd-timesyncd

# Use backup code if TOTP not working
auth mfa verify --code ABCD-EFGH-IJKL

KMS Plugin (nu_plugin_kms)

The KMS plugin provides high-performance encryption and decryption using multiple backend providers.

Supported Backends

Backend Selection Guide

Choose rustyvault when:

• ✅ Running in production with high throughput requirements
• ✅ Need ~5ms encryption/decryption latency
• ✅ Have RustyVault server deployed
• ✅ Require key rotation and versioning

Choose age when:

• ✅ Developing locally without external dependencies
• ✅ Need simple file encryption
• ✅ Want ~3ms latency
• ❌ Don’t need centralized key management

Choose cosmian when:

• ✅ Using Cosmian KMS service
• ✅ Need cloud-based key management
• ⚠️ Can accept ~30ms latency

Choose aws when:

• ✅ Deployed on AWS infrastructure
• ✅ Using AWS IAM for access control
• ✅ Need AWS KMS integration
• ⚠️ Can accept ~50ms latency

Choose vault when:

• ✅ Using HashiCorp Vault enterprise
• ✅ Need advanced policy management
• ✅ Require audit trails
• ⚠️ Can accept ~40ms latency

Available Commands

Command Reference

kms encrypt <data> [--backend <backend>]

Encrypt data using specified KMS backend.

Arguments:

• data (required): Data to encrypt (string or binary)

Flags:

• --backend <backend>: KMS backend (rustyvault, age, cosmian, aws, vault)
• --key <key>: Key ID or recipient (backend-specific)
• --context <context>: Additional authenticated data (AAD)

Examples:

# Auto-detect backend from environment
kms encrypt "secret configuration data"
# vault:v1:8GawgGuP+emDKX5q...

# RustyVault backend
kms encrypt "data" --backend rustyvault --key provisioning-main
# vault:v1:abc123def456...

# Age backend (local encryption)
kms encrypt "data" --backend age --key age1xxxxxxxxx
# -----BEGIN AGE ENCRYPTED FILE-----
# YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+...
# -----END AGE ENCRYPTED FILE-----

# AWS KMS
kms encrypt "data" --backend aws --key alias/provisioning
# AQICAHhwbGF0Zm9ybS1wcm92aXNpb25p...

# With context (AAD for additional security)
kms encrypt "data" --backend rustyvault --key provisioning-main --context "user=admin,env=production"

# Encrypt file contents
kms encrypt (open config.yaml) --backend rustyvault | save config.yaml.enc

# Encrypt multiple files
ls configs/*.yaml | each { |file|
    kms encrypt (open $file.name) --backend age
        | save $"encrypted/($file.name).enc"
}

Output Formats:

• RustyVault: vault:v1:base64_ciphertext
• Age: -----BEGIN AGE ENCRYPTED FILE-----...-----END AGE ENCRYPTED FILE-----
• AWS: base64_aws_kms_ciphertext
• Cosmian: cosmian:v1:base64_ciphertext

kms decrypt <encrypted> [--backend <backend>]

Decrypt KMS-encrypted data.

Arguments:

• encrypted (required): Encrypted data (detects format automatically)

Flags:

• --backend <backend>: KMS backend (auto-detected from format if not specified)
• --context <context>: Additional authenticated data (must match encryption context)

Examples:

# Auto-detect backend from format
kms decrypt "vault:v1:8GawgGuP..."
# secret configuration data

# Explicit backend
kms decrypt "vault:v1:abc123..." --backend rustyvault

# Age decryption
kms decrypt "-----BEGIN AGE ENCRYPTED FILE-----..."
# (uses AGE_IDENTITY from environment)

# With context (must match encryption context)
kms decrypt "vault:v1:abc123..." --context "user=admin,env=production"

# Decrypt file
kms decrypt (open config.yaml.enc) | save config.yaml

# Decrypt multiple files
ls encrypted/*.enc | each { |file|
    kms decrypt (open $file.name)
        | save $"configs/(($file.name | path basename) | str replace '.enc' '')"
}

# Pipeline decryption
open secrets.json
    | get database_password_enc
    | kms decrypt
    | str trim
    | psql --dbname mydb --password

Error Cases:

# Invalid ciphertext
kms decrypt "invalid_data"
# Error: Invalid ciphertext format
# → Verify data was encrypted with KMS

# Context mismatch
kms decrypt "vault:v1:abc..." --context "wrong=context"
# Error: Authentication failed (AAD mismatch)
# → Verify encryption context matches

# Backend unavailable
kms decrypt "vault:v1:abc..."
# Error: Failed to connect to RustyVault at http://localhost:8200
# → Check RustyVault is running: curl http://localhost:8200/v1/sys/health

kms generate-key [--spec <spec>]

Generate data encryption key (DEK) using KMS envelope encryption.

Flags:

• --spec <spec>: Key specification (AES128 or AES256, default: AES256)
• --backend <backend>: KMS backend

Examples:

# Generate AES-256 key
kms generate-key
# {
#   "plaintext": "rKz3N8xPq...",  # base64-encoded key
#   "ciphertext": "vault:v1:...",  # encrypted DEK
#   "spec": "AES256"
# }

# Generate AES-128 key
kms generate-key --spec AES128

# Use in envelope encryption pattern
let dek = kms generate-key
let encrypted_data = ($data | openssl enc -aes-256-cbc -K $dek.plaintext)
{
    data: $encrypted_data,
    encrypted_key: $dek.ciphertext
} | save secure_data.json

# Later, decrypt:
let envelope = open secure_data.json
let dek = kms decrypt $envelope.encrypted_key
$envelope.data | openssl enc -d -aes-256-cbc -K $dek

Use Cases:

• Envelope encryption (encrypt large data locally, protect DEK with KMS)
• Database field encryption
• File encryption with key wrapping

kms status

Show KMS backend status, configuration, and health.

Examples:

# Show current backend status
kms status
# {
#   "backend": "rustyvault",
#   "status": "healthy",
#   "url": "http://localhost:8200",
#   "mount_point": "transit",
#   "version": "0.1.0",
#   "latency_ms": 5
# }

# Check all configured backends
kms status --all
# [
#   { "backend": "rustyvault", "status": "healthy", ... },
#   { "backend": "age", "status": "available", ... },
#   { "backend": "aws", "status": "unavailable", "error": "..." }
# ]

# Filter to specific backend
kms status | where backend == "rustyvault"

# Health check in automation
if (kms status | get status) == "healthy" {
    echo "✓ KMS operational"
} else {
    error make { msg: "KMS unhealthy" }
}

Backend Configuration

RustyVault Backend

# Environment variables
export RUSTYVAULT_ADDR="http://localhost:8200"
export RUSTYVAULT_TOKEN="hvs.xxxxxxxxxxxxx"
export RUSTYVAULT_MOUNT="transit"  # Transit engine mount point
export RUSTYVAULT_KEY="provisioning-main"  # Default key name

# Usage
kms encrypt "data" --backend rustyvault --key provisioning-main

Setup RustyVault:

# Start RustyVault
rustyvault server -dev

# Enable transit engine
rustyvault secrets enable transit

# Create encryption key
rustyvault write -f transit/keys/provisioning-main

Age Backend

# Generate Age keypair
age-keygen -o ~/.age/key.txt

# Environment variables
export AGE_IDENTITY="$HOME/.age/key.txt"  # Private key
export AGE_RECIPIENT="age1xxxxxxxxx"      # Public key (from key.txt)

# Usage
kms encrypt "data" --backend age
kms decrypt (open file.enc) --backend age

AWS KMS Backend

# AWS credentials
export AWS_REGION="us-east-1"
export AWS_ACCESS_KEY_ID="AKIAXXXXX"
export AWS_SECRET_ACCESS_KEY="xxxxx"

# KMS configuration
export AWS_KMS_KEY_ID="alias/provisioning"

# Usage
kms encrypt "data" --backend aws --key alias/provisioning

Setup AWS KMS:

# Create KMS key
aws kms create-key --description "Provisioning Platform"

# Create alias
aws kms create-alias --alias-name alias/provisioning --target-key-id <key-id>

# Grant permissions
aws kms create-grant --key-id <key-id> --grantee-principal <role-arn> \
    --operations Encrypt Decrypt GenerateDataKey

Cosmian Backend

# Cosmian KMS configuration
export KMS_HTTP_URL="http://localhost:9998"
export KMS_HTTP_BACKEND="cosmian"
export COSMIAN_API_KEY="your-api-key"

# Usage
kms encrypt "data" --backend cosmian

Vault Backend (HashiCorp)

# Vault configuration
export VAULT_ADDR="https://vault.example.com:8200"
export VAULT_TOKEN="hvs.xxxxxxxxxxxxx"
export VAULT_MOUNT="transit"
export VAULT_KEY="provisioning"

# Usage
kms encrypt "data" --backend vault --key provisioning

Performance Benchmarks

Test Setup:

• Data size: 1KB
• Iterations: 1000
• Hardware: Apple M1, 16GB RAM
• Network: localhost

Results:

Scaling Test (1000 operations):

# RustyVault: ~5 seconds
0..1000 | each { |_| kms encrypt "data" --backend rustyvault } | length
# Age: ~3 seconds
0..1000 | each { |_| kms encrypt "data" --backend age } | length

Troubleshooting KMS

“RustyVault connection failed”

# Check RustyVault is running
curl http://localhost:8200/v1/sys/health
# Expected: { "initialized": true, "sealed": false }

# Check environment
echo $env.RUSTYVAULT_ADDR
echo $env.RUSTYVAULT_TOKEN

# Test authentication
curl -H "X-Vault-Token: $RUSTYVAULT_TOKEN" $RUSTYVAULT_ADDR/v1/sys/health

“Age encryption failed”

# Check Age keys exist
ls -la ~/.age/
# Expected: key.txt

# Verify key format
cat ~/.age/key.txt | head -1
# Expected: # created: <date>
# Line 2: # public key: age1xxxxx
# Line 3: AGE-SECRET-KEY-xxxxx

# Extract public key
export AGE_RECIPIENT=$(grep "public key:" ~/.age/key.txt | cut -d: -f2 | tr -d ' ')
echo $AGE_RECIPIENT

“AWS KMS access denied”

# Verify AWS credentials
aws sts get-caller-identity
# Expected: Account, UserId, Arn

# Check KMS key permissions
aws kms describe-key --key-id alias/provisioning

# Test encryption
aws kms encrypt --key-id alias/provisioning --plaintext "test"

Orchestrator Plugin (nu_plugin_orchestrator)

The orchestrator plugin provides direct file-based access to orchestrator state, eliminating HTTP overhead for status queries and validation.

Available Commands

Command Reference

orch status [--data-dir <dir>]

Get orchestrator status from local files (no HTTP, ~1ms latency).

Flags:

• --data-dir <dir>: Data directory (default from ORCHESTRATOR_DATA_DIR)

Examples:

# Default data directory
orch status
# {
#   "active_tasks": 5,
#   "completed_tasks": 120,
#   "failed_tasks": 2,
#   "pending_tasks": 3,
#   "uptime": "2d 4h 15m",
#   "health": "healthy"
# }

# Custom data directory
orch status --data-dir /opt/orchestrator/data

# Monitor in loop
while true {
    clear
    orch status | table
    sleep 5sec
}

# Alert on failures
if (orch status | get failed_tasks) > 0 {
    echo "⚠️ Failed tasks detected!"
}

orch validate <workflow.k> [--strict]

Validate workflow KCL file syntax and structure.

Arguments:

• workflow.k (required): Path to KCL workflow file

Flags:

• --strict: Enable strict validation (warnings as errors)

Examples:

# Basic validation
orch validate workflows/deploy.k
# {
#   "valid": true,
#   "workflow": {
#     "name": "deploy_k8s_cluster",
#     "version": "1.0.0",
#     "operations": 5
#   },
#   "warnings": [],
#   "errors": []
# }

# Strict mode (warnings cause failure)
orch validate workflows/deploy.k --strict
# Error: Validation failed with warnings:
# - Operation 'create_servers': Missing retry_policy
# - Operation 'install_k8s': Resource limits not specified

# Validate all workflows
ls workflows/*.k | each { |file|
    let result = orch validate $file.name
    if $result.valid {
        echo $"✓ ($file.name)"
    } else {
        echo $"✗ ($file.name): ($result.errors | str join ', ')"
    }
}

# CI/CD validation
try {
    orch validate workflow.k --strict
    echo "✓ Validation passed"
} catch {
    echo "✗ Validation failed"
    exit 1
}

Validation Checks:

• ✅ KCL syntax correctness
• ✅ Required fields present (name, version, operations)
• ✅ Dependency graph valid (no cycles)
• ✅ Resource limits within bounds
• ✅ Provider configurations valid
• ✅ Operation types supported
• ⚠️ Optional: Retry policies defined
• ⚠️ Optional: Resource limits specified

orch tasks [--status <status>] [--limit <n>]

List orchestrator tasks from local state.

Flags:

• --status <status>: Filter by status (pending, running, completed, failed)
• --limit <n>: Limit results (default: 100)
• --data-dir <dir>: Data directory

Examples:

# All tasks (last 100)
orch tasks
# [
#   {
#     "task_id": "task_abc123",
#     "name": "deploy_kubernetes",
#     "status": "running",
#     "priority": 5,
#     "created_at": "2025-10-09T12:00:00Z",
#     "progress": 45
#   }
# ]

# Running tasks only
orch tasks --status running

# Failed tasks (last 10)
orch tasks --status failed --limit 10

# Pending high-priority tasks
orch tasks --status pending | where priority > 7

# Monitor active tasks
watch {
    orch tasks --status running
        | select name progress updated_at
        | table
}

# Count tasks by status
orch tasks | group-by status | each { |group|
    { status: $group.0, count: ($group.1 | length) }
}

Environment Variables

Performance Comparison

Use Case: CI/CD Pipeline

# HTTP approach (slow)
http get http://localhost:9090/tasks --status running
    | each { |task| http get $"http://localhost:9090/tasks/($task.id)" }
# Total: ~500ms for 10 tasks

# Plugin approach (fast)
orch tasks --status running
# Total: ~5ms for 10 tasks
# Result: 100x faster

Troubleshooting Orchestrator

“Failed to read status”

# Check data directory exists
ls -la provisioning/platform/orchestrator/data/

# Create if missing
mkdir -p provisioning/platform/orchestrator/data

# Check permissions (must be readable)
chmod 755 provisioning/platform/orchestrator/data

“Workflow validation failed”

# Use strict mode for detailed errors
orch validate workflows/deploy.k --strict

# Check KCL syntax manually
kcl fmt workflows/deploy.k
kcl run workflows/deploy.k

“No tasks found”

# Check orchestrator running
ps aux | grep orchestrator

# Start orchestrator if not running
cd provisioning/platform/orchestrator
./scripts/start-orchestrator.nu --background

# Check task files
ls provisioning/platform/orchestrator/data/tasks/

Integration Examples

Example 1: Complete Authenticated Deployment

Full workflow with authentication, secrets, and deployment:

# Step 1: Login with MFA
auth login admin
auth mfa verify --code (input "MFA code: ")

# Step 2: Verify orchestrator health
if (orch status | get health) != "healthy" {
    error make { msg: "Orchestrator unhealthy" }
}

# Step 3: Validate deployment workflow
let validation = orch validate workflows/production-deploy.k --strict
if not $validation.valid {
    error make { msg: $"Validation failed: ($validation.errors)" }
}

# Step 4: Encrypt production secrets
let secrets = open secrets/production.yaml
kms encrypt ($secrets | to json) --backend rustyvault --key prod-main
    | save secrets/production.enc

# Step 5: Submit deployment
provisioning cluster create production --check

# Step 6: Monitor progress
while (orch tasks --status running | length) > 0 {
    orch tasks --status running
        | select name progress updated_at
        | table
    sleep 10sec
}

echo "✓ Deployment complete"

Example 2: Batch Secret Rotation

Rotate all secrets in multiple environments:

# Rotate database passwords
["dev", "staging", "production"] | each { |env|
    # Generate new password
    let new_password = (openssl rand -base64 32)

    # Encrypt with environment-specific key
    let encrypted = kms encrypt $new_password --backend rustyvault --key $"($env)-main"

    # Save encrypted password
    {
        environment: $env,
        password_enc: $encrypted,
        rotated_at: (date now | format date "%Y-%m-%d %H:%M:%S")
    } | save $"secrets/db-password-($env).json"

    echo $"✓ Rotated password for ($env)"
}

Example 3: Multi-Environment Deployment

Deploy to multiple environments with validation:

# Define environments
let environments = [
    { name: "dev", validate: "basic" },
    { name: "staging", validate: "strict" },
    { name: "production", validate: "strict", mfa_required: true }
]

# Deploy to each environment
$environments | each { |env|
    echo $"Deploying to ($env.name)..."

    # Authenticate if production
    if $env.mfa_required? {
        if not (auth verify | get mfa_verified) {
            auth mfa verify --code (input $"MFA code for ($env.name): ")
        }
    }

    # Validate workflow
    let validation = if $env.validate == "strict" {
        orch validate $"workflows/($env.name)-deploy.k" --strict
    } else {
        orch validate $"workflows/($env.name)-deploy.k"
    }

    if not $validation.valid {
        echo $"✗ Validation failed for ($env.name)"
        continue
    }

    # Decrypt secrets
    let secrets = kms decrypt (open $"secrets/($env.name).enc")

    # Deploy
    provisioning cluster create $env.name

    echo $"✓ Deployed to ($env.name)"
}

Example 4: Automated Backup and Encryption

Backup configuration files with encryption:

# Backup script
let backup_dir = $"backups/(date now | format date "%Y%m%d-%H%M%S")"
mkdir $backup_dir

# Backup and encrypt configs
ls configs/**/*.yaml | each { |file|
    let encrypted = kms encrypt (open $file.name) --backend age
    let backup_path = $"($backup_dir)/($file.name | path basename).enc"
    $encrypted | save $backup_path
    echo $"✓ Backed up ($file.name)"
}

# Create manifest
{
    backup_date: (date now),
    files: (ls $"($backup_dir)/*.enc" | length),
    backend: "age"
} | save $"($backup_dir)/manifest.json"

echo $"✓ Backup complete: ($backup_dir)"

Example 5: Health Monitoring Dashboard

Real-time health monitoring:

# Health dashboard
while true {
    clear

    # Header
    echo "=== Provisioning Platform Health Dashboard ==="
    echo $"Updated: (date now | format date "%Y-%m-%d %H:%M:%S")"
    echo ""

    # Authentication status
    let auth_status = try { auth verify } catch { { active: false } }
    echo $"Auth: (if $auth_status.active { '✓ Active' } else { '✗ Inactive' })"

    # KMS status
    let kms_health = kms status
    echo $"KMS: (if $kms_health.status == 'healthy' { '✓ Healthy' } else { '✗ Unhealthy' })"

    # Orchestrator status
    let orch_health = orch status
    echo $"Orchestrator: (if $orch_health.health == 'healthy' { '✓ Healthy' } else { '✗ Unhealthy' })"
    echo $"Active Tasks: ($orch_health.active_tasks)"
    echo $"Failed Tasks: ($orch_health.failed_tasks)"

    # Task summary
    echo ""
    echo "=== Running Tasks ==="
    orch tasks --status running
        | select name progress updated_at
        | table

    sleep 10sec
}

Best Practices

When to Use Plugins vs HTTP

✅ Use Plugins When:

• Performance is critical (high-frequency operations)
• Working in pipelines (Nushell data structures)
• Need offline capability (KMS, orchestrator local ops)
• Building automation scripts
• CI/CD pipelines

Use HTTP When:

• Calling from external systems (not Nushell)
• Need consistent REST API interface
• Cross-language integration
• Web UI backend

Performance Optimization

1. Batch Operations

# ❌ Slow: Individual HTTP calls in loop
ls configs/*.yaml | each { |file|
    http post http://localhost:9998/encrypt { data: (open $file.name) }
}
# Total: ~5 seconds (50ms × 100)

# ✅ Fast: Plugin in pipeline
ls configs/*.yaml | each { |file|
    kms encrypt (open $file.name)
}
# Total: ~0.5 seconds (5ms × 100)

2. Parallel Processing

# Process multiple operations in parallel
ls configs/*.yaml
    | par-each { |file|
        kms encrypt (open $file.name) | save $"encrypted/($file.name).enc"
    }

3. Caching Session State

# Cache auth verification
let $auth_cache = auth verify
if $auth_cache.active {
    # Use cached result instead of repeated calls
    echo $"Authenticated as ($auth_cache.user)"
}

Error Handling

Graceful Degradation:

# Try plugin, fallback to HTTP if unavailable
def kms_encrypt [data: string] {
    try {
        kms encrypt $data
    } catch {
        http post http://localhost:9998/encrypt { data: $data } | get encrypted
    }
}

Comprehensive Error Handling:

# Handle all error cases
def safe_deployment [] {
    # Check authentication
    let auth_status = try {
        auth verify
    } catch {
        echo "✗ Authentication failed, logging in..."
        auth login admin
        auth verify
    }

    # Check KMS health
    let kms_health = try {
        kms status
    } catch {
        error make { msg: "KMS unavailable, cannot proceed" }
    }

    # Validate workflow
    let validation = try {
        orch validate workflow.k --strict
    } catch {
        error make { msg: "Workflow validation failed" }
    }

    # Proceed if all checks pass
    if $auth_status.active and $kms_health.status == "healthy" and $validation.valid {
        echo "✓ All checks passed, deploying..."
        provisioning cluster create production
    }
}

Security Best Practices

1. Never Log Decrypted Data

# ❌ BAD: Logs plaintext password
let password = kms decrypt $encrypted_password
echo $"Password: ($password)"  # Visible in logs!

# ✅ GOOD: Use directly without logging
let password = kms decrypt $encrypted_password
psql --dbname mydb --password $password  # Not logged

2. Use Context (AAD) for Critical Data

# Encrypt with context
let context = $"user=(whoami),env=production,date=(date now | format date "%Y-%m-%d")"
kms encrypt $sensitive_data --context $context

# Decrypt requires same context
kms decrypt $encrypted --context $context

3. Rotate Backup Codes

# After using backup code, generate new set
auth mfa verify --code ABCD-EFGH-IJKL
# Warning: Backup code used
auth mfa regenerate-backups
# New backup codes generated

4. Limit Token Lifetime

# Check token expiration before long operations
let session = auth verify
let expires_in = (($session.expires_at | into datetime) - (date now))
if $expires_in < 5min {
    echo "⚠️ Token expiring soon, re-authenticating..."
    auth login $session.user
}

Troubleshooting

Common Issues Across Plugins

“Plugin not found”

# Check plugin registration
plugin list | where name =~ "auth|kms|orch"

# Re-register if missing
cd provisioning/core/plugins/nushell-plugins
plugin add target/release/nu_plugin_auth
plugin add target/release/nu_plugin_kms
plugin add target/release/nu_plugin_orchestrator

# Restart Nushell
exit
nu

“Plugin command failed”

# Enable debug mode
$env.RUST_LOG = "debug"

# Run command again to see detailed errors
kms encrypt "test"

# Check plugin version compatibility
plugin list | where name =~ "kms" | select name version

“Permission denied”

# Check plugin executable permissions
ls -l provisioning/core/plugins/nushell-plugins/target/release/nu_plugin_*
# Should show: -rwxr-xr-x

# Fix if needed
chmod +x provisioning/core/plugins/nushell-plugins/target/release/nu_plugin_*

Platform-Specific Issues

macOS Issues:

# "cannot be opened because the developer cannot be verified"
xattr -d com.apple.quarantine target/release/nu_plugin_auth
xattr -d com.apple.quarantine target/release/nu_plugin_kms
xattr -d com.apple.quarantine target/release/nu_plugin_orchestrator

# Keychain access denied
# System Preferences → Security & Privacy → Privacy → Full Disk Access
# Add: /usr/local/bin/nu

Linux Issues:

# Keyring service not running
systemctl --user status gnome-keyring-daemon
systemctl --user start gnome-keyring-daemon

# Missing dependencies
sudo apt install libssl-dev pkg-config  # Ubuntu/Debian
sudo dnf install openssl-devel          # Fedora

Windows Issues:

# Credential Manager access denied
# Control Panel → User Accounts → Credential Manager
# Ensure Windows Credential Manager service is running

# Missing Visual C++ runtime
# Download from: https://aka.ms/vs/17/release/vc_redist.x64.exe

Debugging Techniques

Enable Verbose Logging:

# Set log level
$env.RUST_LOG = "debug,nu_plugin_auth=trace"

# Run command
auth login admin

# Check logs

Test Plugin Directly:

# Test plugin communication (advanced)
echo '{"Call": [0, {"name": "auth", "call": "login", "args": ["admin", "password"]}]}' \
    | target/release/nu_plugin_auth

Check Plugin Health:

# Test each plugin
auth --help       # Should show auth commands
kms --help        # Should show kms commands
orch --help       # Should show orch commands

# Test functionality
auth verify       # Should return session status
kms status        # Should return backend status
orch status       # Should return orchestrator status

Migration Guide

Migrating from HTTP to Plugin-Based

Phase 1: Install Plugins (No Breaking Changes)

# Build and register plugins
cd provisioning/core/plugins/nushell-plugins
cargo build --release --all
plugin add target/release/nu_plugin_auth
plugin add target/release/nu_plugin_kms
plugin add target/release/nu_plugin_orchestrator

# Verify HTTP still works
http get http://localhost:9090/health

Phase 2: Update Scripts Incrementally

# Before (HTTP)
def encrypt_config [file: string] {
    let data = open $file
    let result = http post http://localhost:9998/encrypt { data: $data }
    $result.encrypted | save $"($file).enc"
}

# After (Plugin with fallback)
def encrypt_config [file: string] {
    let data = open $file
    let encrypted = try {
        kms encrypt $data --backend rustyvault
    } catch {
        # Fallback to HTTP if plugin unavailable
        (http post http://localhost:9998/encrypt { data: $data }).encrypted
    }
    $encrypted | save $"($file).enc"
}

Phase 3: Test Migration

# Run side-by-side comparison
def test_migration [] {
    let test_data = "test secret data"

    # Plugin approach
    let start_plugin = date now
    let plugin_result = kms encrypt $test_data
    let plugin_time = ((date now) - $start_plugin)

    # HTTP approach
    let start_http = date now
    let http_result = (http post http://localhost:9998/encrypt { data: $test_data }).encrypted
    let http_time = ((date now) - $start_http)

    echo $"Plugin: ($plugin_time)ms"
    echo $"HTTP: ($http_time)ms"
    echo $"Speedup: (($http_time / $plugin_time))x"
}

Phase 4: Gradual Rollout

# Use feature flag for controlled rollout
$env.USE_PLUGINS = true

def encrypt_with_flag [data: string] {
    if $env.USE_PLUGINS {
        kms encrypt $data
    } else {
        (http post http://localhost:9998/encrypt { data: $data }).encrypted
    }
}

Phase 5: Full Migration

# Replace all HTTP calls with plugin calls
# Remove fallback logic once stable
def encrypt_config [file: string] {
    let data = open $file
    kms encrypt $data --backend rustyvault | save $"($file).enc"
}

Rollback Strategy

# If issues arise, quickly rollback
def rollback_to_http [] {
    # Remove plugin registrations
    plugin rm nu_plugin_auth
    plugin rm nu_plugin_kms
    plugin rm nu_plugin_orchestrator

    # Restart Nushell
    exec nu
}

Advanced Configuration

Custom Plugin Paths

# ~/.config/nushell/config.nu
$env.PLUGIN_PATH = "/opt/provisioning/plugins"

# Register from custom location
plugin add $"($env.PLUGIN_PATH)/nu_plugin_auth"
plugin add $"($env.PLUGIN_PATH)/nu_plugin_kms"
plugin add $"($env.PLUGIN_PATH)/nu_plugin_orchestrator"

Environment-Specific Configuration

# ~/.config/nushell/env.nu

# Development environment
if ($env.ENV? == "dev") {
    $env.RUSTYVAULT_ADDR = "http://localhost:8200"
    $env.CONTROL_CENTER_URL = "http://localhost:3000"
}

# Staging environment
if ($env.ENV? == "staging") {
    $env.RUSTYVAULT_ADDR = "https://vault-staging.example.com"
    $env.CONTROL_CENTER_URL = "https://control-staging.example.com"
}

# Production environment
if ($env.ENV? == "prod") {
    $env.RUSTYVAULT_ADDR = "https://vault.example.com"
    $env.CONTROL_CENTER_URL = "https://control.example.com"
}

Plugin Aliases

# ~/.config/nushell/config.nu

# Auth shortcuts
alias login = auth login
alias logout = auth logout
alias whoami = auth verify | get user

# KMS shortcuts
alias encrypt = kms encrypt
alias decrypt = kms decrypt

# Orchestrator shortcuts
alias status = orch status
alias tasks = orch tasks
alias validate = orch validate

Custom Commands

# ~/.config/nushell/custom_commands.nu

# Encrypt all files in directory
def encrypt-dir [dir: string] {
    ls $"($dir)/**/*" | where type == file | each { |file|
        kms encrypt (open $file.name) | save $"($file.name).enc"
        echo $"✓ Encrypted ($file.name)"
    }
}

# Decrypt all files in directory
def decrypt-dir [dir: string] {
    ls $"($dir)/**/*.enc" | each { |file|
        kms decrypt (open $file.name)
            | save (echo $file.name | str replace '.enc' '')
        echo $"✓ Decrypted ($file.name)"
    }
}

# Monitor deployments
def watch-deployments [] {
    while true {
        clear
        echo "=== Active Deployments ==="
        orch tasks --status running | table
        sleep 5sec
    }
}

Security Considerations

Threat Model

What Plugins Protect Against:

• ✅ Network eavesdropping (no HTTP for KMS/orch)
• ✅ Token theft from files (keyring storage)
• ✅ Credential exposure in logs (prompt-based input)
• ✅ Man-in-the-middle attacks (local file access)

What Plugins Don’t Protect Against:

• ❌ Memory dumping (decrypted data in RAM)
• ❌ Malicious plugins (trust registry only)
• ❌ Compromised OS keyring
• ❌ Physical access to machine

Secure Deployment

1. Verify Plugin Integrity

# Check plugin signatures (if available)
sha256sum target/release/nu_plugin_auth
# Compare with published checksums

# Build from trusted source
git clone https://github.com/provisioning-platform/plugins
cd plugins
cargo build --release --all

2. Restrict Plugin Access

# Set plugin permissions (only owner can execute)
chmod 700 target/release/nu_plugin_*

# Store in protected directory
sudo mkdir -p /opt/provisioning/plugins
sudo chown $(whoami):$(whoami) /opt/provisioning/plugins
sudo chmod 755 /opt/provisioning/plugins
mv target/release/nu_plugin_* /opt/provisioning/plugins/

3. Audit Plugin Usage

# Log plugin calls (for compliance)
def logged_encrypt [data: string] {
    let timestamp = date now
    let result = kms encrypt $data
    { timestamp: $timestamp, action: "encrypt" } | save --append audit.log
    $result
}

4. Rotate Credentials Regularly

# Weekly credential rotation script
def rotate_credentials [] {
    # Re-authenticate
    auth logout
    auth login admin

    # Rotate KMS keys (if supported)
    kms rotate-key --key provisioning-main

    # Update encrypted secrets
    ls secrets/*.enc | each { |file|
        let plain = kms decrypt (open $file.name)
        kms encrypt $plain | save $file.name
    }
}

FAQ

Q: Can I use plugins without RustyVault/Age installed?

A: Yes, authentication and orchestrator plugins work independently. KMS plugin requires at least one backend configured (Age is easiest for local dev).

Q: Do plugins work in CI/CD pipelines?

A: Yes, plugins work great in CI/CD. For headless environments (no keyring), use environment variables for auth or file-based tokens.

# CI/CD example
export CONTROL_CENTER_TOKEN="jwt-token-here"
kms encrypt "data" --backend age

Q: How do I update plugins?

A: Rebuild and re-register:

cd provisioning/core/plugins/nushell-plugins
git pull
cargo build --release --all
plugin add --force target/release/nu_plugin_auth
plugin add --force target/release/nu_plugin_kms
plugin add --force target/release/nu_plugin_orchestrator

Q: Can I use multiple KMS backends simultaneously?

A: Yes, specify --backend for each operation:

kms encrypt "data1" --backend rustyvault
kms encrypt "data2" --backend age
kms encrypt "data3" --backend aws

Q: What happens if a plugin crashes?

A: Nushell isolates plugin crashes. The command fails with an error, but Nushell continues running. Check logs with $env.RUST_LOG = "debug".

Q: Are plugins compatible with older Nushell versions?

A: Plugins require Nushell 0.107.1+. For older versions, use HTTP API.

Q: How do I backup MFA enrollment?

A: Save backup codes securely (password manager, encrypted file). QR code can be re-scanned from the same secret.

# Save backup codes
auth mfa enroll totp | save mfa-backup-codes.txt
kms encrypt (open mfa-backup-codes.txt) | save mfa-backup-codes.enc
rm mfa-backup-codes.txt

Q: Can plugins work offline?

A: Partially:

• ✅ kms with Age backend (fully offline)
• ✅ orch status/tasks (reads local files)
• ❌ auth (requires control center)
• ❌ kms with RustyVault/AWS/Vault (requires network)

Q: How do I troubleshoot plugin performance?

A: Use Nushell’s timing:

timeit { kms encrypt "data" }
# 5ms 123μs 456ns

timeit { http post http://localhost:9998/encrypt { data: "data" } }
# 52ms 789μs 123ns

Related Documentation

• Security System: /Users/Akasha/project-provisioning/docs/architecture/ADR-009-security-system-complete.md
• JWT Authentication: /Users/Akasha/project-provisioning/docs/architecture/JWT_AUTH_IMPLEMENTATION.md
• Config Encryption: /Users/Akasha/project-provisioning/docs/user/CONFIG_ENCRYPTION_GUIDE.md
• RustyVault Integration: /Users/Akasha/project-provisioning/RUSTYVAULT_INTEGRATION_SUMMARY.md
• MFA Implementation: /Users/Akasha/project-provisioning/docs/architecture/MFA_IMPLEMENTATION_SUMMARY.md
• Nushell Plugins Reference: /Users/Akasha/project-provisioning/docs/user/NUSHELL_PLUGINS_GUIDE.md

Version: 1.0.0 Maintained By: Platform Team Last Updated: 2025-10-09 Feedback: Open an issue or contact platform-team@example.com