# CLI Reference\n\nComplete command-line reference for Infrastructure Automation. This guide covers all commands, options, and usage patterns.\n\n## What You'll Learn\n\n- Complete command syntax and options\n- All available commands and subcommands\n- Usage examples and patterns\n- Scripting and automation\n- Integration with other tools\n- Advanced command combinations\n\n## Command Structure\n\nAll provisioning commands follow this structure:\n\n```\nprovisioning [global-options] <command> [subcommand] [command-options] [arguments]\n```\n\n### Global Options\n\nThese options can be used with any command:\n\n| Option | Short | Description | Example |\n| -------- | ------- | ------------- | --------- |\n| `--infra` | `-i` | Specify infrastructure | `--infra production` |\n| `--environment` | | Environment override | `--environment prod` |\n| `--check` | `-c` | Dry run mode | `--check` |\n| `--debug` | `-x` | Enable debug output | `--debug` |\n| `--yes` | `-y` | Auto-confirm actions | `--yes` |\n| `--wait` | `-w` | Wait for completion | `--wait` |\n| `--out` | | Output format | `--out json` |\n| `--help` | `-h` | Show help | `--help` |\n\n### Output Formats\n\n| Format | Description | Use Case |\n| -------- | ------------- | ---------- |\n| `text` | Human-readable text | Terminal viewing |\n| `json` | JSON format | Scripting, APIs |\n| `yaml` | YAML format | Configuration files |\n| `toml` | TOML format | Settings files |\n| `table` | Tabular format | Reports, lists |\n\n## Core Commands\n\n### help - Show Help Information\n\nDisplay help information for the system or specific commands.\n\n```\n# General help\nprovisioning help\n\n# Command-specific help\nprovisioning help server\nprovisioning help taskserv\nprovisioning help cluster\n\n# Show all available commands\nprovisioning help --all\n\n# Show help for subcommand\nprovisioning server help create\n```\n\n**Options:**\n\n- `--all` - Show all available commands\n- `--detailed` - Show detailed help with examples\n\n### version - Show Version Information\n\nDisplay version information for the system and dependencies.\n\n```\n# Basic version\nprovisioning version\nprovisioning --version\nprovisioning -V\n\n# Detailed version with dependencies\nprovisioning version --verbose\n\n# Show version info with title\nprovisioning --info\nprovisioning -I\n```\n\n**Options:**\n\n- `--verbose` - Show detailed version information\n- `--dependencies` - Include dependency versions\n\n### env - Environment Information\n\nDisplay current environment configuration and settings.\n\n```\n# Show environment variables\nprovisioning env\n\n# Show all environment and configuration\nprovisioning allenv\n\n# Show specific environment\nprovisioning env --environment prod\n\n# Export environment\nprovisioning env --export\n```\n\n**Output includes:**\n\n- Configuration file locations\n- Environment variables\n- Provider settings\n- Path configurations\n\n## Server Management Commands\n\n### server create - Create Servers\n\nCreate new server instances based on configuration.\n\n```\n# Create all servers in infrastructure\nprovisioning server create --infra my-infra\n\n# Dry run (check mode)\nprovisioning server create --infra my-infra --check\n\n# Create with confirmation\nprovisioning server create --infra my-infra --yes\n\n# Create and wait for completion\nprovisioning server create --infra my-infra --wait\n\n# Create specific server\nprovisioning server create web-01 --infra my-infra\n\n# Create with custom settings\nprovisioning server create --infra my-infra --settings custom.ncl\n```\n\n**Options:**\n\n- `--check`, `-c` - Dry run mode (show what would be created)\n- `--yes`, `-y` - Auto-confirm creation\n- `--wait`, `-w` - Wait for servers to be fully ready\n- `--settings`, `-s` - Custom settings file\n- `--template`, `-t` - Use specific template\n\n### server delete - Delete Servers\n\nRemove server instances and associated resources.\n\n```\n# Delete all servers\nprovisioning server delete --infra my-infra\n\n# Delete with confirmation\nprovisioning server delete --infra my-infra --yes\n\n# Delete but keep storage\nprovisioning server delete --infra my-infra --keepstorage\n\n# Delete specific server\nprovisioning server delete web-01 --infra my-infra\n\n# Dry run deletion\nprovisioning server delete --infra my-infra --check\n```\n\n**Options:**\n\n- `--yes`, `-y` - Auto-confirm deletion\n- `--keepstorage` - Preserve storage volumes\n- `--force` - Force deletion even if servers are running\n\n### server list - List Servers\n\nDisplay information about servers.\n\n```\n# List all servers\nprovisioning server list --infra my-infra\n\n# List with detailed information\nprovisioning server list --infra my-infra --detailed\n\n# List in specific format\nprovisioning server list --infra my-infra --out json\n\n# List servers across all infrastructures\nprovisioning server list --all\n\n# Filter by status\nprovisioning server list --infra my-infra --status running\n```\n\n**Options:**\n\n- `--detailed` - Show detailed server information\n- `--status` - Filter by server status\n- `--all` - Show servers from all infrastructures\n\n### server ssh - SSH Access\n\nConnect to servers via SSH.\n\n```\n# SSH to server\nprovisioning server ssh web-01 --infra my-infra\n\n# SSH with specific user\nprovisioning server ssh web-01 --user admin --infra my-infra\n\n# SSH with custom key\nprovisioning server ssh web-01 --key ~/.ssh/custom_key --infra my-infra\n\n# Execute single command\nprovisioning server ssh web-01 --command "systemctl status nginx" --infra my-infra\n```\n\n**Options:**\n\n- `--user` - SSH username (default from configuration)\n- `--key` - SSH private key file\n- `--command` - Execute command and exit\n- `--port` - SSH port (default: 22)\n\n### server price - Cost Information\n\nDisplay pricing information for servers.\n\n```\n# Show costs for all servers\nprovisioning server price --infra my-infra\n\n# Show detailed cost breakdown\nprovisioning server price --infra my-infra --detailed\n\n# Show monthly estimates\nprovisioning server price --infra my-infra --monthly\n\n# Cost comparison between providers\nprovisioning server price --infra my-infra --compare\n```\n\n**Options:**\n\n- `--detailed` - Detailed cost breakdown\n- `--monthly` - Monthly cost estimates\n- `--compare` - Compare costs across providers\n\n## Task Service Commands\n\n### taskserv create - Install Services\n\nInstall and configure task services on servers.\n\n```\n# Install service on all eligible servers\nprovisioning taskserv create kubernetes --infra my-infra\n\n# Install with check mode\nprovisioning taskserv create kubernetes --infra my-infra --check\n\n# Install specific version\nprovisioning taskserv create kubernetes --version 1.28 --infra my-infra\n\n# Install on specific servers\nprovisioning taskserv create postgresql --servers db-01,db-02 --infra my-infra\n\n# Install with custom configuration\nprovisioning taskserv create kubernetes --config k8s-config.yaml --infra my-infra\n```\n\n**Options:**\n\n- `--version` - Specific version to install\n- `--config` - Custom configuration file\n- `--servers` - Target specific servers\n- `--force` - Force installation even if conflicts exist\n\n### taskserv delete - Remove Services\n\nRemove task services from servers.\n\n```\n# Remove service\nprovisioning taskserv delete kubernetes --infra my-infra\n\n# Remove with data cleanup\nprovisioning taskserv delete postgresql --cleanup-data --infra my-infra\n\n# Remove from specific servers\nprovisioning taskserv delete nginx --servers web-01,web-02 --infra my-infra\n\n# Dry run removal\nprovisioning taskserv delete kubernetes --infra my-infra --check\n```\n\n**Options:**\n\n- `--cleanup-data` - Remove associated data\n- `--servers` - Target specific servers\n- `--force` - Force removal\n\n### taskserv list - List Services\n\nDisplay available and installed task services.\n\n```\n# List all available services\nprovisioning taskserv list\n\n# List installed services\nprovisioning taskserv list --infra my-infra --installed\n\n# List by category\nprovisioning taskserv list --category database\n\n# List with versions\nprovisioning taskserv list --versions\n\n# Search services\nprovisioning taskserv list --search kubernetes\n```\n\n**Options:**\n\n- `--installed` - Show only installed services\n- `--category` - Filter by service category\n- `--versions` - Include version information\n- `--search` - Search by name or description\n\n### taskserv generate - Generate Configurations\n\nGenerate configuration files for task services.\n\n```\n# Generate configuration\nprovisioning taskserv generate kubernetes --infra my-infra\n\n# Generate with custom template\nprovisioning taskserv generate kubernetes --template custom --infra my-infra\n\n# Generate for specific servers\nprovisioning taskserv generate nginx --servers web-01,web-02 --infra my-infra\n\n# Generate and save to file\nprovisioning taskserv generate postgresql --output db-config.yaml --infra my-infra\n```\n\n**Options:**\n\n- `--template` - Use specific template\n- `--output` - Save to specific file\n- `--servers` - Target specific servers\n\n### taskserv check-updates - Version Management\n\nCheck for and manage service version updates.\n\n```\n# Check updates for all services\nprovisioning taskserv check-updates --infra my-infra\n\n# Check specific service\nprovisioning taskserv check-updates kubernetes --infra my-infra\n\n# Show available versions\nprovisioning taskserv versions kubernetes\n\n# Update to latest version\nprovisioning taskserv update kubernetes --infra my-infra\n\n# Update to specific version\nprovisioning taskserv update kubernetes --version 1.29 --infra my-infra\n```\n\n**Options:**\n\n- `--version` - Target specific version\n- `--security-only` - Only security updates\n- `--dry-run` - Show what would be updated\n\n## Cluster Management Commands\n\n### cluster create - Deploy Clusters\n\nDeploy and configure application clusters.\n\n```\n# Create cluster\nprovisioning cluster create web-cluster --infra my-infra\n\n# Create with check mode\nprovisioning cluster create web-cluster --infra my-infra --check\n\n# Create with custom configuration\nprovisioning cluster create web-cluster --config cluster.yaml --infra my-infra\n\n# Create and scale immediately\nprovisioning cluster create web-cluster --replicas 5 --infra my-infra\n```\n\n**Options:**\n\n- `--config` - Custom cluster configuration\n- `--replicas` - Initial replica count\n- `--namespace` - Kubernetes namespace\n\n### cluster delete - Remove Clusters\n\nRemove application clusters and associated resources.\n\n```\n# Delete cluster\nprovisioning cluster delete web-cluster --infra my-infra\n\n# Delete with data cleanup\nprovisioning cluster delete web-cluster --cleanup --infra my-infra\n\n# Force delete\nprovisioning cluster delete web-cluster --force --infra my-infra\n```\n\n**Options:**\n\n- `--cleanup` - Remove associated data\n- `--force` - Force deletion\n- `--keep-volumes` - Preserve persistent volumes\n\n### cluster list - List Clusters\n\nDisplay information about deployed clusters.\n\n```\n# List all clusters\nprovisioning cluster list --infra my-infra\n\n# List with status\nprovisioning cluster list --infra my-infra --status\n\n# List across all infrastructures\nprovisioning cluster list --all\n\n# Filter by namespace\nprovisioning cluster list --namespace production --infra my-infra\n```\n\n**Options:**\n\n- `--status` - Include status information\n- `--all` - Show clusters from all infrastructures\n- `--namespace` - Filter by namespace\n\n### cluster scale - Scale Clusters\n\nAdjust cluster size and resources.\n\n```\n# Scale cluster\nprovisioning cluster scale web-cluster --replicas 10 --infra my-infra\n\n# Auto-scale configuration\nprovisioning cluster scale web-cluster --auto-scale --min 3 --max 20 --infra my-infra\n\n# Scale specific component\nprovisioning cluster scale web-cluster --component api --replicas 5 --infra my-infra\n```\n\n**Options:**\n\n- `--replicas` - Target replica count\n- `--auto-scale` - Enable auto-scaling\n- `--min`, `--max` - Auto-scaling limits\n- `--component` - Scale specific component\n\n## Infrastructure Commands\n\n### generate - Generate Configurations\n\nGenerate infrastructure and configuration files.\n\n```\n# Generate new infrastructure\nprovisioning generate infra --new my-infrastructure\n\n# Generate from template\nprovisioning generate infra --template web-app --name my-app\n\n# Generate server configurations\nprovisioning generate server --infra my-infra\n\n# Generate task service configurations\nprovisioning generate taskserv --infra my-infra\n\n# Generate cluster configurations\nprovisioning generate cluster --infra my-infra\n```\n\n**Subcommands:**\n\n- `infra` - Infrastructure configurations\n- `server` - Server configurations\n- `taskserv` - Task service configurations\n- `cluster` - Cluster configurations\n\n**Options:**\n\n- `--new` - Create new infrastructure\n- `--template` - Use specific template\n- `--name` - Name for generated resources\n- `--output` - Output directory\n\n### show - Display Information\n\nShow detailed information about infrastructure components.\n\n```\n# Show settings\nprovisioning show settings --infra my-infra\n\n# Show servers\nprovisioning show servers --infra my-infra\n\n# Show specific server\nprovisioning show servers web-01 --infra my-infra\n\n# Show task services\nprovisioning show taskservs --infra my-infra\n\n# Show costs\nprovisioning show costs --infra my-infra\n\n# Show in different format\nprovisioning show servers --infra my-infra --out json\n```\n\n**Subcommands:**\n\n- `settings` - Configuration settings\n- `servers` - Server information\n- `taskservs` - Task service information\n- `costs` - Cost information\n- `data` - Raw infrastructure data\n\n### list - List Resources\n\nList resource types (servers, networks, volumes, etc.).\n\n```\n# List providers\nprovisioning list providers\n\n# List task services\nprovisioning list taskservs\n\n# List clusters\nprovisioning list clusters\n\n# List infrastructures\nprovisioning list infras\n\n# List with selection interface\nprovisioning list servers --select\n```\n\n**Subcommands:**\n\n- `providers` - Available providers\n- `taskservs` - Available task services\n- `clusters` - Available clusters\n- `infras` - Available infrastructures\n- `servers` - Server instances\n\n### validate - Validate Configuration\n\nValidate configuration files and infrastructure definitions.\n\n```\n# Validate configuration\nprovisioning validate config --infra my-infra\n\n# Validate with detailed output\nprovisioning validate config --detailed --infra my-infra\n\n# Validate specific file\nprovisioning validate config settings.ncl --infra my-infra\n\n# Quick validation\nprovisioning validate quick --infra my-infra\n\n# Validate interpolation\nprovisioning validate interpolation --infra my-infra\n```\n\n**Subcommands:**\n\n- `config` - Configuration validation\n- `quick` - Quick infrastructure validation\n- `interpolation` - Interpolation pattern validation\n\n**Options:**\n\n- `--detailed` - Show detailed validation results\n- `--strict` - Strict validation mode\n- `--rules` - Show validation rules\n\n## Configuration Commands\n\n### init - Initialize Configuration\n\nInitialize user and project configurations.\n\n```\n# Initialize user configuration\nprovisioning init config\n\n# Initialize with specific template\nprovisioning init config dev\n\n# Initialize project configuration\nprovisioning init project\n\n# Force overwrite existing\nprovisioning init config --force\n```\n\n**Subcommands:**\n\n- `config` - User configuration\n- `project` - Project configuration\n\n**Options:**\n\n- `--template` - Configuration template\n- `--force` - Overwrite existing files\n\n### template - Template Management\n\nManage configuration templates.\n\n```\n# List available templates\nprovisioning template list\n\n# Show template content\nprovisioning template show dev\n\n# Validate templates\nprovisioning template validate\n\n# Create custom template\nprovisioning template create my-template --from dev\n```\n\n**Subcommands:**\n\n- `list` - List available templates\n- `show` - Display template content\n- `validate` - Validate templates\n- `create` - Create custom template\n\n## Advanced Commands\n\n### nu - Interactive Shell\n\nStart interactive Nushell session with provisioning library loaded.\n\n```\n# Start interactive shell\nprovisioning nu\n\n# Execute specific command\nprovisioning nu -c "use lib_provisioning *; show_env"\n\n# Start with custom script\nprovisioning nu --script my-script.nu\n```\n\n**Options:**\n\n- `-c` - Execute command and exit\n- `--script` - Run specific script\n- `--load` - Load additional modules\n\n### sops - Secret Management\n\nEdit encrypted configuration files using SOPS.\n\n```\n# Edit encrypted file\nprovisioning sops settings.ncl --infra my-infra\n\n# Encrypt new file\nprovisioning sops --encrypt new-secrets.ncl --infra my-infra\n\n# Decrypt for viewing\nprovisioning sops --decrypt secrets.ncl --infra my-infra\n\n# Rotate keys\nprovisioning sops --rotate-keys secrets.ncl --infra my-infra\n```\n\n**Options:**\n\n- `--encrypt` - Encrypt file\n- `--decrypt` - Decrypt file\n- `--rotate-keys` - Rotate encryption keys\n\n### context - Context Management\n\nManage infrastructure contexts and environments.\n\n```\n# Show current context\nprovisioning context\n\n# List available contexts\nprovisioning context list\n\n# Switch context\nprovisioning context switch production\n\n# Create new context\nprovisioning context create staging --from development\n\n# Delete context\nprovisioning context delete old-context\n```\n\n**Subcommands:**\n\n- `list` - List contexts\n- `switch` - Switch active context\n- `create` - Create new context\n- `delete` - Delete context\n\n## Workflow Commands\n\n### workflows - Batch Operations\n\nManage complex workflows and batch operations.\n\n```\n# Submit batch workflow\nprovisioning workflows batch submit my-workflow.ncl\n\n# Monitor workflow progress\nprovisioning workflows batch monitor workflow-123\n\n# List workflows\nprovisioning workflows batch list --status running\n\n# Get workflow status\nprovisioning workflows batch status workflow-123\n\n# Rollback failed workflow\nprovisioning workflows batch rollback workflow-123\n```\n\n**Options:**\n\n- `--status` - Filter by workflow status\n- `--follow` - Follow workflow progress\n- `--timeout` - Set timeout for operations\n\n### orchestrator - Orchestrator Management\n\nControl the hybrid orchestrator system.\n\n```\n# Start orchestrator\nprovisioning orchestrator start\n\n# Check orchestrator status\nprovisioning orchestrator status\n\n# Stop orchestrator\nprovisioning orchestrator stop\n\n# Show orchestrator logs\nprovisioning orchestrator logs\n\n# Health check\nprovisioning orchestrator health\n```\n\n## Scripting and Automation\n\n### Exit Codes\n\nProvisioning uses standard exit codes:\n\n- `0` - Success\n- `1` - General error\n- `2` - Invalid command or arguments\n- `3` - Configuration error\n- `4` - Permission denied\n- `5` - Resource not found\n\n### Environment Variables\n\nControl behavior through environment variables:\n\n```\n# Enable debug mode\nexport PROVISIONING_DEBUG=true\n\n# Set environment\nexport PROVISIONING_ENV=production\n\n# Set output format\nexport PROVISIONING_OUTPUT_FORMAT=json\n\n# Disable interactive prompts\nexport PROVISIONING_NONINTERACTIVE=true\n```\n\n### Batch Operations\n\n```\n#!/bin/bash\n# Example batch script\n\n# Set environment\nexport PROVISIONING_ENV=production\nexport PROVISIONING_NONINTERACTIVE=true\n\n# Validate first\nif ! provisioning validate config --infra production; then\n    echo "Configuration validation failed"\n    exit 1\nfi\n\n# Create infrastructure\nprovisioning server create --infra production --yes --wait\n\n# Install services\nprovisioning taskserv create kubernetes --infra production --yes\nprovisioning taskserv create postgresql --infra production --yes\n\n# Deploy clusters\nprovisioning cluster create web-app --infra production --yes\n\necho "Deployment completed successfully"\n```\n\n### JSON Output Processing\n\n```\n# Get server list as JSON\nservers=$(provisioning server list --infra my-infra --out json)\n\n# Process with jq\necho "$servers" | jq '.[] | select(.status == "running") | .name'\n\n# Use in scripts\nfor server in $(echo "$servers" | jq -r '.[] | select(.status == "running") | .name'); do\n    echo "Processing server: $server"\n    provisioning server ssh "$server" --command "uptime" --infra my-infra\ndone\n```\n\n## Command Chaining and Pipelines\n\n### Sequential Operations\n\n```\n# Chain commands with && (stop on failure)\nprovisioning validate config --infra my-infra && \\nprovisioning server create --infra my-infra --check && \\nprovisioning server create --infra my-infra --yes\n\n# Chain with || (continue on failure)\nprovisioning taskserv create kubernetes --infra my-infra || \\necho "Kubernetes installation failed, continuing with other services"\n```\n\n### Complex Workflows\n\n```\n# Full deployment workflow\ndeploy_infrastructure() {\n    local infra_name=$1\n\n    echo "Deploying infrastructure: $infra_name"\n\n    # Validate\n    provisioning validate config --infra "$infra_name" || return 1\n\n    # Create servers\n    provisioning server create --infra "$infra_name" --yes --wait || return 1\n\n    # Install base services\n    for service in containerd kubernetes; do\n        provisioning taskserv create "$service" --infra "$infra_name" --yes || return 1\n    done\n\n    # Deploy applications\n    provisioning cluster create web-app --infra "$infra_name" --yes || return 1\n\n    echo "Deployment completed: $infra_name"\n}\n\n# Use the function\ndeploy_infrastructure "production"\n```\n\n## Integration with Other Tools\n\n### CI/CD Integration\n\n```\n# GitLab CI example\ndeploy:\n  script:\n    - provisioning validate config --infra production\n    - provisioning server create --infra production --check\n    - provisioning server create --infra production --yes --wait\n    - provisioning taskserv create kubernetes --infra production --yes\n  only:\n    - main\n```\n\n### Monitoring Integration\n\n```\n# Health check script\n#!/bin/bash\n\n# Check infrastructure health\nif provisioning health check --infra production --out json | jq -e '.healthy'; then\n    echo "Infrastructure healthy"\n    exit 0\nelse\n    echo "Infrastructure unhealthy"\n    # Send alert\n    curl -X POST https://alerts.company.com/webhook \\n        -d '{"message": "Infrastructure health check failed"}'\n    exit 1\nfi\n```\n\n### Backup Automation\n\n```\n# Backup script\n#!/bin/bash\n\nDATE=$(date +%Y%m%d_%H%M%S)\nBACKUP_DIR="/backups/provisioning/$DATE"\n\n# Create backup directory\nmkdir -p "$BACKUP_DIR"\n\n# Export configurations\nprovisioning config export --format yaml > "$BACKUP_DIR/config.yaml"\n\n# Backup infrastructure definitions\nfor infra in $(provisioning list infras --out json | jq -r '.[]'); do\n    provisioning show settings --infra "$infra" --out yaml > "$BACKUP_DIR/$infra.yaml"\ndone\n\necho "Backup completed: $BACKUP_DIR"\n```\n\nThis CLI reference provides comprehensive coverage of all provisioning commands. Use it as your primary reference for command syntax, options, and\nintegration patterns.
