provisioning/docs/src/api-reference/cli-commands.md

CLI Commands Reference

Complete command-line interface documentation for the Provisioning platform covering 111+ commands across 11 domain modules.

Command Structure

All commands follow the pattern:

provisioning <domain> <action> [resource] [flags]

Common Flags (available on most commands):

• --yes - Skip confirmation prompts (auto-yes)
• --check - Dry-run mode, show what would happen without executing
• --wait - Wait for async operations to complete
• --format <jso| n yam| l table> - Output format (default: table)
• --verbose - Detailed output with debug information
• --quiet - Minimal output, errors only
• --help - Show command help

Quick Reference

Shortcuts - Single-letter aliases for common domains:

provisioning s = provisioning server
provisioning t = provisioning taskserv
provisioning c = provisioning cluster
provisioning w = provisioning workspace
provisioning cfg = provisioning config
provisioning b = provisioning batch

Help Navigation - Bi-directional help system:

provisioning help server = provisioning server help
provisioning help ws = provisioning workspace help

Domain Modules

The CLI is organized into 11 domain modules:

1. Infrastructure - Server, provider, network management
2. Orchestration - Workflow, batch, task execution
3. Configuration - Config validation and management
4. Workspace - Multi-workspace operations
5. Development - Extensions and customization
6. Utilities - Tools and helpers
7. Generation - Schema and config generation
8. Authentication - Auth, MFA, users
9. Security - Vault, KMS, audit, policies
10. Platform - Service control and monitoring
11. Guides - Interactive documentation

Infrastructure Commands

Manage cloud infrastructure, servers, and resources.

Server Commands

provisioning server create [NAME]

Create a new server or servers from infrastructure configuration.

Flags:

• --infra <file> - Nickel infrastructure file
• --plan <size> - Server plan (small/medium/large/xlarge)
• --provider <name> - Cloud provider (upcloud/aws/local)
• --zone <name> - Availability zone
• --ssh-key <path> - SSH public key path
• --tags <key=value> - Server tags (repeatable)
• --yes - Skip confirmation
• --check - Dry-run mode
• --wait - Wait for server creation

Examples:

# Create server from infrastructure file
provisioning server create --infra my-cluster.ncl --yes --wait

# Create single server interactively
provisioning server create web-01 --plan medium --provider upcloud

# Check what would be created (dry-run)
provisioning server create --infra cluster.ncl --check

provisioning server delete [NAM| E ID]

Delete servers.

Flags:

• --all - Delete all servers in current infrastructure
• --force - Force deletion without cleanup
• --yes - Skip confirmation

Examples:

# Delete specific server
provisioning server delete web-01 --yes

# Delete all servers
provisioning server delete --all --yes

provisioning server list

List all servers in the current workspace.

Flags:

• --provider <name> - Filter by provider
• --state <state> - Filter by state (running/stopped/error)
• --format <format> - Output format

Examples:

# List all servers
provisioning server list

# List only running servers
provisioning server list --state running --format json

provisioning server status [NAM| E ID]

Get detailed server status.

Examples:

provisioning server status web-01
provisioning server status --all

provisioning server ssh [NAM| E ID]

SSH into a server.

Examples:

provisioning server ssh web-01
provisioning server ssh web-01 -- "systemctl status kubelet"

Provider Commands

provisioning provider list

List available cloud providers.

provisioning provider validate <NAME>

Validate provider configuration and credentials.

Examples:

provisioning provider validate upcloud
provisioning provider validate aws

provisioning provider zones <NAME>

List available zones for a provider.

Examples:

provisioning provider zones upcloud
provisioning provider zones aws --region us-east-1

Orchestration Commands

Execute workflows, batch operations, and manage tasks.

Workflow Commands

provisioning workflow submit <FILE>

Submit a workflow for execution.

Flags:

• --priority <level> - Priority (low/normal/high/critical)
• --checkpoint - Enable checkpoint recovery
• --wait - Wait for completion

Examples:

# Submit workflow and wait
provisioning workflow submit deploy.ncl --wait

# Submit with high priority
provisioning workflow submit urgent.ncl --priority high

provisioning workflow status <ID>

Get workflow execution status.

Examples:

provisioning workflow status wf-20260116-abc123

provisioning workflow list

List workflows.

Flags:

• --state <state> - Filter by state (queued/running/completed/failed)
• --limit <num> - Maximum results

Examples:

# List running workflows
provisioning workflow list --state running

# List failed workflows
provisioning workflow list --state failed --format json

provisioning workflow cancel <ID>

Cancel a running workflow.

Examples:

provisioning workflow cancel wf-20260116-abc123 --yes

provisioning workflow resume <ID>

