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

```bash
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:

```bash
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:

```bash
provisioning help server = provisioning server help
provisioning help ws = provisioning workspace help
```

## Domain Modules

The CLI is organized into 11 domain modules:

1. **[Infrastructure](#infrastructure-commands)** - Server, provider, network management
2. **[Orchestration](#orchestration-commands)** - Workflow, batch, task execution
3. **[Configuration](#configuration-commands)** - Config validation and management
4. **[Workspace](#workspace-commands)** - Multi-workspace operations
5. **[Development](#development-commands)** - Extensions and customization
6. **[Utilities](#utility-commands)** - Tools and helpers
7. **[Generation](#generation-commands)** - Schema and config generation
8. **[Authentication](#authentication-commands)** - Auth, MFA, users
9. **[Security](#security-commands)** - Vault, KMS, audit, policies
10. **[Platform](#platform-commands)** - Service control and monitoring
11. **[Guides](#guides-commands)** - 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**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
provisioning server status web-01
provisioning server status --all
```

**`provisioning server ssh [NAM| E ID]`**

SSH into a server.

**Examples**:

```bash
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**:

```bash
provisioning provider validate upcloud
provisioning provider validate aws
```

**`provisioning provider zones <NAME>`**

List available zones for a provider.

**Examples**:

```bash
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**:

```bash
# 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**:

```bash
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**:

```bash
# 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**:

```bash
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**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
provisioning workspace switch production
provisioning workspace switch dev
```

**`provisioning workspace list`**

List all workspaces.

**Flags**:

- `--format <format>` - Output format

**Examples**:

```bash
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**:

```bash
# 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**:

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

**`provisioning extension install <NAM| E PATH>`**

Install an extension from registry or file.

**Examples**:

```bash
# 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**:

```bash
provisioning version
provisioning version --check
```

**`provisioning health`**

Check platform health.

**Flags**:

- `--service <name>` - Check specific service

**Examples**:

```bash
# Check all services
provisioning health

# Check specific service
provisioning health --service orchestrator
```

**`provisioning diagnostics`**

Run platform diagnostics.

**Flags**:

- `--output <path>` - Save diagnostic report

**Examples**:

```bash
provisioning diagnostics --output diagnostics.json
```

**`provisioning setup versions`**

Generate versions file from Nickel schemas.

**Examples**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
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**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
# 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**:

```bash
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**:

```bash
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**:

```bash
# 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**:

```bash
# 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**:

```bash
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**:

```bash
# 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**:

```bash
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**:

```bash
# 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**:

```bash
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
# 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](rest-api.md)** - HTTP API alternatives
- **[Nushell Libraries](nushell-libraries.md)** - Library functions
- **[Integration Examples](examples.md)** - Real-world usage patterns
- **[Quick Start Guide](../getting-started/quick-start.md)** - Getting started
- **[Interactive Guides](../features/interactive-guides.md)** - In-platform tutorials