nushell-plugins/nu_plugin_orchestrator/USAGE_EXAMPLES.md

Orchestrator Plugin Usage Examples

This document provides comprehensive examples for using the nu_plugin_orchestrator plugin.

Installation

First, register the plugin with Nushell:

# Build the plugin
cd provisioning/core/plugins/nushell-plugins/nu_plugin_orchestrator
cargo build --release

# Register with Nushell
plugin add target/release/nu_plugin_orchestrator

Commands Overview

The plugin provides three main commands:

1. orch status - Get orchestrator status from local state
2. orch validate - Validate workflow KCL files
3. orch tasks - List orchestrator tasks from local queue

---

1. Checking Orchestrator Status

Basic Status Check

orch status

Output:

╭─────────────────┬────────────────────────────────────────────────────────╮
│ running         │ false                                                  │
│ tasks_pending   │ 5                                                      │
│ tasks_running   │ 2                                                      │
│ tasks_completed │ 10                                                     │
│ last_check      │ 2025-10-09T12:00:00Z                                  │
│ data_dir        │ provisioning/platform/orchestrator/data               │
╰─────────────────┴────────────────────────────────────────────────────────╯

Custom Data Directory

orch status --data-dir /custom/path/to/orchestrator/data

Format as JSON

orch status | to json

Output:

{
  "running": false,
  "tasks_pending": 5,
  "tasks_running": 2,
  "tasks_completed": 10,
  "last_check": "2025-10-09T12:00:00Z",
  "data_dir": "provisioning/platform/orchestrator/data"
}

Check if Orchestrator is Running

if (orch status | get running) {
    print "Orchestrator is running"
} else {
    print "Orchestrator is not running"
}

---

2. Validating Workflow Files

Basic Validation

orch validate test-workflow.k

Output (Valid):

╭──────────┬──────╮
│ valid    │ true │
│ errors   │ []   │
│ warnings │ []   │
╰──────────┴──────╯

Output (Invalid):

╭──────────┬─────────────────────────────────────────────────────────────╮
│ valid    │ false                                                       │
│ errors   │ ["File not found: nonexistent.k"]                          │
│ warnings │ []                                                          │
╰──────────┴─────────────────────────────────────────────────────────────╯

Strict Validation

Strict mode performs additional checks for required fields:

orch validate workflow.k --strict

Output:

╭──────────┬──────────────────────────────────────────────────────────╮
│ valid    │ false                                                    │
│ errors   │ ["Missing 'operations' field (required)"]               │
│ warnings │ ["Missing 'name' field", "Missing 'version' field"]     │
╰──────────┴──────────────────────────────────────────────────────────╯

Validation Pipeline

# Validate and check if valid
orch validate workflow.k | if $in.valid {
    print "✓ Workflow is valid"
} else {
    print "✗ Workflow has errors"
}

