provisioning/docs/src/infrastructure/cli-reference.md

# CLI Reference

Complete command-line reference for Infrastructure Automation. This guide covers all commands, options, and usage patterns.

## What You'll Learn

- Complete command syntax and options
- All available commands and subcommands
- Usage examples and patterns
- Scripting and automation
- Integration with other tools
- Advanced command combinations

## Command Structure

All provisioning commands follow this structure:

```text
provisioning [global-options] <command> [subcommand] [command-options] [arguments]
```

### Global Options

These options can be used with any command:

| Option | Short | Description | Example |
| -------- | ------- | ------------- | --------- |
| `--infra` | `-i` | Specify infrastructure | `--infra production` |
| `--environment` | | Environment override | `--environment prod` |
| `--check` | `-c` | Dry run mode | `--check` |
| `--debug` | `-x` | Enable debug output | `--debug` |
| `--yes` | `-y` | Auto-confirm actions | `--yes` |
| `--wait` | `-w` | Wait for completion | `--wait` |
| `--out` | | Output format | `--out json` |
| `--help` | `-h` | Show help | `--help` |

### Output Formats

| Format | Description | Use Case |
| -------- | ------------- | ---------- |
| `text` | Human-readable text | Terminal viewing |
| `json` | JSON format | Scripting, APIs |
| `yaml` | YAML format | Configuration files |
| `toml` | TOML format | Settings files |
| `table` | Tabular format | Reports, lists |

## Core Commands

### help - Show Help Information

Display help information for the system or specific commands.

```text
# General help
provisioning help

# Command-specific help
provisioning help server
provisioning help taskserv
provisioning help cluster

# Show all available commands
provisioning help --all

# Show help for subcommand
provisioning server help create
```

**Options:**

- `--all` - Show all available commands
- `--detailed` - Show detailed help with examples

### version - Show Version Information

Display version information for the system and dependencies.

```text
# Basic version
provisioning version
provisioning --version
provisioning -V

# Detailed version with dependencies
provisioning version --verbose

# Show version info with title
provisioning --info
provisioning -I
```

**Options:**

- `--verbose` - Show detailed version information
- `--dependencies` - Include dependency versions

### env - Environment Information

Display current environment configuration and settings.

```text
# Show environment variables
provisioning env

# Show all environment and configuration
provisioning allenv

# Show specific environment
provisioning env --environment prod

# Export environment
provisioning env --export
```

**Output includes:**

- Configuration file locations
- Environment variables
- Provider settings
- Path configurations

## Server Management Commands

### server create - Create Servers

Create new server instances based on configuration.

```text
# Create all servers in infrastructure
provisioning server create --infra my-infra

# Dry run (check mode)
provisioning server create --infra my-infra --check

# Create with confirmation
provisioning server create --infra my-infra --yes

# Create and wait for completion
provisioning server create --infra my-infra --wait

# Create specific server
provisioning server create web-01 --infra my-infra

# Create with custom settings
provisioning server create --infra my-infra --settings custom.ncl
```

**Options:**

- `--check`, `-c` - Dry run mode (show what would be created)
- `--yes`, `-y` - Auto-confirm creation
- `--wait`, `-w` - Wait for servers to be fully ready
- `--settings`, `-s` - Custom settings file
- `--template`, `-t` - Use specific template

### server delete - Delete Servers

Remove server instances and associated resources.

```text
# Delete all servers
provisioning server delete --infra my-infra

# Delete with confirmation
provisioning server delete --infra my-infra --yes

# Delete but keep storage
provisioning server delete --infra my-infra --keepstorage

# Delete specific server
provisioning server delete web-01 --infra my-infra

# Dry run deletion
provisioning server delete --infra my-infra --check
```

**Options:**

- `--yes`, `-y` - Auto-confirm deletion
- `--keepstorage` - Preserve storage volumes
- `--force` - Force deletion even if servers are running

### server list - List Servers

Display information about servers.

