CLI Reference

Complete command-line reference for the project-planton CLI.

Command Tree

project-planton
├── apply               Deploy infrastructure (unified, auto-detects provisioner)
├── destroy             Teardown infrastructure (or 'delete')
├── init                Initialize backend/stack (unified, auto-detects provisioner)
├── plan                Preview changes (or 'preview', unified, auto-detects provisioner)
├── refresh             Sync state with reality (unified, auto-detects provisioner)
├── pulumi              Manage infrastructure with Pulumi
│   ├── init           Initialize Pulumi stack
│   ├── preview        Preview infrastructure changes
│   ├── up             Deploy infrastructure (or 'update')
│   ├── refresh        Sync state with cloud reality
│   ├── destroy        Teardown infrastructure
│   ├── delete         Remove stack metadata (or 'rm')
│   └── cancel         Cancel ongoing Pulumi operation
├── tofu                Manage infrastructure with OpenTofu
│   ├── init           Initialize backend and providers
│   ├── plan           Preview infrastructure changes
│   ├── apply          Deploy infrastructure
│   ├── refresh        Sync state with cloud reality
│   └── destroy        Teardown infrastructure
├── validate            Validate manifest against schema
├── load-manifest       Load and display manifest with defaults
└── version             Show CLI version

Top-Level Commands

apply

NEW! Unified kubectl-style command to deploy infrastructure by automatically detecting the provisioner from the manifest label project-planton.org/provisioner.

Usage:

project-planton apply -f <file> [flags]
# or
project-planton apply -f <file> [flags]

Example:

# Auto-detect provisioner from manifest
project-planton apply -f database.yaml

# With kustomize
project-planton apply --kustomize-dir services/api --overlay prod

# With overrides
project-planton apply -f api.yaml --set spec.replicas=5

How it works:

1. Reads the project-planton.org/provisioner label from your manifest
2. Automatically routes to the appropriate provisioner (pulumi/tofu/terraform)
3. If label is missing, prompts you to select a provisioner interactively (defaults to Pulumi)

Supported provisioners: pulumi, tofu, terraform (case-insensitive)

destroy

NEW! Unified kubectl-style command to destroy infrastructure. Works exactly like apply but tears down resources instead.

Aliases: delete (for kubectl compatibility)

Usage:

project-planton destroy -f <file> [flags]
project-planton delete -f <file> [flags]

Example:

# Auto-detect provisioner from manifest
project-planton destroy -f database.yaml

# Using kubectl-style delete alias
project-planton delete -f database.yaml

# With auto-approve (skips confirmation)
project-planton destroy -f api.yaml --auto-approve

init

NEW! Unified command to initialize infrastructure backend or stack by automatically detecting the provisioner.

Usage:

project-planton init -f <file> [flags]

Example:

# Auto-detect provisioner from manifest
project-planton init -f database.yaml

# With kustomize
project-planton init --kustomize-dir services/api --overlay prod

# With tofu-specific backend config
project-planton init -f app.yaml --backend-type s3 --backend-config bucket=my-bucket

How it works:

1. Reads the project-planton.org/provisioner label from your manifest
2. Routes to appropriate initialization:
   • Pulumi: Creates stack if it doesn't exist
   • Tofu: Initializes backend and downloads providers
   • Terraform: Not yet implemented

plan

NEW! Unified command to preview infrastructure changes without applying them.

Aliases: preview (for Pulumi-style experience)

Usage:

project-planton plan -f <file> [flags]
project-planton preview -f <file> [flags]

Example:

# Auto-detect provisioner and preview changes
project-planton plan -f database.yaml

# Using preview alias (Pulumi-style)
project-planton preview -f database.yaml

# With kustomize
project-planton plan --kustomize-dir services/api --overlay staging

# Preview destroy plan (Tofu)
project-planton plan -f app.yaml --destroy

How it works:

1. Reads the project-planton.org/provisioner label from your manifest
2. Routes to appropriate preview operation:
   • Pulumi: Runs pulumi preview
   • Tofu: Runs tofu plan
   • Terraform: Not yet implemented

refresh

NEW! Unified command to sync state with cloud reality without modifying resources.

Usage:

project-planton refresh -f <file> [flags]

Example:

# Auto-detect provisioner and refresh state
project-planton refresh -f database.yaml

# With kustomize
project-planton refresh --kustomize-dir services/api --overlay prod

# Show detailed diffs (Pulumi)
project-planton refresh -f app.yaml --diff

How it works:

1. Queries your cloud provider for current resource state
2. Updates state file to reflect reality
3. Does NOT modify any cloud resources (read-only operation)
4. Routes based on provisioner:
   • Pulumi: Runs pulumi refresh
   • Tofu: Runs tofu refresh
   • Terraform: Not yet implemented

pulumi

Manage infrastructure using Pulumi as the IaC engine.

Subcommands: init, preview, up/update, refresh, destroy, delete/rm, cancel

Documentation: See Pulumi Commands Reference

Example:

project-planton pulumi up -f database.yaml

tofu

Manage infrastructure using OpenTofu/Terraform as the IaC engine.

Subcommands: init, plan, apply, refresh, destroy

