Stack Management Commands
Relevant source files
The following files were used as context for generating this wiki page:
A Pulumi stack is an isolated, independently configurable instance of a Pulumi program. Stacks are the primary mechanism for managing different deployment environments (e.g., development, staging, production) or distinct cloud configurations. The pulumi stack command and its subcommands provide the command-line interface for creating, viewing, and managing these stacks.
This functionality is also exposed programmatically through the Automation API, which allows for orchestrating Pulumi deployments within larger software systems, CI/CD pipelines, or custom tooling. The core stack operations—initialization, listing, selection, and removal—are fundamental to the Pulumi workflow.
Core Concepts
A stack is always associated with a project. It maintains its own configuration, secrets, and a history of updates. The state of a stack's resources is stored in a checkpoint in the configured backend.
The relationship between a project, workspace, and stacks can be visualized as follows:
This diagram shows a single project within a workspace can have multiple stacks, each with its own configuration file.
Sources: pkg/cmd/pulumi/newcmd/new.go, pkg/cmd/pulumi/stack/stack.go
Command Structure
The primary command for stack management is pulumi stack. It serves as a parent command for various subcommands that perform specific actions.
| Command | Description |
|---|---|
pulumi stack init | Create a new stack. |
pulumi stack ls | List all stacks for the current project. |
pulumi stack select | Select a stack to be the current working stack. |
pulumi stack rm | Remove a stack and its configuration. |
pulumi stack | Display information about the current stack. |
pulumi stack output | Show the outputs of the current stack. |
pulumi stack history | Display the update history of a stack. |
pulumi stack rename | Rename an existing stack. |
pulumi stack tag | Manage stack tags. |
pulumi stack export | Export a stack's deployment to standard out. |
pulumi stack import | Import a stack's deployment from standard in. |
Sources: pkg/cmd/pulumi/stack/stack.go:73-93
Detailed Commands
Stack Initialization (pulumi stack init)
This command creates a new, empty stack with a specified name. During initialization, you can also select a secrets provider.
The newStackInitCmd function orchestrates this process. If a stack name is not provided via the --stack flag, it interactively prompts the user for one. It then calls the backend's CreateStack method.
Sources: pkg/cmd/pulumi/stack/stack_init.go:34-80
A key helper function, PromptAndCreateStack (often used by pulumi new), encapsulates the logic for interactively prompting for a stack name and creating it.
Sources: pkg/cmd/pulumi/newcmd/new.go:420-429
The initialization flow is as follows:
This flowchart illustrates the process of initializing a new stack, from user input to backend interaction.
Sources: pkg/cmd/pulumi/stack/stack_init.go:34-80, pkg/cmd/pulumi/newcmd/new.go:420-429
Flags
| Flag | Description |
|---|---|
-s, --stack <name> | The name of the stack to create. |
--secrets-provider <type> | The type of secrets provider to use (default, passphrase, awskms, azurekeyvault, gcpkms, hashivault). |
-y, --yes | Skip prompts and proceed with default values. |
Sources: pkg/cmd/pulumi/stack/stack_init.go:82-93, pkg/cmd/pulumi/newcmd/new.go:616-618
Listing Stacks (pulumi stack ls)
This command lists all stacks associated with the current project.
The newStackLsCmd function retrieves the current backend and calls its ListStacks method. The results are then formatted and printed to the console, either as a human-readable table or as JSON if the --json flag is used. The currently selected stack is marked with an asterisk (*).
Sources: pkg/cmd/pulumi/stack/stack_ls.go:34-91, sdk/nodejs/tests/automation/localWorkspace.spec.ts:182-202
Flags
| Flag | Description |
|---|---|
-a, --all | List all stacks in the organization, not just for the current project. |
-j, --json | Emit output as JSON. |
--show-secrets | Display secret configuration values in plaintext (only for JSON output). |
Sources: pkg/cmd/pulumi/stack/stack_ls.go:93-103
Removing Stacks (pulumi stack rm)
This command removes one or more stacks and their associated history and configuration.
The newStackRmCmd function implements this. For safety, it requires user confirmation before proceeding, which can be bypassed with the --yes flag. If a stack contains resources, removal is blocked unless the --force flag is provided. This prevents accidental deletion of active infrastructure.
Sources: pkg/cmd/pulumi/stack/stack_rm.go:38-144
The following sequence diagram shows the interaction for removing a stack:
This diagram illustrates the confirmation and backend communication steps involved in removing a stack.
Sources: pkg/cmd/pulumi/stack/stack_rm.go:38-144
Flags
| Flag | Description |
|---|---|
-y, --yes | Skip confirmation prompts. |
-f, --force | Force deletion of a stack that still contains resources. |
--preserve-config | Do not delete the stack's configuration file. |
Sources: pkg/cmd/pulumi/stack/stack_rm.go:146-155
Viewing Stack Information (pulumi stack)
When run without any subcommands, pulumi stack displays detailed information about the currently selected stack.
The runStack function in stack.go is responsible for gathering and displaying this information. It fetches the stack's snapshot from the backend to list resources and outputs. It also shows metadata such as the backend name, owner, and last update time.
The output can be customized with flags to show resource URNs or provider-assigned IDs.
Sources: pkg/cmd/pulumi/stack/stack.go:96-206
A key feature is its ability to render the resource hierarchy in a tree format. The renderTree function builds a node tree from the parent-child relationships in the snapshot and then prints it. If a tree cannot be constructed (e.g., due to missing parent nodes), it falls back to a simple list.
Sources: pkg/cmd/pulumi/stack/stack.go:268-315
Flags
| Flag | Description |
|---|---|
-i, --show-ids | Display each resource's provider-assigned unique ID. |
-u, --show-urns | Display each resource's Pulumi-assigned globally unique URN. |
--show-secrets | Display stack outputs marked as secret in plaintext. |
--show-name | Display only the stack name. |
Sources: pkg/cmd/pulumi/stack/stack.go:58-69
Automation API
The stack management commands available in the CLI are mirrored in the Automation API, allowing for programmatic control over stacks. This is particularly useful for CI/CD integration, building custom platforms on top of Pulumi, or integration testing.
The LocalWorkspace class (in both Go and Node.js SDKs) is the primary entry point. It provides methods to create, select, list, and remove stacks.
Sources: sdk/go/auto/README.md:65-73, sdk/nodejs/tests/automation/localWorkspace.spec.ts:101-110
The following class diagram shows the relationship between LocalWorkspace and Stack in the Node.js Automation API.
This diagram illustrates that a LocalWorkspace instance can manage multiple Stack instances, providing methods for their lifecycle and configuration.
Sources: sdk/nodejs/tests/automation/localWorkspace.spec.ts
Example Usage (Go)
The Go Automation API provides functions like NewStackLocalSource, SelectStackLocalSource, and UpsertStackLocalSource to work with stacks tied to a local filesystem project.
// Example of creating and removing a stack programmatically
ctx := context.Background()
stackName := FullyQualifiedStackName("org", "project", "dev_stack")
pDir := filepath.Join(".", "project")
// Initialize a new stack
s, err := NewStackLocalSource(ctx, stackName, pDir)
if err != nil { /* ... */ }
// Deploy the stack
_, err = s.Up(ctx)
if err != nil { /* ... */ }
// Remove the stack
err = s.Workspace().RemoveStack(ctx, s.Name())
if err != nil { /* ... */ }
Sources: sdk/go/auto/example_test.go:704-730
Example Usage (Node.js)
The Node.js Automation API uses a similar object-oriented model.
// Example of creating and removing a stack in Node.js
const projectName = "node_test";
const projectSettings = { name: projectName, runtime: "nodejs" };
const ws = await LocalWorkspace.create({ projectSettings });
const stackName = "my-org/node_test/dev";
// Create, select, and then remove a stack
await ws.createStack(stackName);
await ws.selectStack(stackName);
await ws.removeStack(stackName);
Sources: sdk/nodejs/tests/automation/localWorkspace.spec.ts:101-110
Summary
The pulumi stack command suite provides a comprehensive set of tools for managing the lifecycle of deployment environments. From interactive creation with init to detailed inspection with the base stack command and safe removal with rm, these commands are essential for any developer using Pulumi. The parallel functionality offered by the Automation API further extends these capabilities, enabling powerful automation and integration scenarios.