```text
# List all servers
provisioning server list --infra my-infra

# List with detailed information
provisioning server list --infra my-infra --detailed

# List in specific format
provisioning server list --infra my-infra --out json

# List servers across all infrastructures
provisioning server list --all

# Filter by status
provisioning server list --infra my-infra --status running
```

**Options:**

- `--detailed` - Show detailed server information
- `--status` - Filter by server status
- `--all` - Show servers from all infrastructures

### server ssh - SSH Access

Connect to servers via SSH.

```text
# SSH to server
provisioning server ssh web-01 --infra my-infra

# SSH with specific user
provisioning server ssh web-01 --user admin --infra my-infra

# SSH with custom key
provisioning server ssh web-01 --key ~/.ssh/custom_key --infra my-infra

# Execute single command
provisioning server ssh web-01 --command "systemctl status nginx" --infra my-infra
```

**Options:**

- `--user` - SSH username (default from configuration)
- `--key` - SSH private key file
- `--command` - Execute command and exit
- `--port` - SSH port (default: 22)

### server price - Cost Information

Display pricing information for servers.

```text
# Show costs for all servers
provisioning server price --infra my-infra

# Show detailed cost breakdown
provisioning server price --infra my-infra --detailed

# Show monthly estimates
provisioning server price --infra my-infra --monthly

# Cost comparison between providers
provisioning server price --infra my-infra --compare
```

**Options:**

- `--detailed` - Detailed cost breakdown
- `--monthly` - Monthly cost estimates
- `--compare` - Compare costs across providers

## Task Service Commands

### taskserv create - Install Services

Install and configure task services on servers.

```text
# Install service on all eligible servers
provisioning taskserv create kubernetes --infra my-infra

# Install with check mode
provisioning taskserv create kubernetes --infra my-infra --check

# Install specific version
provisioning taskserv create kubernetes --version 1.28 --infra my-infra

# Install on specific servers
provisioning taskserv create postgresql --servers db-01,db-02 --infra my-infra

# Install with custom configuration
provisioning taskserv create kubernetes --config k8s-config.yaml --infra my-infra
```

**Options:**

- `--version` - Specific version to install
- `--config` - Custom configuration file
- `--servers` - Target specific servers
- `--force` - Force installation even if conflicts exist

### taskserv delete - Remove Services

Remove task services from servers.

```text
# Remove service
provisioning taskserv delete kubernetes --infra my-infra

# Remove with data cleanup
provisioning taskserv delete postgresql --cleanup-data --infra my-infra

# Remove from specific servers
provisioning taskserv delete nginx --servers web-01,web-02 --infra my-infra

# Dry run removal
provisioning taskserv delete kubernetes --infra my-infra --check
```

**Options:**

- `--cleanup-data` - Remove associated data
- `--servers` - Target specific servers
- `--force` - Force removal

### taskserv list - List Services

Display available and installed task services.

```text
# List all available services
provisioning taskserv list

# List installed services
provisioning taskserv list --infra my-infra --installed

# List by category
provisioning taskserv list --category database

# List with versions
provisioning taskserv list --versions

# Search services
provisioning taskserv list --search kubernetes
```

**Options:**

- `--installed` - Show only installed services
- `--category` - Filter by service category
- `--versions` - Include version information
- `--search` - Search by name or description

### taskserv generate - Generate Configurations

Generate configuration files for task services.

```text
# Generate configuration
provisioning taskserv generate kubernetes --infra my-infra

# Generate with custom template
provisioning taskserv generate kubernetes --template custom --infra my-infra

# Generate for specific servers
provisioning taskserv generate nginx --servers web-01,web-02 --infra my-infra

# Generate and save to file
provisioning taskserv generate postgresql --output db-config.yaml --infra my-infra
```

**Options:**

- `--template` - Use specific template
- `--output` - Save to specific file
- `--servers` - Target specific servers

### taskserv check-updates - Version Management

Check for and manage service version updates.