Resume a failed workflow from checkpoint.

Flags:

• --from <checkpoint> - Resume from specific checkpoint
• --skip-failed - Skip failed tasks

Examples:

# Resume from last checkpoint
provisioning workflow resume wf-20260116-abc123

# Resume from specific checkpoint
provisioning workflow resume wf-20260116-abc123 --from create-servers

provisioning workflow logs <ID>

View workflow logs.

Flags:

• --task <id> - Show logs for specific task
• --follow - Stream logs in real-time
• --lines <num> - Number of lines (default: 100)

Examples:

# View all workflow logs
provisioning workflow logs wf-20260116-abc123

# Follow logs in real-time
provisioning workflow logs wf-20260116-abc123 --follow

# View specific task logs
provisioning workflow logs wf-20260116-abc123 --task install-k8s

Batch Commands

provisioning batch submit <FILE>

Submit a batch workflow with multiple operations.

Flags:

• --parallel <num> - Maximum parallel operations
• --wait - Wait for completion

Examples:

# Submit batch workflow
provisioning batch submit multi-region.ncl --parallel 3 --wait

provisioning batch status <ID>

Get batch workflow status with progress.

provisioning batch monitor <ID>

Monitor batch execution in real-time.

Configuration Commands

Validate and manage configuration.

provisioning config validate

Validate current configuration.

Flags:

• --infra <file> - Specific infrastructure file
• --all - Validate all configuration files

Examples:

# Validate workspace configuration
provisioning config validate

# Validate specific infrastructure
provisioning config validate --infra cluster.ncl

provisioning config show

Display effective configuration.

Flags:

• --key <path> - Show specific config value
• --format <format> - Output format

Examples:

# Show all configuration
provisioning config show

# Show specific value
provisioning config show --key paths.base

# Export as JSON
provisioning config show --format json > config.json

provisioning config reload

Reload configuration from files.

provisioning config diff

Show configuration differences between environments.

Flags:

• --from <env> - Source environment
• --to <env> - Target environment

Workspace Commands

Manage isolated workspaces.

provisioning workspace init <NAME>

Initialize a new workspace.

Flags:

• --template <name> - Workspace template
• --path <path> - Custom workspace path

Examples:

# Create workspace from default template
provisioning workspace init my-project

# Create from template
provisioning workspace init prod --template production

provisioning workspace switch <NAME>

Switch to a different workspace.

Examples:

provisioning workspace switch production
provisioning workspace switch dev

provisioning workspace list

List all workspaces.

Flags:

• --format <format> - Output format

Examples:

provisioning workspace list
provisioning workspace list --format json

provisioning workspace current

Show current active workspace.

provisioning workspace delete <NAME>

Delete a workspace.

Flags:

• --force - Force deletion without cleanup
• --yes - Skip confirmation

Development Commands

Develop custom extensions.

provisioning extension create <TYPE> <NAME>

Create a new extension.

Types: provider, taskserv, cluster, workflow

Flags:

• --template <name> - Extension template

Examples:

# Create new task service
provisioning extension create taskserv my-service

# Create new provider
provisioning extension create provider my-cloud --template basic

provisioning extension validate <PATH>

Validate extension structure and configuration.

provisioning extension package <PATH>

Package extension for distribution (OCI format).

Flags:

• --version <version> - Extension version
• --output <path> - Output file path

Examples:

provisioning extension package ./my-service --version 1.0.0

provisioning extension install <NAM| E PATH>

Install an extension from registry or file.

Examples:

# Install from registry
provisioning extension install kubernetes

# Install from local file
provisioning extension install ./my-service.tar.gz

provisioning extension list

List installed extensions.

Flags:

• --type <type> - Filter by type
• --available - Show available (not installed)

Utility Commands

Helper commands and tools.

provisioning version

Show platform version information.

Flags:

• --check - Check for updates

Examples:

provisioning version
provisioning version --check

provisioning health

Check platform health.

Flags:

• --service <name> - Check specific service

Examples:

# Check all services
provisioning health

# Check specific service
provisioning health --service orchestrator

provisioning diagnostics

Run platform diagnostics.

Flags:

• --output <path> - Save diagnostic report

Examples:

provisioning diagnostics --output diagnostics.json

provisioning setup versions

Generate versions file from Nickel schemas.

Examples:

# Generate /provisioning/core/versions file
provisioning setup versions

# Use in shell scripts
source /provisioning/core/versions
echo "Nushell version: $NU_VERSION"

Generation Commands

Generate schemas, configurations, and infrastructure code.

provisioning generate config <TYPE>

Generate configuration templates.

Types: workspace, infrastructure, provider

Flags:

• --output <path> - Output file path
• --format <format> - Output format (nickel/yaml/toml)

Examples:

# Generate workspace config
provisioning generate config workspace --output config.ncl

# Generate infrastructure template
provisioning generate config infrastructure --format nickel

provisioning generate schema <NAME>

Generate Nickel schema from existing configuration.

provisioning generate docs

Generate documentation from schemas.

Authentication Commands

Manage authentication and user accounts.

provisioning auth login

Authenticate to the platform.

Flags:

• --user <username> - Username
• --password <password> - Password (prompt if not provided)
• --mfa <code> - MFA code

Examples:

# Interactive login
provisioning auth login --user admin

# Login with MFA
provisioning auth login --user admin --mfa 123456

provisioning auth logout

Logout and invalidate tokens.

provisioning auth token

Display or refresh authentication token.

Flags:

• --refresh - Refresh the token

provisioning auth user create <USERNAME>

Create a new user (admin only).

Flags:

• --email <email> - User email
• --roles <roles> - Comma-separated roles

Examples:

provisioning auth user create developer --email [dev@example.com](mailto:dev@example.com) --roles developer,operator

provisioning auth user list

List all users (admin only).

provisioning auth user delete <USERNAME>

Delete a user (admin only).

Security Commands

Manage secrets, encryption, audit logs, and policies.

Vault Commands

provisioning vault store <PATH>

Store a secret.

Flags:

• --value <value> - Secret value
• --file <path> - Read value from file

Examples:

# Store secret interactively
provisioning vault store database/postgres/password

# Store from value
provisioning vault store api/key --value "secret-value"

# Store from file
provisioning vault store ssh/key --file ~/.ssh/id_rsa

provisioning vault get <PATH>

Retrieve a secret.

Flags:

• --version <num> - Specific version
• --output <path> - Save to file

Examples:

# Get latest secret
provisioning vault get database/postgres/password

# Get specific version
provisioning vault get database/postgres/password --version 2

provisioning vault list

List all secret paths.

Flags:

• --prefix <prefix> - Filter by path prefix

provisioning vault delete <PATH>

Delete a secret.

KMS Commands

provisioning kms encrypt <FILE>

Encrypt a file or data.

Flags:

• --key <id> - Key ID
• --output <path> - Output file

Examples:

# Encrypt file
provisioning kms encrypt config.yaml --key master-key --output config.enc

# Encrypt string
echo "sensitive data" | provisioning kms encrypt --key master-key

provisioning kms decrypt <FILE>

Decrypt encrypted data.

Flags:

• --output <path> - Output file

provisioning kms create-key <ID>

Create a new encryption key.

Flags:

• --algorithm <algo> - Algorithm (default: AES-256-GCM)

provisioning kms list-keys

List all encryption keys.

provisioning kms rotate-key <ID>

Rotate an encryption key.

Audit Commands

provisioning audit query

Query audit logs.

Flags:

• --user <user> - Filter by user
• --action <action> - Filter by action
• --resource <resource> - Filter by resource
• --start <time> - Start time
• --end <time> - End time
• --limit <num> - Maximum results

Examples:

# Query recent audit logs
provisioning audit query --limit 100

# Query specific user actions
provisioning audit query --user admin --action workflow.submit

# Query time range
provisioning audit query --start "2026-01-15" --end "2026-01-16"

provisioning audit export

Export audit logs.

Flags:

• --format <format> - Export format (json/csv/syslog/cef/splunk)
• --start <time> - Start time
• --end <time> - End time
• --output <path> - Output file

Examples:

# Export as JSON
provisioning audit export --format json --output audit.json

# Export last 7 days as CSV
provisioning audit export --format csv --start "7 days ago" --output audit.csv

provisioning audit compliance

Generate compliance report.

Flags:

• --standard <standard> - Compliance standard (gdpr/soc2/iso27001)
• --start <time> - Report start time
• --end <time> - Report end time

Policy Commands

provisioning policy create <ID>

Create an authorization policy.

Flags:

• --content <cedar> - Cedar policy content
• --file <path> - Load from file
• --description <text> - Policy description

Examples:

# Create from file
provisioning policy create developer-read --file policies/read-only.cedar

# Create inline
provisioning policy create admin-full --content "permit(principal in Role::\"admin\", action, resource);"

provisioning policy list

List all authorization policies.

provisioning policy evaluate

Evaluate a policy decision.

Flags:

• --principal <entity> - Principal entity
• --action <action> - Action
• --resource <resource> - Resource

Examples:

provisioning policy evaluate \
  --principal "User::\"admin\"" \
  --action "Action::\"workflow.submit\"" \
  --resource "Workflow::\"deploy\""

