Pulumi Blog: CLI

All Pulumi CLI flags are now supported as environment variables

Tom Harding — Fri, 21 Nov 2025 00:00:00 +0000

With the release of Pulumi v3.208.0, all CLI flags can now be configured as environment variables. This addresses a common friction point of having to remember the same flags across multiple commands and of ensuring that your entire team uses consistent CLI options.

Use cases

An example use case might be that you want to always refresh state before operations, or re-run programs during refresh and destroy (using --run-program). But remembering to add --refresh every time is tedious.

Another example is you’re working on a specific subset of your infrastructure and need to pass the same --target or --exclude flags repeatedly across multiple operations.

You’re working in a CI environment where you want to skip interactive prompts and previews. That means adding --yes and --skip-preview to every single command in your pipeline.

The usual workaround, if there is no env var already, is writing wrapper scripts or shell aliases, but these become another thing to maintain and share across your team.

How it works

Any CLI flag can now be set as an environment variable. The naming convention is straightforward: prefix the flag name with PULUMI_OPTION_, and convert dashes to underscores.

For example:

export PULUMI_OPTION_REFRESH=true

Target specific resources without repeating flags:

export PULUMI_OPTION_TARGET=foo,bar
# Equivalent to: --target foo --target bar

This works for any flag the CLI accepts. The environment variable takes precedence if you don’t explicitly pass the flag on the command line.

Using with direnv for project-level defaults

This becomes particularly useful when combined with tools like direnv. You can define project-specific CLI defaults in a .envrc file at the root of your project:

# Enable very verbose logging for debugging purposes
export PULUMI_OPTION_VERBOSE=3

# Always refresh before any Pulumi operation
export PULUMI_OPTION_REFRESH=true

# Skip previews and any dialogs or user prompts
export PULUMI_OPTION_YES=true
export PULUMI_OPTION_SKIP_PREVIEW=true

Now, running direnv allow . in this directory means that, whenever we access this directory, these options will be automatically applied to all commands that we run until we leave the directory!

Wrapping up

We hope that this change makes Pulumi much easier to configure across a range of different environments, and gives you another tool for managing operation defaults across your team. Thanks for reading, and feel free to share any feedback on GitHub, X, or our Community Slack.

Pulumi Updates, Explained: AI-Powered Features in Pulumi CLI

Artur Laksberg — Thu, 22 May 2025 00:00:00 +0000

Note: This post discusses Pulumi Copilot, which Pulumi Neo has replaced. Learn about Neo →

We’re excited to announce the new AI capabilities for Pulumi CLI powered by Pulumi Copilot that translate complex infrastructure changes into clear, human-readable explanations and help resolve deployment errors with actionable guidance. Enable these preview features with the --copilot flag.

At Pulumi, we’re committed to helping you deploy infrastructure efficiently and with minimal friction. Anyone who has worked with cloud infrastructure knows the frustration of sifting through large previews with numerous changes and the difficulty of interpreting cryptic error messages from cloud provider APIs when deployments fail.

There are two key challenges we’ve identified:

Understanding Preview Changes: Reviewing raw update previews can be overwhelming, especially for complex deployments with many resources. It’s difficult to quickly grasp the full scope and impact of pending infrastructure changes.
Interpreting Error Messages: When deployments fail, cloud providers often return error messages that, while comprehensive, bury the core issue within extensive diagnostics, requiring specialized expertise to interpret and address.

Our latest CLI update introduces AI capabilities that tackle both issues. Let’s explore how these new features improve your infrastructure management workflow.

Update Explanation

To address the first challenge above, we’ve introduced a new “explain” menu item in the CLI. When running pulumi preview or pulumi up with the --copilot flag, you’ll see this option in the interactive menu:

In this screenshot, you can see the standard Pulumi update preview showing an AWS VPC with multiple subnets, route tables, and gateways that need to be updated. The interactive menu at the bottom shows the new “explain” option with a sparkle emoji, indicating the AI-powered feature. When selected, this tool analyzes and provides a clear summary of all changes in your pending infrastructure update:

In this example, the AI explanation immediately identifies that this is a “VPC Renaming Operation - Tag Updates Only” and explains that the update is simply changing tags across all components. It clearly states this is a “safe, non-disruptive change that only affects resource labels.”

This explanation serves as a valuable sanity check before deployment. It presents a plain-language summary of exactly what changes will occur, helping you verify that the planned modifications align with your intentions. This visibility is particularly valuable when managing complex infrastructure with many resources, as it helps identify unexpected changes or potential drift between your code and deployed resources. The system also proactively flags potential issues such as security vulnerabilities or destructive updates that might impact your production environment.

Diagnostics Summarization

For the second challenge, when infrastructure deployments fail, cloud providers often return error messages that are technically accurate but difficult to decipher without specialized knowledge. Consider the following scenario where a Go-based Docker image build fails with vendoring issues:

In this example, the standard Go build process failed with a cryptic error about inconsistent vendoring. While the raw output does contain the necessary information, it’s buried within extensive build logs. Our AI-powered Copilot diagnostics immediately identifies the problem and provides a clear, actionable solution: “Docker image update failed due to inconsistent vendoring. Sync vendor with ‘go mod vendor’.”

This clear explanation identifies root causes and provides actionable guidance, transforming dense technical output into concise explanations. It reduces time to resolution by pinpointing both the problem and the exact command needed to fix it, eliminating the need to search through documentation or guess.

Getting Started

The AI-powered features are currently in preview. You can enable them by adding the --copilot flag to your Pulumi CLI commands:

pulumi preview --copilot
pulumi up --copilot

These features require Pulumi CLI version v3.171.0 or greater and the Pulumi Cloud backend. Organization administrators must enable Pulumi Copilot by navigating to Settings > Access Management > Pulumi Copilot in the Pulumi Cloud console.

During this preview period, we’re focused on:

Refining explanations based on user feedback
Adding new capabilities like suggesting fixes for common errors
Improving performance to ensure minimal impact on command execution time

We will continue to monitor usage patterns and incorporate your feedback before enabling these features by default.

We’re excited to see how these AI-powered insights enhance your infrastructure deployment workflow! Please share your experiences with us:

Connect with us in the Pulumi Community Slack
Open an issue on GitHub
Learn more about Pulumi Copilot

Try this today, Get Started with Pulumi for free

Your input will directly influence how we evolve these features from preview to general availability.

Introducing `pulumi state move`: Move Resources Between Stacks or Projects

Thomas Gummerer — Thu, 25 Jul 2024 00:00:00 +0000

Today we’re announcing the pulumi state move command, which can be used to move resources that are managed by Pulumi between different stacks and/or projects. With the pulumi state move command, you can refactor your Pulumi Infrastructure as Code without any disruption to your deployed cloud infrastructure, enabling you to evolve and scale with confidence.

When refactoring a Pulumi project from a monolithic structure to micro stacks, you might need to move resources between different projects or stacks, without recreating them. While this has been possible with some significant manual effort to hand-modify Pulumi state files (our users came up with automated solutions for this!), doing so can be error prone and time consuming. Having a simpler, integrated solution for this problem was a much requested feature. The new pulumi state move command, combined with the aliases command for refactoring resources within stacks, offers the richest collection of tools for refactoring IaC at scale available in the industry today.

The pulumi state move command works as follows:

$ pulumi state move --help
Move resources from one stack to another
This command can be used to move resources from one stack to another. This can be useful when
splitting a stack into multiple stacks or when merging multiple stacks into one.
Usage:
pulumi state move [flags] <urn>...
Flags:
--dest string The name of the stack to move resources to
-h, --help help for move
--include-parents Include all the parents of the moved resources as well
--source string The name of the stack to move resources from
-y, --yes Automatically approve and perform the move

Both dest and source can be either stacks in the current project, or stacks in a different project, using the fully qualified stack names. Note that this works only for stacks within the same backend, it is currently not possible to move a resource between different backends (though you can move stacks between backends using other existing tools).