```text
# Check updates for all services
provisioning taskserv check-updates --infra my-infra

# Check specific service
provisioning taskserv check-updates kubernetes --infra my-infra

# Show available versions
provisioning taskserv versions kubernetes

# Update to latest version
provisioning taskserv update kubernetes --infra my-infra

# Update to specific version
provisioning taskserv update kubernetes --version 1.29 --infra my-infra
```

**Options:**

- `--version` - Target specific version
- `--security-only` - Only security updates
- `--dry-run` - Show what would be updated

## Cluster Management Commands

### cluster create - Deploy Clusters

Deploy and configure application clusters.

```text
# Create cluster
provisioning cluster create web-cluster --infra my-infra

# Create with check mode
provisioning cluster create web-cluster --infra my-infra --check

# Create with custom configuration
provisioning cluster create web-cluster --config cluster.yaml --infra my-infra

# Create and scale immediately
provisioning cluster create web-cluster --replicas 5 --infra my-infra
```

**Options:**

- `--config` - Custom cluster configuration
- `--replicas` - Initial replica count
- `--namespace` - Kubernetes namespace

### cluster delete - Remove Clusters

Remove application clusters and associated resources.

```text
# Delete cluster
provisioning cluster delete web-cluster --infra my-infra

# Delete with data cleanup
provisioning cluster delete web-cluster --cleanup --infra my-infra

# Force delete
provisioning cluster delete web-cluster --force --infra my-infra
```

**Options:**

- `--cleanup` - Remove associated data
- `--force` - Force deletion
- `--keep-volumes` - Preserve persistent volumes

### cluster list - List Clusters

Display information about deployed clusters.

```text
# List all clusters
provisioning cluster list --infra my-infra

# List with status
provisioning cluster list --infra my-infra --status

# List across all infrastructures
provisioning cluster list --all

# Filter by namespace
provisioning cluster list --namespace production --infra my-infra
```

**Options:**

- `--status` - Include status information
- `--all` - Show clusters from all infrastructures
- `--namespace` - Filter by namespace

### cluster scale - Scale Clusters

Adjust cluster size and resources.

```text
# Scale cluster
provisioning cluster scale web-cluster --replicas 10 --infra my-infra

# Auto-scale configuration
provisioning cluster scale web-cluster --auto-scale --min 3 --max 20 --infra my-infra

# Scale specific component
provisioning cluster scale web-cluster --component api --replicas 5 --infra my-infra
```

**Options:**

- `--replicas` - Target replica count
- `--auto-scale` - Enable auto-scaling
- `--min`, `--max` - Auto-scaling limits
- `--component` - Scale specific component

## Infrastructure Commands

### generate - Generate Configurations

Generate infrastructure and configuration files.

```text
# Generate new infrastructure
provisioning generate infra --new my-infrastructure

# Generate from template
provisioning generate infra --template web-app --name my-app

# Generate server configurations
provisioning generate server --infra my-infra

# Generate task service configurations
provisioning generate taskserv --infra my-infra

# Generate cluster configurations
provisioning generate cluster --infra my-infra
```

**Subcommands:**

- `infra` - Infrastructure configurations
- `server` - Server configurations
- `taskserv` - Task service configurations
- `cluster` - Cluster configurations

**Options:**

- `--new` - Create new infrastructure
- `--template` - Use specific template
- `--name` - Name for generated resources
- `--output` - Output directory

### show - Display Information

Show detailed information about infrastructure components.

```text
# Show settings
provisioning show settings --infra my-infra

# Show servers
provisioning show servers --infra my-infra

# Show specific server
provisioning show servers web-01 --infra my-infra

# Show task services
provisioning show taskservs --infra my-infra

# Show costs
provisioning show costs --infra my-infra

# Show in different format
provisioning show servers --infra my-infra --out json
```

**Subcommands:**

- `settings` - Configuration settings
- `servers` - Server information
- `taskservs` - Task service information
- `costs` - Cost information
- `data` - Raw infrastructure data

### list - List Resources

List resource types (servers, networks, volumes, etc.).

```text
# List providers
provisioning list providers

# List task services
provisioning list taskservs

# List clusters
provisioning list clusters

# List infrastructures
provisioning list infras

# List with selection interface
provisioning list servers --select
```

