pulumi-cli

name

pulumi-cli

description

Use for hands-on Pulumi CLI work: running deployments, fixing broken stacks, and managing infrastructure state. Handles: recovering from stuck or interrupted `pulumi up` with pending operations, cleaning orphaned resources from state after out-of-band cloud deletions, protecting critical resources from accidental `pulumi destroy`, moving resources between stacks without recreating them, targeting specific resources during deployment, migrating between backends (local file to Pulumi Cloud, S3), stack lifecycle management, state export/import/repair, CI/CD pipeline setup, and importing existing cloud resources. Use this skill — not the language-specific Pulumi skills — whenever the user's question is about operating, troubleshooting, or recovering Pulumi infrastructure rather than writing program code.

Pulumi CLI Skill

Quick Command Reference

Deployment Workflow

# 1. Create new project
pulumi new typescript                    # Interactive
pulumi new aws-typescript --name myapp --stack dev --yes  # Non-interactive

# 2. Preview changes
pulumi preview                           # Interactive preview
pulumi preview --diff                    # Show detailed diff

# 3. Deploy
pulumi up                                # Interactive deployment
pulumi up --yes                          # Non-interactive
pulumi up --skip-preview --yes           # Skip preview step

# 4. View outputs
pulumi stack output
pulumi stack output --json

# 5. Tear down
pulumi destroy --yes

Stack Management

# List stacks
pulumi stack ls

# Create and select stacks
pulumi stack init dev
pulumi stack select prod

# View stack info
pulumi stack
pulumi stack history

# Stack outputs
pulumi stack output
pulumi stack output bucketName --show-secrets

# Remove stack
pulumi stack rm dev --yes

State Operations

# Refresh state from cloud
pulumi refresh --yes

# Export/import state
pulumi stack export --file backup.json
pulumi stack import --file backup.json

# Delete resource from state (keeps cloud resource)
pulumi state delete 'urn:pulumi:dev::myproject::aws:s3/bucket:Bucket::my-bucket'

# Move resource between stacks (preferred over delete+import)
# This is a single atomic operation that transfers state without touching cloud resources
pulumi state move --source dev --dest prod 'urn:...'

# Protect critical resources
pulumi state protect 'urn:...'

Configuration

# Set config values
pulumi config set aws:region us-west-2
pulumi config set dbPassword secret --secret

# Get config
pulumi config get aws:region
pulumi config                            # List all

# Link ESC environment (see language-specific skills for ESC details)
pulumi config env add myorg/myproject-dev

Common Flags

Flag	Description
--yes / -y	Skip confirmation prompts
--stack / -s	Specify stack name
--parallel / -p	Limit concurrent operations
--target	Target specific resource URNs
--refresh	Refresh state before operation
--diff	Show detailed diff
--json	Output in JSON format
--skip-preview	Skip preview step
--suppress-outputs	Hide stack outputs

CI/CD Quick Setup

These three environment variables are essential for non-interactive Pulumi in CI/CD — without PULUMI_CI=true, Pulumi may prompt for input and hang your pipeline:

# Required environment variables (all three are important)
export PULUMI_ACCESS_TOKEN=pul-xxx    # Authentication token
export PULUMI_CI=true                  # Disables interactive prompts
export PULUMI_SKIP_UPDATE_CHECK=true   # Avoids update check delays

# Typical CI workflow
pulumi login                           # Authenticates via PULUMI_ACCESS_TOKEN
pulumi stack select prod               # Select target stack explicitly
pulumi preview                         # Always preview before deploying
pulumi up --yes                        # --yes for non-interactive confirmation

Importing Existing Resources

# Import single resource
pulumi import aws:s3/bucket:Bucket my-bucket existing-bucket-name

# Bulk import from file
pulumi import --file resources.json

resources.json format:

{
  "resources": [
    {"type": "aws:s3/bucket:Bucket", "name": "my-bucket", "id": "existing-bucket-name"}
  ]
}

State Recovery Patterns

Resource deleted outside Pulumi

pulumi refresh --yes
# Or manually remove from state:
pulumi state delete 'urn:pulumi:dev::myproject::aws:s3/bucket:Bucket::deleted-bucket'

Stuck pending operations

pulumi refresh --clear-pending-creates --yes
# Or:
pulumi cancel --yes
pulumi state repair

State corruption

# Backup current state
pulumi stack export --file current.json

# Try repair
pulumi state repair

# Or restore from history
pulumi stack export --version <previous-version> --file good.json
pulumi stack import --file good.json

URN Format

urn:pulumi:<stack>::<project>::<type>::<name>

Example:
urn:pulumi:dev::myproject::aws:s3/bucket:Bucket::my-bucket

Backend Options

# Pulumi Cloud (default)
pulumi login

# Self-hosted backends
pulumi login s3://my-bucket
pulumi login azblob://my-container
pulumi login gs://my-bucket
pulumi login file://~/.pulumi-state

References

• references/pulumi-cli-commands.md - Complete command documentation
• references/pulumi-state-management.md - State operations and recovery
• references/pulumi-environment-variables.md - CI/CD environment variables