pulumi stack Command Reference

Manage Pulumi stacks: select, initialize, list, and read outputs.

A Pulumi stack is an isolated instance of your program (for example dev, staging, prod). pulumi stack and its subcommands select the active stack and expose its outputs.

What it does

pulumi stack manages the named instances of a project. Subcommands select the active stack, create new ones, list existing stacks, and print the outputs a deployment exported for other steps to consume.

Common flags and usage

pulumi stack select NAME: set the active stack for subsequent commands
pulumi stack init NAME: create a new stack
pulumi stack ls: list all stacks in the project
pulumi stack output KEY: print a single stack output value
pulumi stack output --json: emit all outputs as JSON
--show-secrets: include secret outputs in the output (use with care)

Example

shell

- name: Read stack outputs
  env:
    PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
  run: |
    pulumi stack select prod
    API_URL=$(pulumi stack output apiUrl)
    echo "api_url=${API_URL}" >> "$GITHUB_OUTPUT"

In CI

Run pulumi stack select before up or preview so the pipeline always targets the intended environment. Use pulumi stack output to pass deployed values (URLs, ARNs) to later steps via $GITHUB_OUTPUT. Avoid --show-secrets in logs unless the output is masked.

Key takeaways

Stacks are isolated instances of a Pulumi project, one per environment.
pulumi stack select pins the active stack before up or preview.
pulumi stack output exports deployed values for later pipeline steps.