**Subcommands:**

- `providers` - Available providers
- `taskservs` - Available task services
- `clusters` - Available clusters
- `infras` - Available infrastructures
- `servers` - Server instances

### validate - Validate Configuration

Validate configuration files and infrastructure definitions.

```text
# Validate configuration
provisioning validate config --infra my-infra

# Validate with detailed output
provisioning validate config --detailed --infra my-infra

# Validate specific file
provisioning validate config settings.ncl --infra my-infra

# Quick validation
provisioning validate quick --infra my-infra

# Validate interpolation
provisioning validate interpolation --infra my-infra
```

**Subcommands:**

- `config` - Configuration validation
- `quick` - Quick infrastructure validation
- `interpolation` - Interpolation pattern validation

**Options:**

- `--detailed` - Show detailed validation results
- `--strict` - Strict validation mode
- `--rules` - Show validation rules

## Configuration Commands

### init - Initialize Configuration

Initialize user and project configurations.

```text
# Initialize user configuration
provisioning init config

# Initialize with specific template
provisioning init config dev

# Initialize project configuration
provisioning init project

# Force overwrite existing
provisioning init config --force
```

**Subcommands:**

- `config` - User configuration
- `project` - Project configuration

**Options:**

- `--template` - Configuration template
- `--force` - Overwrite existing files

### template - Template Management

Manage configuration templates.

```text
# List available templates
provisioning template list

# Show template content
provisioning template show dev

# Validate templates
provisioning template validate

# Create custom template
provisioning template create my-template --from dev
```

**Subcommands:**

- `list` - List available templates
- `show` - Display template content
- `validate` - Validate templates
- `create` - Create custom template

## Advanced Commands

### nu - Interactive Shell

Start interactive Nushell session with provisioning library loaded.

```text
# Start interactive shell
provisioning nu

# Execute specific command
provisioning nu -c "use lib_provisioning *; show_env"

# Start with custom script
provisioning nu --script my-script.nu
```

**Options:**

- `-c` - Execute command and exit
- `--script` - Run specific script
- `--load` - Load additional modules

### sops - Secret Management

Edit encrypted configuration files using SOPS.

```text
# Edit encrypted file
provisioning sops settings.ncl --infra my-infra

# Encrypt new file
provisioning sops --encrypt new-secrets.ncl --infra my-infra

# Decrypt for viewing
provisioning sops --decrypt secrets.ncl --infra my-infra

# Rotate keys
provisioning sops --rotate-keys secrets.ncl --infra my-infra
```

**Options:**

- `--encrypt` - Encrypt file
- `--decrypt` - Decrypt file
- `--rotate-keys` - Rotate encryption keys

### context - Context Management

Manage infrastructure contexts and environments.

```text
# Show current context
provisioning context

# List available contexts
provisioning context list

# Switch context
provisioning context switch production

# Create new context
provisioning context create staging --from development

# Delete context
provisioning context delete old-context
```

**Subcommands:**

- `list` - List contexts
- `switch` - Switch active context
- `create` - Create new context
- `delete` - Delete context

## Workflow Commands

### workflows - Batch Operations

Manage complex workflows and batch operations.

```text
# Submit batch workflow
provisioning workflows batch submit my-workflow.ncl

# Monitor workflow progress
provisioning workflows batch monitor workflow-123

# List workflows
provisioning workflows batch list --status running

# Get workflow status
provisioning workflows batch status workflow-123

# Rollback failed workflow
provisioning workflows batch rollback workflow-123
```

**Options:**

- `--status` - Filter by workflow status
- `--follow` - Follow workflow progress
- `--timeout` - Set timeout for operations

### orchestrator - Orchestrator Management

Control the hybrid orchestrator system.

```text
# Start orchestrator
provisioning orchestrator start

# Check orchestrator status
provisioning orchestrator status

# Stop orchestrator
provisioning orchestrator stop

# Show orchestrator logs
provisioning orchestrator logs

# Health check
provisioning orchestrator health
```