provisioning policy update <ID>

Update an existing policy (hot reload).

provisioning policy delete <ID>

Delete an authorization policy.

Platform Commands

Control platform services.

provisioning platform service list

List all platform services and status.

provisioning platform service start <NAME>

Start a platform service.

Examples:

provisioning platform service start orchestrator

provisioning platform service stop <NAME>

Stop a platform service.

Flags:

• --force - Force stop without graceful shutdown
• --timeout <seconds> - Graceful shutdown timeout

provisioning platform service restart <NAME>

Restart a platform service.

provisioning platform service health <NAME>

Check service health.

provisioning platform metrics

Display platform-wide metrics.

Flags:

• --watch - Continuously update metrics

Guides Commands

Access interactive guides and documentation.

provisioning guide from-scratch

Complete walkthrough from installation to first deployment.

provisioning guide update

Guide for updating the platform.

provisioning guide customize

Guide for customizing extensions.

provisioning sc

Quick reference shortcut guide (fastest).

provisioning help [COMMAND]

Display help for any command.

Examples:

# General help
provisioning help

# Command-specific help
provisioning help server create
provisioning server create --help  # Same result

Task Service Commands

provisioning taskserv install <NAME>

Install a task service on servers.

Flags:

• --cluster <name> - Target cluster
• --version <version> - Specific version
• --servers <names> - Target servers (comma-separated)
• --wait - Wait for installation
• --yes - Skip confirmation

Examples:

# Install Kubernetes on cluster
provisioning taskserv install kubernetes --cluster prod --wait

# Install specific version
provisioning taskserv install kubernetes --version 1.29.0

# Install on specific servers
provisioning taskserv install containerd --servers web-01,web-02

provisioning taskserv remove <NAME>

Remove a task service.

Flags:

• --cluster <name> - Target cluster
• --purge - Remove all data
• --yes - Skip confirmation

provisioning taskserv list

List installed task services.

Flags:

• --available - Show available (not installed) services

provisioning taskserv status <NAME>

Get task service status.

Examples:

provisioning taskserv status kubernetes

Cluster Commands

provisioning cluster create <NAME>

Create a complete cluster from configuration.

Flags:

• --infra <file> - Nickel infrastructure file
• --type <type> - Cluster type (kubernetes/etcd/postgres)
• --wait - Wait for creation
• --yes - Skip confirmation
• --check - Dry-run mode

Examples:

# Create Kubernetes cluster
provisioning cluster create prod-k8s --infra k8s-cluster.ncl --wait

# Check what would be created
provisioning cluster create staging --infra staging.ncl --check

provisioning cluster delete <NAME>

Delete a cluster and all resources.

Flags:

• --keep-data - Preserve data volumes
• --yes - Skip confirmation

provisioning cluster list

List all clusters.

provisioning cluster status <NAME>

Get detailed cluster status.

Examples:

provisioning cluster status prod-k8s

provisioning cluster scale <NAME>

Scale cluster nodes.

Flags:

• --workers <num> - Number of worker nodes
• --control-plane <num> - Number of control plane nodes

Examples:

# Scale workers to 5 nodes
provisioning cluster scale prod-k8s --workers 5

Test Commands

provisioning test quick <TASKSERV>

Quick test of a task service in container.

Examples:

provisioning test quick kubernetes
provisioning test quick postgres

provisioning test topology load <NAME>

Load a test topology template.

provisioning test env create

Create a test environment.

Flags:

• --topology <name> - Topology template
• --services <names> - Services to install

provisioning test env list

List active test environments.

provisioning test env cleanup <ID>

Cleanup a test environment.

Environment Variables

The CLI respects these environment variables:

• PROVISIONING_WORKSPACE - Override active workspace
• PROVISIONING_CONFIG - Custom config file path
• PROVISIONING_LOG_LEVEL - Log level (debug/info/warn/error)
• PROVISIONING_API_URL - API endpoint URL
• PROVISIONING_TOKEN - Auth token (overrides login)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid usage
3	Configuration error
4	Authentication error
5	Permission denied
6	Resource not found
7	Operation failed
8	Timeout

Shell Completion

Generate shell completion scripts:

# Bash
provisioning completion bash > /etc/bash_completion.d/provisioning

# Zsh
provisioning completion zsh > ~/.zsh/completion/_provisioning

# Fish
provisioning completion fish > ~/.config/fish/completions/provisioning.fish

Related Documentation

• REST API Reference - HTTP API alternatives
• Nushell Libraries - Library functions
• Integration Examples - Real-world usage patterns
• Quick Start Guide - Getting started
• Interactive Guides - In-platform tutorials