nushell-plugins/nu_plugin_orchestrator/usage-examples.md

Orchestrator Plugin Usage Examples\n\nThis document provides comprehensive examples for using the nu_plugin_orchestrator plugin.\n\n## Installation\n\nFirst, register the plugin with Nushell:\n\nbash\n# Build the plugin\ncd provisioning/core/plugins/nushell-plugins/nu_plugin_orchestrator\ncargo build --release\n\n# Register with Nushell\nplugin add target/release/nu_plugin_orchestrator\n\n\n## Commands Overview\n\nThe plugin provides three main commands:\n\n1. orch status - Get orchestrator status from local state\n2. orch validate - Validate workflow KCL files\n3. orch tasks - List orchestrator tasks from local queue\n\n---\n\n## 1. Checking Orchestrator Status\n\n### Basic Status Check\n\nnushell\norch status\n\n\nOutput:\n\nplaintext\n╭─────────────────┬────────────────────────────────────────────────────────╮\n│ running │ false │\n│ tasks_pending │ 5 │\n│ tasks_running │ 2 │\n│ tasks_completed │ 10 │\n│ last_check │ 2025-10-09T12:00:00Z │\n│ data_dir │ provisioning/platform/orchestrator/data │\n╰─────────────────┴────────────────────────────────────────────────────────╯\n\n\n### Custom Data Directory\n\nnushell\norch status --data-dir /custom/path/to/orchestrator/data\n\n\n### Format as JSON\n\nnushell\norch status | to json\n\n\nOutput:\n\njson\n{\n "running": false,\n "tasks_pending": 5,\n "tasks_running": 2,\n "tasks_completed": 10,\n "last_check": "2025-10-09T12:00:00Z",\n "data_dir": "provisioning/platform/orchestrator/data"\n}\n\n\n### Check if Orchestrator is Running\n\nnushell\nif (orch status | get running) {\n print "Orchestrator is running"\n} else {\n print "Orchestrator is not running"\n}\n\n\n---\n\n## 2. Validating Workflow Files\n\n### Basic Validation\n\nnushell\norch validate test-workflow.k\n\n\nOutput (Valid):\n\nplaintext\n╭──────────┬──────╮\n│ valid │ true │\n│ errors │ [] │\n│ warnings │ [] │\n╰──────────┴──────╯\n\n\nOutput (Invalid):\n\nplaintext\n╭──────────┬─────────────────────────────────────────────────────────────╮\n│ valid │ false │\n│ errors │ ["File not found: nonexistent.k"] │\n│ warnings │ [] │\n╰──────────┴─────────────────────────────────────────────────────────────╯\n\n\n### Strict Validation\n\nStrict mode performs additional checks for required fields:\n\nnushell\norch validate workflow.k --strict\n\n\nOutput:\n\nplaintext\n╭──────────┬──────────────────────────────────────────────────────────╮\n│ valid │ false │\n│ errors │ ["Missing 'operations' field (required)"] │\n│ warnings │ ["Missing 'name' field", "Missing 'version' field"] │\n╰──────────┴──────────────────────────────────────────────────────────╯\n\n\n### Validation Pipeline\n\nnushell\n# Validate and check if valid\norch validate workflow.k | if $in.valid {\n print "✓ Workflow is valid"\n} else {\n print "✗ Workflow has errors"\n}\n\n# Validate multiple files\nls workflows/*.k | each { |file|\n let result = (orch validate $file.name)\n {\n file: $file.name,\n valid: $result.valid,\n error_count: ($result.errors | length)\n }\n}\n\n\n### Extract Validation Errors\n\nnushell\n# Show only errors\norch validate workflow.k | get errors\n\n# Show errors and warnings\nlet result = (orch validate workflow.k --strict)\nprint $"Errors: ($result.errors)"\nprint $"Warnings: ($result.warnings)"\n\n\n---\n\n## 3. Listing Tasks\n\n### List All Tasks\n\nnushell\norch tasks\n\n\nOutput:\n\nplaintext\n╭───┬──────────┬──────────┬──────────┬──────────────────────┬──────────────╮\n│ # │ id │ status │ priority │ created_at │ workflow_id │\n├───┼──────────┼──────────┼──────────┼──────────────────────┼──────────────┤\n│ 0 │ task-001 │ pending │ 10 │ 2025-10-09T10:00:00Z │ workflow-123 │\n│ 1 │ task-002 │ running │ 8 │ 2025-10-09T10:30:00Z │ workflow-123 │\n│ 2 │ task-003 │ pending │ 5 │ 2025-10-09T11:00:00Z │ │\n╰───┴──────────┴──────────┴──────────┴──────────────────────┴──────────────╯\n\n\n### Filter by Status\n\nnushell\n# Show only pending tasks\norch tasks --status pending\n\n# Show only running tasks\norch tasks --status running\n\n# Show only completed tasks\norch tasks --status completed\n\n\n### Limit Results\n\nnushell\n# Show only first 10 tasks\norch tasks --limit 10\n\n# Show top 5 pending tasks\norch tasks --status pending --limit 5\n\n\n### Combine Filters\n\nnushell\n# Top 3 pending tasks\norch tasks --status pending --limit 3\n\n\n### Task Analysis\n\nnushell\n# Count tasks by status\norch tasks | group-by status | each { |key, items|\n {status: $key, count: ($items | length)}\n}\n\n# Find high-priority tasks\norch tasks | where priority > 7\n\n# Tasks without workflow\norch tasks | where workflow_id == null\n\n# Tasks created in last hour\norch tasks | where created_at > ((date now) - 1hr)\n\n\n### Export to JSON\n\nnushell\n# Export all tasks\norch tasks | to json > tasks.json\n\n# Export pending tasks\norch tasks --status pending | to json > pending-tasks.json\n\n\n---\n\n## Advanced Usage Examples\n\n### Monitoring Dashboard\n\nnushell\ndef orch-dashboard [] {\n let status = (orch status)\n let tasks = (orch tasks)\n\n print $"╭─────────────────────────────────────╮"\n print $"│ Orchestrator Dashboard │"\n print $"╰─────────────────────────────────────╯"\n print ""\n print $"Status: ($status.running | if $in { '🟢 Running' } else { '🔴 Stopped' })"\n print $"Pending: ($status.tasks_pending)"\n print $"Running: ($status.tasks_running)"\n print $"Completed: ($status.tasks_completed)"\n print ""\n\n let by_status = ($tasks | group-by status | each { |key, items|\n {status: $key, count: ($items | length)}\n })\n\n print "Tasks by Status:"\n $by_status | table\n}\n\norch-dashboard\n\n\n### Validation Report\n\nnushell\ndef validate-all-workflows [] {\n ls workflows/*.k | each { |file|\n let result = (orch validate $file.name --strict)\n {\n file: ($file.name | path basename),\n valid: $result.valid,\n errors: ($result.errors | length),\n warnings: ($result.warnings | length)\n }\n } | table\n}\n\nvalidate-all-workflows\n\n\n### Task Queue Monitor\n\nnushell\ndef monitor-queue [interval: duration = 5sec] {\n loop {\n clear\n print $"Last updated: (date now)"\n print ""\n orch tasks | table\n sleep $interval\n }\n}\n\nmonitor-queue\n\n\n### Automatic Workflow Validation\n\nnushell\ndef submit-workflow [workflow: string] {\n let validation = (orch validate $workflow --strict)\n\n if $validation.valid {\n print $"✓ Workflow ($workflow) is valid"\n # Submit to orchestrator\n # http post http://localhost:8080/workflows/batch/submit ...\n } else {\n print $"✗ Workflow ($workflow) has errors:"\n $validation.errors | each { |err| print $" - ($err)" }\n error make {msg: "Workflow validation failed"}\n }\n}\n\nsubmit-workflow test-workflow.k\n\n\n---\n\n## Environment Variables\n\nThe plugin respects the following environment variables:\n\n- ORCHESTRATOR_DATA_DIR: Override default data directory\n\n bash\n export ORCHESTRATOR_DATA_DIR=/custom/orchestrator/data\n orch status\n \n\n---\n\n## Data Directory Structure\n\nThe plugin expects the following directory structure:\n\nplaintext\nprovisioning/platform/orchestrator/data/\n├── status.json # Orchestrator status\n└── tasks/ # Task queue\n ├── task-001.json\n ├── task-002.json\n └── task-003.json\n\n\n### Status File Format (status.json)\n\njson\n{\n "running": true,\n "tasks_pending": 5,\n "tasks_running": 2,\n "tasks_completed": 10,\n "last_check": "2025-10-09T12:00:00Z"\n}\n\n\n### Task File Format (task-XXX.json)\n\njson\n{\n "id": "task-001",\n "status": "pending",\n "created_at": "2025-10-09T10:00:00Z",\n "priority": 10,\n "workflow_id": "workflow-123"\n}\n\n\n---\n\n## Troubleshooting\n\n### Plugin Not Found\n\nIf you get "command not found", ensure the plugin is registered:\n\nbash\nplugin list | where name == nu_plugin_orchestrator\n\n\nIf not listed, register it:\n\nbash\nplugin add target/release/nu_plugin_orchestrator\n\n\n### Data Directory Not Found\n\nIf status.json or tasks directory doesn't exist, the plugin returns default values:\n\nnushell\norch status # Returns default status with 0 tasks\norch tasks # Returns empty list\n\n\nCreate the directory structure:\n\nbash\nmkdir -p provisioning/platform/orchestrator/data/tasks\n\n\n### KCL Validation Fails\n\nEnsure kcl is in your PATH:\n\nbash\nwhich kcl\nkcl --version\n\n\n---\n\n## Integration Examples\n\n### With CI/CD\n\nyaml\n# .gitlab-ci.yml\nvalidate-workflows:\n script:\n - nu -c "ls workflows/*.k | each { |f| orch validate $f.name --strict }"\n\n\n### With Nushell Scripts\n\nnushell\n# deploy.nu\nuse std assert\n\ndef main [workflow: string] {\n # Validate workflow\n let validation = (orch validate $workflow --strict)\n assert ($validation.valid) "Workflow validation failed"\n\n # Check orchestrator is running\n let status = (orch status)\n assert ($status.running) "Orchestrator is not running"\n\n # Submit workflow\n print "Submitting workflow..."\n # ... submit logic ...\n}\n\n\n---\n\n## Performance Notes\n\n- orch status: Reads single JSON file (~1ms)\n- orch tasks: Walks task directory, O(n) for n tasks (~10ms for 1000 tasks)\n- orch validate: Spawns kcl process (~50-100ms depending on workflow size)\n\n---\n\n## See Also\n\n- Orchestrator Architecture\n- Batch Workflow System\n- KCL Idiomatic Patterns