pulumi preview Command Reference

Preview the changes a pulumi up would make without applying them.

pulumi preview computes and prints the diff between your program and the stack state without mutating any resources. It is the safe, read-only step you run on pull requests.

What it does

pulumi preview evaluates the program and reports the create, update, replace, and delete operations it would perform, along with a resource count. No infrastructure is touched, making it the standard PR check.

Common flags and usage

--stack / -s NAME: preview a specific stack
--diff: show a detailed property-level diff
--expect-no-changes: exit non-zero if any change is detected (drift gate)
--refresh: refresh state before computing the preview
--json: emit machine-readable output for downstream tooling

Example

shell

- name: Pulumi Preview
  if: github.event_name == 'pull_request'
  env:
    PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
  run: pulumi preview --stack prod --diff

In CI

Run preview on pull requests to surface the diff before merge; reserve pulumi up for the main branch. Use --expect-no-changes in a scheduled job to fail when live infrastructure has drifted from code. PULUMI_ACCESS_TOKEN authenticates the state backend.

Key takeaways

preview shows planned changes without modifying any resources.
Run it on pull requests and keep pulumi up on the deploy branch.
--expect-no-changes turns preview into a drift gate that fails on any diff.