jesus/provisioning
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
provisioning/docs/src/infrastructure/cli-reference.md
Jesús Pérez d0b6b9b759
chore: fix docs after fences fix
2026-01-14 04:59:11 +00:00

22 KiB
Raw Blame History

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:

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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.).

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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:

# 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

#!/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

# 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

# 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

# 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

# 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

# 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

# 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.