# Nushell API Reference

API documentation for Nushell library functions in the provisioning platform.

## Overview

The provisioning platform provides a comprehensive Nushell library with reusable functions for infrastructure automation.

## Core Modules

### Configuration Module

**Location**: `provisioning/core/nulib/lib_provisioning/config/`

- `get-config <key>` - Retrieve configuration values
- `validate-config` - Validate configuration files
- `load-config <path>` - Load configuration from file

### Server Module

**Location**: `provisioning/core/nulib/lib_provisioning/servers/`

- `create-servers <plan>` - Create server infrastructure
- `list-servers` - List all provisioned servers
- `delete-servers <ids>` - Remove servers

### Task Service Module

**Location**: `provisioning/core/nulib/lib_provisioning/taskservs/`

- `install-taskserv <name>` - Install infrastructure service
- `list-taskservs` - List installed services
- `generate-taskserv-config <name>` - Generate service configuration

### Workspace Module

**Location**: `provisioning/core/nulib/lib_provisioning/workspace/`

- `init-workspace <name>` - Initialize new workspace
- `get-active-workspace` - Get current workspace
- `switch-workspace <name>` - Switch to different workspace

### Provider Module

**Location**: `provisioning/core/nulib/lib_provisioning/providers/`

- `discover-providers` - Find available providers
- `load-provider <name>` - Load provider module
- `list-providers` - List loaded providers

## Diagnostics & Utilities

### Diagnostics Module

**Location**: `provisioning/core/nulib/lib_provisioning/diagnostics/`

- `system-status` - Check system health (13+ checks)
- `health-check` - Deep validation (7 areas)
- `next-steps` - Get progressive guidance
- `deployment-phase` - Check deployment progress

### Hints Module

**Location**: `provisioning/core/nulib/lib_provisioning/utils/hints.nu`

- `show-next-step <context>` - Display next step suggestion
- `show-doc-link <topic>` - Show documentation link
- `show-example <command>` - Display command example

## Usage Example

```nushell
# Load provisioning library
use provisioning/core/nulib/lib_provisioning *

# Check system status
system-status | table

# Create servers
create-servers --plan "3-node-cluster" --check

# Install kubernetes
install-taskserv kubernetes --check

# Get next steps
next-steps
```

## API Conventions

All API functions follow these conventions:

- **Explicit types**: All parameters have type annotations
- **Early returns**: Validate first, fail fast
- **Pure functions**: No side effects (mutations marked with `!`)
- **Pipeline-friendly**: Output designed for Nu pipelines

## Best Practices

See [Nushell Best Practices](../development/NUSHELL_BEST_PRACTICES.md) for coding guidelines.

## Source Code

Browse the complete source code:

- **Core library**: `provisioning/core/nulib/lib_provisioning/`
- **Module index**: `provisioning/core/nulib/lib_provisioning/mod.nu`

---

For integration examples, see [Integration Examples](integration-examples.md).