## Scripting and Automation

### Exit Codes

Provisioning uses standard exit codes:

- `0` - Success
- `1` - General error
- `2` - Invalid command or arguments
- `3` - Configuration error
- `4` - Permission denied
- `5` - Resource not found

### Environment Variables

Control behavior through environment variables:

```text
# Enable debug mode
export PROVISIONING_DEBUG=true

# Set environment
export PROVISIONING_ENV=production

# Set output format
export PROVISIONING_OUTPUT_FORMAT=json

# Disable interactive prompts
export PROVISIONING_NONINTERACTIVE=true
```

### Batch Operations

```text
#!/bin/bash
# Example batch script

# Set environment
export PROVISIONING_ENV=production
export PROVISIONING_NONINTERACTIVE=true

# Validate first
if ! provisioning validate config --infra production; then
    echo "Configuration validation failed"
    exit 1
fi

# Create infrastructure
provisioning server create --infra production --yes --wait

# Install services
provisioning taskserv create kubernetes --infra production --yes
provisioning taskserv create postgresql --infra production --yes

# Deploy clusters
provisioning cluster create web-app --infra production --yes

echo "Deployment completed successfully"
```

### JSON Output Processing

```text
# Get server list as JSON
servers=$(provisioning server list --infra my-infra --out json)

# Process with jq
echo "$servers" | jq '.[] | select(.status == "running") | .name'

# Use in scripts
for server in $(echo "$servers" | jq -r '.[] | select(.status == "running") | .name'); do
    echo "Processing server: $server"
    provisioning server ssh "$server" --command "uptime" --infra my-infra
done
```

## Command Chaining and Pipelines

### Sequential Operations

```text
# Chain commands with && (stop on failure)
provisioning validate config --infra my-infra && 
provisioning server create --infra my-infra --check && 
provisioning server create --infra my-infra --yes

# Chain with || (continue on failure)
provisioning taskserv create kubernetes --infra my-infra || 
echo "Kubernetes installation failed, continuing with other services"
```

### Complex Workflows

```text
# Full deployment workflow
deploy_infrastructure() {
    local infra_name=$1

    echo "Deploying infrastructure: $infra_name"

    # Validate
    provisioning validate config --infra "$infra_name" || return 1

    # Create servers
    provisioning server create --infra "$infra_name" --yes --wait || return 1

    # Install base services
    for service in containerd kubernetes; do
        provisioning taskserv create "$service" --infra "$infra_name" --yes || return 1
    done

    # Deploy applications
    provisioning cluster create web-app --infra "$infra_name" --yes || return 1

    echo "Deployment completed: $infra_name"
}

# Use the function
deploy_infrastructure "production"
```

## Integration with Other Tools

### CI/CD Integration

```text
# GitLab CI example
deploy:
  script:
    - provisioning validate config --infra production
    - provisioning server create --infra production --check
    - provisioning server create --infra production --yes --wait
    - provisioning taskserv create kubernetes --infra production --yes
  only:
    - main
```

### Monitoring Integration

```text
# Health check script
#!/bin/bash

# Check infrastructure health
if provisioning health check --infra production --out json | jq -e '.healthy'; then
    echo "Infrastructure healthy"
    exit 0
else
    echo "Infrastructure unhealthy"
    # Send alert
    curl -X POST https://alerts.company.com/webhook 
        -d '{"message": "Infrastructure health check failed"}'
    exit 1
fi
```

### Backup Automation

```text
# Backup script
#!/bin/bash

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/provisioning/$DATE"

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Export configurations
provisioning config export --format yaml > "$BACKUP_DIR/config.yaml"

# Backup infrastructure definitions
for infra in $(provisioning list infras --out json | jq -r '.[]'); do
    provisioning show settings --infra "$infra" --out yaml > "$BACKUP_DIR/$infra.yaml"
done

echo "Backup completed: $BACKUP_DIR"
```

This CLI reference provides comprehensive coverage of all provisioning commands. Use it as your primary reference for command syntax, options, and
integration patterns.