The resources being moved have to be specified by their full URN, and multiple URNs can be passed at once. For each resource being moved, all the children of that resource will also be moved, and the relationships between all resources being moved is preserved. Resources with other types of dependencies will however not be moved to the target stack by default. The easiest way to get the full URN of the resources is to use pulumi stack --show-urns. Note that URNs can contain characters that get interpreted by the shell, so it is always a good idea to wrap them in single quotes (') when passing them as arguments.

The pulumi state move command won’t modify the code of your program directly, it will only modify the state of the source and destination stacks. So following running the command, you should ensure that you modify both programs to match the changes you have made. This can typically be accomplished by copy/pasting source code for the resources and/or components between the two codebases. Inputs and outputs of resources that were moved may need to be adjusted as part of this process. This can be done either by using stack references, or recreating the inputs in the program.

Example

To demonstrate how the command works in practice, let’s go through an example. Let’s assume we have the following program:

const randomPet = new random.RandomPet("a-random-pet");

const b = new aws.s3.Bucket("b");

const index = new aws.s3.BucketObject("index.html", {
 bucket: b.bucket,
 content: "Thanks for using Pulumi!",
}, {
 parent: b,
});

const randomSite = new aws.s3.BucketObject("random.html", {
 bucket: b.bucket,
 content: randomPet.id,
}, {
 parent: b,
});

We create a bucket, and two bucket objects, both of them having the bucket as their parent. One of the objects has a random pet name as its content. At some point we decide we’d rather group all the AWS resources in a separate program, because this one grew too large. We can do that using the pulumi state move command, and then adjusting the code.

First we can find out which stacks already exist and we can move the resources to:

$ pulumi stack ls --all
NAME LAST UPDATE RESOURCE COUNT URL
v-thomas-pulumi-corp/pulumi-demo-move-aws/dev 23 minutes ago 0 <url>
v-thomas-pulumi-corp/pulumi-demo-move/dev 6 minutes ago 7 <url>

Next we can find the URN of the resources using pulumi stack --show-urns:

$ pulumi stack --show-urns
Current stack is dev:
 Owner: v-thomas-pulumi-corp
 Last updated: 13 seconds ago (2024-07-23 13:52:17.58884965 +0200 CEST)
 Pulumi version used: 3.125.1-dev.0
Current stack resources (7):
 TYPE NAME
 pulumi:pulumi:Stack pulumi-demo-move-dev
 │ URN: urn:pulumi:dev::pulumi-demo-move::pulumi:pulumi:Stack::pulumi-demo-move-dev
 ├─ random:index/randomPet:RandomPet a-random-pet
 │ URN: urn:pulumi:dev::pulumi-demo-move::random:index/randomPet:RandomPet::a-random-pet
 ├─ aws:s3/bucket:Bucket b
 │ │ URN: urn:pulumi:dev::pulumi-demo-move::aws:s3/bucket:Bucket::b
 │ ├─ aws:s3/bucketObject:BucketObject random.html
 │ │ URN: urn:pulumi:dev::pulumi-demo-move::aws:s3/bucket:Bucket$aws:s3/bucketObject:BucketObject::random.html
 │ └─ aws:s3/bucketObject:BucketObject index.html
 │ URN: urn:pulumi:dev::pulumi-demo-move::aws:s3/bucket:Bucket$aws:s3/bucketObject:BucketObject::index.html
 ├─ pulumi:providers:random default_4_16_3
 │ URN: urn:pulumi:dev::pulumi-demo-move::pulumi:providers:random::default_4_16_3
 └─ pulumi:providers:aws default_6_45_0
 URN: urn:pulumi:dev::pulumi-demo-move::pulumi:providers:aws::default_6_45_0

Next we can actually move the resources. Since we’re moving the resources from the currently selected stack, we can omit the --source argument:

$ pulumi state move --dest v-thomas-pulumi-corp/pulumi-demo-move-aws/dev 'urn:pulumi:dev::pulumi-demo-move::aws:s3/bucket:Bucket::b'
Planning to move the following resources from v-thomas-pulumi-corp/pulumi-demo-move/dev to v-thomas-pulumi-corp/pulumi-demo-move-aws/dev:

 - urn:pulumi:dev::pulumi-demo-move::aws:s3/bucket:Bucket::b
 - urn:pulumi:dev::pulumi-demo-move::aws:s3/bucket:Bucket$aws:s3/bucketObject:BucketObject::random.html
 - urn:pulumi:dev::pulumi-demo-move::aws:s3/bucket:Bucket$aws:s3/bucketObject:BucketObject::index.html

The following resources being moved to v-thomas-pulumi-corp/pulumi-demo-move-aws/dev have dependencies on resources in v-thomas-pulumi-corp/pulumi-demo-move/dev:

 - urn:pulumi:dev::pulumi-demo-move::aws:s3/bucket:Bucket$aws:s3/bucketObject:BucketObject::random.html has a dependency on urn:pulumi:dev::pulumi-demo-move::random:index/randomPet:RandomPet::a-random-pet
 - urn:pulumi:dev::pulumi-demo-move::aws:s3/bucket:Bucket$aws:s3/bucketObject:BucketObject::random.html (content) has a property dependency on urn:pulumi:dev::pulumi-demo-move::random:index/randomPet:RandomPet::a-random-pet

If you go ahead with moving these dependencies, it will be necessary to create the appropriate inputs and outputs in the program for the stack the resources are moved to.

Do you want to perform this move? yes
Successfully moved resources from v-thomas-pulumi-corp/pulumi-demo-move/dev to v-thomas-pulumi-corp/pulumi-demo-move-aws/dev

There’s a few things worth explaining above:

We’re moving the resources to a different project, so we need to use the fully qualified stack name. If the resources are being moved between different stacks in the same project, the argument can be only the stack name.
Before actually moving the resources, the command gives a list of resources that is being moved. Since the bucket objects are children of the bucket, they will be included in the move. However the random pet is not a child resource, so it will not be moved.
The command also warns us about dependencies that will not be transferred to the destination stack. Since we didn’t want to include the pet, but the bucket has a dependency on it, pulumi will warn us about that.
Before going ahead with the move, we get prompted to confirm whether we want to go ahead with it. In this example we do want to go ahead with the move, so we confirm the move, and the resources will be moved for us.

Now that the resources are moved, we need to adjust the program to take advantage of that. The source program will now look as follows:

const randomPet = new random.RandomPet("a-random-pet");
export const randomPetName = randomPet.id;

Only the random pet remains here. We also export its name, so we can continue using it in the destination program. Meanwhile the destination program is mostly just a copy of the original AWS resources, but there is an important change:

const stackRef = new pulumi.StackReference(`v-thomas-pulumi-com/pulumi-demo-move/dev`)

const b = new aws.s3.Bucket("b");

const index = new aws.s3.BucketObject("index.html", {
 bucket: b.bucket,
 content: "Thanks for using Pulumi!",
}, {
 parent: b,
});

const randomSite = new aws.s3.BucketObject("random.html", {
 bucket: b.bucket,
 content: stackRef.getOutput("randomPetName"),
}, {
 parent: b,
});

Note how we now need to specify the content of random.html, since we no longer have the random pet in the same program. In this case we use a stack reference to reference the output from the source program. It is of course up to the user how to re-create the output. It could also come from config, or be hardcoded depending on the use-case.

Refactor your infrastructure safely

Use pulumi state move to split a growing project into focused stacks without recreating your cloud resources. Organize your infrastructure as code and manage every stack in Pulumi Cloud.

Learn more

As always, we would love to hear your feedback in the community slack. If you encounter any issues with the command, please open an issue.

Introducing Dev Releases for the Pulumi CLI and SDKs

Thomas Gummerer — Tue, 02 Apr 2024 00:00:00 +0000

At Pulumi, the stability of our CLI and SDK releases is critically important. A lot of infrastructure is built and deployed using Pulumi, and any bugs in how that infrastructure is deployed can cause outages. While we put a lot of emphasis on unit and integration testing, we are also constantly investing in new ways to provide additional safeguards to ensure we always deliver stable releases. To that end, we are introducing new dev releases of our CLI and SDKs, which will enable users who want to work with the very latest bits to try them out before they are deployed widely to the entire Pulumi user base. This blog post will walk you through how we are using them internally, and how you can too!

What are dev releases?

On every push to the main branch, in other words every time a pull request is merged, we publish a new dev release for both the CLI and the Pulumi core SDKs. For the CLI, we publish the binaries for all supported platforms to S3, while for the SDKs we create pre-release versions in whatever form the various package managers support.

This means these dev releases always include all the latest features and bug fixes, that will be in the next stable release. And while it was always possible to get the latest CLI or SDKs with some moderate effort depending on the platform and language, having these be proper releases makes for a much more standardized experience on how to install them.

Dev releases of the CLI can be installed on Linux, macOS, and Windows. For example, on Linux or macOS:

$ curl -fsSL https://get.pulumi.com | sh -s -- --version dev

Dev SDKs are currently available for Node.js, Python, .NET, and Go. For example, installing the dev release of the Node.js SDK with npm:

$ npm add @pulumi/pulumi@dev

How are we using them internally at Pulumi?

At Pulumi we are not only developers of our product, but we also love using it internally. All deploys for Pulumi Cloud are orchestrated by Pulumi. In addition we use Pulumi for managing other things such as this blog, and even access management to services we are using is partly done with Pulumi. All of these are a great way for us to test our software in real world use cases, before releasing it.

In addition to that, we also use the dev releases for testing both our templates and examples. This is a huge set of Pulumi programs, that can help figure out problems early.

How you can leverage dev releases

In addition to making it easier for us to test new code that gets merged, and making sure we can release the most stable software possible, we also wanted to make it easier for users to use these dev releases. There’s a couple reasons why these could help your organization:

A bug fix has been merged, but not yet released? You can get it a few minutes after it is merged via the dev release channel
You want to make sure your production stacks work well with the latest version of Pulumi? Use dev releases with your dev stacks for some early testing. We’d be delighted with any bugs that are reported before they make it into a release.

How to get started

For instructions on how to use the CLI dev releases see the Install Docs, and for pre-release versions of dev SDKs see the docs for Node.js, Python, .NET, and Go.

Happy building!

Manage Pulumi Teams in Bulk with the New CLI Teams Flag

Robbie McKinstry — Fri, 31 Mar 2023 00:00:00 +0000

We’ve been hearing feedback from our customers that they need ways to manage permissions for their stacks at scale. Today we are announcing a --teams flag for pulumi stack init, which allows customers to assign Teams to stacks from the CLI. This flag offers a third programmatic method for assigning permissions, supplementing Pulumi Service REST API or the Pulumi Service Provider. Developers can now initialize their stacks with the right permissions directly from the CLI.

Here’s some background for any Pulumi newcomers. Pulumi projects consist of stacks, which are separate deployments of the same infrastructure. Stacks may also be configured with separate inputs. Organization admins can leverage RBAC to grant access permissions at the organization or Pulumi Teams levels. Pulumi Teams and RBAC are available for Enterprise and Business Critical customers.

Stacks are often created via the CLI with the pulumi stack init command. This command initializes a new stack. If you’re using the Pulumi Service as your backend, you can view your newly created stack in the Pulumi Service console. If your organization uses teams, you will want to give your teammates access to the stack.

With the release of Pulumi v3.59.0, developers can assign Pulumi Team access during stack creation. To do this, pass in the --teams flag followed by the team’s name. For instance:

pulumi stack init --teams Red

This saves time by eliminating context switching, allowing users to stay on task. Previously, the Service console was the most direct way to assign team access to a stack, meaning a trip to the browser before your teammates could access the stack. The --teams flag improves upon the process of managing stack permissions by removing this step.

Use the flag multiple times to assign access to multiple Pulumi Teams, as in:

pulumi stack init --teams Red --teams Blue

Currently, the feature always grants read and write access, the most commonly assigned permissions.

We implemented this feature as a direct result of feedback from daily users. Context switching can be expensive when you’re creating enough stacks. At Pulumi, we enable our users to squeak out as much productivity from our tooling as possible. We’re always happy to make ergonomic improvements. We look forward to continuing to raise the bar for cloud productivity.