# Orchestrator Plugin Quick Reference

**Version**: 0.1.0
**Binary**: `target/release/nu_plugin_orchestrator` (7.6M)

---

## Installation

```bash
plugin add target/release/nu_plugin_orchestrator
plugin list | where name == nu_plugin_orchestrator
```

---

## Commands

### 1. Status Check

```nushell
orch status                              # Default data dir
orch status --data-dir /custom/path      # Custom location
orch status | to json                    # JSON output
```

**Returns**: `{running, tasks_pending, tasks_running, tasks_completed, last_check, data_dir}`

---

### 2. Workflow Validation

```nushell
orch validate workflow.k                 # Basic validation
orch validate workflow.k --strict        # Strict mode (checks required fields)
```

**Returns**: `{valid, errors, warnings}`

---

### 3. Task Queue

```nushell
orch tasks                               # All tasks
orch tasks --status pending              # Filter by status
orch tasks --limit 10                    # Limit results
orch tasks --status running --limit 5    # Combined filters
```

**Returns**: `[{id, status, priority, created_at, workflow_id}]`

---

## Common Patterns

### Check if Orchestrator Running

```nushell
if (orch status | get running) { "✓ Running" } else { "✗ Stopped" }
```

### Validate Before Submit

```nushell
let valid = (orch validate workflow.k | get valid)
if $valid { "✓ Valid" } else { "✗ Invalid" }
```

### Count Tasks by Status

```nushell
orch tasks | group-by status | each { |k,v| {status: $k, count: ($v | length)} }
```

### Find High Priority Tasks

```nushell
orch tasks | where priority > 7 | select id priority
```

---

## Environment

```bash
export ORCHESTRATOR_DATA_DIR=/custom/path/to/data
```

---

## Data Structure

```
provisioning/platform/orchestrator/data/
├── status.json              # {running, tasks_*, last_check}
└── tasks/
    ├── task-001.json       # {id, status, created_at, priority, workflow_id}
    └── ...
```

---

## Performance

| Operation | Latency | Notes |
|-----------|---------|-------|
| `orch status` | ~1ms | Single file read |
| `orch tasks` | ~10ms | 1000 tasks |
| `orch validate` | ~50-100ms | KCL subprocess |

**5-10x faster than HTTP** for read operations

---

## See Also

- **Usage Examples**: `USAGE_EXAMPLES.md`
- **Implementation**: `IMPLEMENTATION_SUMMARY.md`
- **Architecture**: `/.claude/features/orchestrator-architecture.md`