# Validate multiple files
ls workflows/*.k | each { |file|
    let result = (orch validate $file.name)
    {
        file: $file.name,
        valid: $result.valid,
        error_count: ($result.errors | length)
    }
}

Extract Validation Errors

# Show only errors
orch validate workflow.k | get errors

# Show errors and warnings
let result = (orch validate workflow.k --strict)
print $"Errors: ($result.errors)"
print $"Warnings: ($result.warnings)"

---

3. Listing Tasks

List All Tasks

orch tasks

Output:

╭───┬──────────┬──────────┬──────────┬──────────────────────┬──────────────╮
│ # │    id    │  status  │ priority │     created_at       │ workflow_id  │
├───┼──────────┼──────────┼──────────┼──────────────────────┼──────────────┤
│ 0 │ task-001 │ pending  │       10 │ 2025-10-09T10:00:00Z │ workflow-123 │
│ 1 │ task-002 │ running  │        8 │ 2025-10-09T10:30:00Z │ workflow-123 │
│ 2 │ task-003 │ pending  │        5 │ 2025-10-09T11:00:00Z │              │
╰───┴──────────┴──────────┴──────────┴──────────────────────┴──────────────╯

Filter by Status

# Show only pending tasks
orch tasks --status pending

# Show only running tasks
orch tasks --status running

# Show only completed tasks
orch tasks --status completed

Limit Results

# Show only first 10 tasks
orch tasks --limit 10

# Show top 5 pending tasks
orch tasks --status pending --limit 5

Combine Filters

# Top 3 pending tasks
orch tasks --status pending --limit 3

Task Analysis

# Count tasks by status
orch tasks | group-by status | each { |key, items|
    {status: $key, count: ($items | length)}
}

# Find high-priority tasks
orch tasks | where priority > 7

# Tasks without workflow
orch tasks | where workflow_id == null

# Tasks created in last hour
orch tasks | where created_at > ((date now) - 1hr)

Export to JSON

# Export all tasks
orch tasks | to json > tasks.json

# Export pending tasks
orch tasks --status pending | to json > pending-tasks.json

---

Advanced Usage Examples

Monitoring Dashboard

def orch-dashboard [] {
    let status = (orch status)
    let tasks = (orch tasks)

    print $"╭─────────────────────────────────────╮"
    print $"│  Orchestrator Dashboard            │"
    print $"╰─────────────────────────────────────╯"
    print ""
    print $"Status: ($status.running | if $in { '🟢 Running' } else { '🔴 Stopped' })"
    print $"Pending:   ($status.tasks_pending)"
    print $"Running:   ($status.tasks_running)"
    print $"Completed: ($status.tasks_completed)"
    print ""

    let by_status = ($tasks | group-by status | each { |key, items|
        {status: $key, count: ($items | length)}
    })

    print "Tasks by Status:"
    $by_status | table
}

orch-dashboard

Validation Report

def validate-all-workflows [] {
    ls workflows/*.k | each { |file|
        let result = (orch validate $file.name --strict)
        {
            file: ($file.name | path basename),
            valid: $result.valid,
            errors: ($result.errors | length),
            warnings: ($result.warnings | length)
        }
    } | table
}

validate-all-workflows

Task Queue Monitor

def monitor-queue [interval: duration = 5sec] {
    loop {
        clear
        print $"Last updated: (date now)"
        print ""
        orch tasks | table
        sleep $interval
    }
}

monitor-queue

Automatic Workflow Validation

def submit-workflow [workflow: string] {
    let validation = (orch validate $workflow --strict)

    if $validation.valid {
        print $"✓ Workflow ($workflow) is valid"
        # Submit to orchestrator
        # http post http://localhost:8080/workflows/batch/submit ...
    } else {
        print $"✗ Workflow ($workflow) has errors:"
        $validation.errors | each { |err| print $"  - ($err)" }
        error make {msg: "Workflow validation failed"}
    }
}

submit-workflow test-workflow.k

---

Environment Variables

The plugin respects the following environment variables:

• ORCHESTRATOR_DATA_DIR: Override default data directory

  export ORCHESTRATOR_DATA_DIR=/custom/orchestrator/data
  orch status
  

---

Data Directory Structure

The plugin expects the following directory structure:

provisioning/platform/orchestrator/data/
├── status.json                 # Orchestrator status
└── tasks/                      # Task queue
    ├── task-001.json
    ├── task-002.json
    └── task-003.json

Status File Format (status.json)

{
  "running": true,
  "tasks_pending": 5,
  "tasks_running": 2,
  "tasks_completed": 10,
  "last_check": "2025-10-09T12:00:00Z"
}

Task File Format (task-XXX.json)

{
  "id": "task-001",
  "status": "pending",
  "created_at": "2025-10-09T10:00:00Z",
  "priority": 10,
  "workflow_id": "workflow-123"
}

---

Troubleshooting

Plugin Not Found

If you get "command not found", ensure the plugin is registered:

plugin list | where name == nu_plugin_orchestrator

If not listed, register it:

plugin add target/release/nu_plugin_orchestrator

Data Directory Not Found

If status.json or tasks directory doesn't exist, the plugin returns default values:

orch status  # Returns default status with 0 tasks
orch tasks   # Returns empty list

Create the directory structure:

mkdir -p provisioning/platform/orchestrator/data/tasks

KCL Validation Fails

Ensure kcl is in your PATH:

which kcl
kcl --version

---

Integration Examples

With CI/CD

# .gitlab-ci.yml
validate-workflows:
  script:
    - nu -c "ls workflows/*.k | each { |f| orch validate $f.name --strict }"

With Nushell Scripts

# deploy.nu
use std assert

def main [workflow: string] {
    # Validate workflow
    let validation = (orch validate $workflow --strict)
    assert ($validation.valid) "Workflow validation failed"

    # Check orchestrator is running
    let status = (orch status)
    assert ($status.running) "Orchestrator is not running"

    # Submit workflow
    print "Submitting workflow..."
    # ... submit logic ...
}

---

Performance Notes

• orch status: Reads single JSON file (~1ms)
• orch tasks: Walks task directory, O(n) for n tasks (~10ms for 1000 tasks)
• orch validate: Spawns kcl process (~50-100ms depending on workflow size)

---

See Also

• Orchestrator Architecture
• Batch Workflow System
• KCL Idiomatic Patterns