Running Commands with pulumi env run

This guide shows you how to use pulumi env run to inject secrets and configuration from ESC environments into any command or script as environment variables.

Prerequisites

• Pulumi CLI installed
• Pulumi account created
• An ESC environment with values (see Managing secrets)

Basic usage

The pulumi env run command opens an ESC environment, exports values as environment variables, and runs a command with those variables:

pulumi env run <org>/<project>/<env-name> -- <command>

For example, if your environment contains:

values:
  environmentVariables:
    DATABASE_URL: postgres://localhost/mydb
    API_KEY:
      fn::secret: my-api-key-123

Run a script with these variables:

pulumi env run my-org/my-project/dev -- node app.js

The app.js script will have access to DATABASE_URL and API_KEY as environment variables.

Using the environmentVariables block

ESC exports values to environment variables using the environmentVariables block:

values:
  database:
    host: db.example.com
    password:
      fn::secret: db-password-123

  environmentVariables:
    DB_HOST: ${database.host}
    DB_PASSWORD: ${database.password}

The environmentVariables block:

• Maps ESC values to environment variable names
• Uses interpolation (${...}) to reference other values
• Automatically includes secrets (they’re revealed when the environment is opened)

Common patterns

Running cloud CLI commands

Inject cloud credentials into CLI commands:

values:
  aws:
    login:
      fn::open::aws-login:
        oidc:
          roleArn: arn:aws:iam::123456789012:role/my-role
          sessionName: esc-session

  environmentVariables:
    AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
    AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
    AWS_SESSION_TOKEN: ${aws.login.sessionToken}

Run AWS CLI commands:

pulumi env run my-org/my-project/aws-prod -- aws s3 ls
pulumi env run my-org/my-project/aws-prod -- aws ec2 describe-instances

The same pattern works for other cloud CLIs:

pulumi env run my-org/my-project/azure-prod -- az vm list
pulumi env run my-org/my-project/gcp-prod -- gcloud compute instances list

Running tests with secrets

Configure test environments with secrets:

values:
  environmentVariables:
    TEST_DATABASE_URL: postgres://localhost/test_db
    TEST_API_KEY:
      fn::secret: test-api-key
    TEST_WEBHOOK_SECRET:
      fn::secret: test-webhook-secret

Run tests:

pulumi env run my-org/my-project/test -- npm test
pulumi env run my-org/my-project/test -- pytest
pulumi env run my-org/my-project/test -- go test ./...

Running deployment scripts

Inject credentials for deployment scripts:

values:
  environmentVariables:
    DEPLOY_TOKEN:
      fn::secret: github-deploy-token
    DOCKER_REGISTRY: myregistry.azurecr.io
    DOCKER_USERNAME: myuser
    DOCKER_PASSWORD:
      fn::secret: registry-password

Run deployment:

pulumi env run my-org/my-project/prod -- ./deploy.sh

Running interactive shells

Start a shell session with environment variables loaded:

pulumi env run my-org/my-project/dev -- bash

All environment variables from the ESC environment are available in the shell. This is useful for:

• Debugging issues locally with production-like configuration
• Running multiple commands without repeating pulumi env run
• Interactive exploration of cloud resources

Exit the shell to clear the environment variables.

Combining with other tools

Docker

Run containers with secrets:

pulumi env run my-org/my-project/dev -- docker run --env DATABASE_URL myapp

Or use with Docker Compose:

pulumi env run my-org/my-project/dev -- docker-compose up

Make

Run Makefile targets with secrets:

pulumi env run my-org/my-project/dev -- make deploy

CI/CD

Use in CI/CD pipelines to inject secrets without storing them in CI configuration:

# GitHub Actions
- run: pulumi env run my-org/my-project/prod -- ./deploy.sh

# GitLab CI
script:
  - pulumi env run my-org/my-project/prod -- ./deploy.sh

Security considerations

Secrets are revealed during execution

When you run pulumi env run, secrets are revealed and passed as environment variables to the command. The command and any child processes can access these secrets.

Secrets are temporary

Environment variables only exist for the duration of the command. Once the command exits, the secrets are no longer available.

Use appropriate environments

Use separate environments for different security contexts:

• Dev environment for local development
• CI environment for continuous integration
• Prod environment for production deployments

Configure RBAC to control who can run commands with production secrets.

Next steps

• Managing secrets - Store and organize secrets
• Integrate with Pulumi IaC - Use ESC in infrastructure code
• Dynamic login credentials - Generate dynamic cloud credentials with OIDC
• CLI reference - Complete pulumi env run documentation