Documentation: See OpenTofu Commands Reference

Example:

project-planton tofu apply -f database.yaml

validate

Validate a manifest against its Protocol Buffer schema without deploying.

Usage:

project-planton validate -f <file> [flags]

Example:

# Validate single manifest
project-planton validate -f ops/resources/database.yaml

# With kustomize
project-planton validate \
  --kustomize-dir services/api/kustomize \
  --overlay prod

# If valid: exits with code 0, no output
# If invalid: shows detailed errors, exits with code 1

Flags:

• -f <file>: Path to manifest file
• --kustomize-dir <dir>: Kustomize base directory
• --overlay <name>: Kustomize overlay name

load-manifest

Load a manifest and display it with defaults applied and overrides resolved.

Usage:

project-planton load-manifest -f <file> [flags]

Example:

# Load manifest and see defaults
project-planton load-manifest -f database.yaml

# Load with overrides
project-planton load-manifest \
  -f api.yaml \
  --set spec.replicas=5

# Load kustomize-built manifest
project-planton load-manifest \
  --kustomize-dir services/api/kustomize \
  --overlay prod

Flags: Same as validate

Output: YAML manifest with defaults filled in and overrides applied

version

Show Project Planton CLI version information.

Usage:

project-planton version

Example Output:

project-planton version: v0.1.0
git commit: a1b2c3d
built: 2025-11-11T10:30:00Z

Common Flags

These flags are available across multiple commands:

Manifest Input

-f, -f <path>
Path to manifest YAML file (local or URL). The -f shorthand is available for kubectl-style experience.

# Local file (kubectl-style)
-f ops/resources/database.yaml

# Local file (traditional)
-f ops/resources/database.yaml

# URL
-f https://raw.githubusercontent.com/myorg/manifests/main/db.yaml

--kustomize-dir <directory>
Base directory containing kustomize structure.

--kustomize-dir services/api/kustomize

--overlay <name>
Kustomize overlay environment to build (must be used with --kustomize-dir).

--overlay prod

Priority: -f > --kustomize-dir + --overlay

Execution Control

--module-dir <path>
Override IaC module directory (defaults to current directory).

--module-dir ~/projects/custom-modules/my-module

--set <key>=<value>
Override manifest field values at runtime (repeatable).

--set spec.replicas=5 \
--set spec.container.image.tag=v2.0.0

Pulumi-Specific Flags

--stack <org>/<project>/<stack>
Override stack FQDN (instead of using manifest label).

--stack my-org/my-project/dev-stack

--yes
Auto-approve operations without confirmation (Pulumi commands).

--yes

--force
Force stack removal even if resources exist (delete/rm only).

--force

OpenTofu-Specific Flags

--auto-approve
Skip interactive approval (apply and destroy commands).

--auto-approve

--destroy
Create destroy plan (plan command).

--destroy

Credential Flags

Provider credential file paths:

--aws-credential <file>
--azure-credential <file>
--gcp-credential <file>
--kubernetes-cluster <file>
--cloudflare-credential <file>
--confluent-credential <file>
--mongodb-atlas-credential <file>
--snowflake-credential <file>

Environment Variables

Respected by CLI

TF_LOG / PULUMI_LOG_LEVEL
Enable verbose logging for debugging.

export TF_LOG=DEBUG
export PULUMI_LOG_LEVEL=3

Provider Credentials

See Credentials Guide for complete list of provider-specific environment variables.

Exit Codes

Configuration Files

Manifest Download Directory

Downloaded URL manifests are cached in:

~/.project-planton/manifests/downloaded/

Module Cache

Cloned IaC modules are cached in:

~/.project-planton/modules/

Examples by Use Case

First Deployment

# Unified kubectl-style (recommended)
project-planton validate -f database.yaml
project-planton apply -f database.yaml

# Using Pulumi directly
project-planton validate -f database.yaml
project-planton pulumi up -f database.yaml

# Using OpenTofu directly
project-planton validate -f database.yaml
project-planton tofu init -f database.yaml
project-planton tofu plan -f database.yaml
project-planton tofu apply -f database.yaml

Multi-Environment Deployment

# Deploy across environments with unified command
for env in dev staging prod; do
    project-planton apply \
        --kustomize-dir services/api/kustomize \
        --overlay $env \
        --yes
done

CI/CD Deployment

# Non-interactive with dynamic values (unified command)
project-planton apply \
  -f deployment.yaml \
  --set spec.container.image.tag=$CI_COMMIT_SHA \
  --yes

Testing Local Module Changes

# Point to local module during development
project-planton pulumi preview \
  -f test.yaml \
  --module-dir ~/dev/my-module

Related Documentation

• Pulumi Commands - Detailed Pulumi command guide
• OpenTofu Commands - Detailed OpenTofu command guide
• Manifest Structure - Understanding manifests
• Credentials Guide - Setting up cloud credentials
• Advanced Usage - Power user techniques

Getting Help

Command help:

# General help
project-planton --help

# Command-specific help
project-planton pulumi --help
project-planton tofu apply --help

Found an issue? Open an issue

Need support? Check existing issues or discussions