CLI Overview
Relevant source files
The following files were used as context for generating this wiki page:The Pulumi Command Line Interface (CLI) is the primary tool for users to create, deploy, and manage their infrastructure using Pulumi. It serves as the interface to the Pulumi deployment engine, state storage backends, language SDKs, and resource providers. The CLI is designed to handle the entire lifecycle of cloud resources, from project creation and configuration to deployment, updates, and destruction.
This document provides a technical overview of the CLI's architecture, core commands, and internal mechanisms, as derived from its source code. It is intended for developers and contributors who wish to understand the inner workings of the pulumi executable.
Architecture and Entrypoint
The Pulumi CLI is a Go application built using the Cobra library, which provides a framework for creating powerful and modern CLI applications. The application's entrypoint and command structure are defined across several key files.
Sources: cmd/pulumi/main.go, cmd/pulumi/pulumi.go, developer-docs/architecture/overview.md
Initialization Flow
The execution of any pulumi command begins in cmd/pulumi/main.go. This file contains the main function, which sets up the execution context and invokes the root command defined in cmd/pulumi/pulumi.go. The NewPulumiCmd function constructs the root pulumi command and attaches all subcommands to it.
The following diagram illustrates the initialization flow of the CLI.
This diagram shows the process starting from the main function, which constructs the command tree using NewPulumiCmd and then executes the user-requested command.
Sources: cmd/pulumi/main.go:27-32, cmd/pulumi/pulumi.go:61-137
Core Commands
The Pulumi CLI is composed of numerous subcommands, each responsible for a specific piece of functionality.
pulumi new
The pulumi new command is responsible for creating a new Pulumi project from a template. It orchestrates project scaffolding, stack creation, and dependency installation.
Sources: pkg/cmd/pulumi/newcmd/new.go, README.md
Workflow
The runNew function in pkg/cmd/pulumi/newcmd/new.go orchestrates the project creation process. It handles command-line arguments, user prompts, template downloading, and project initialization.
The workflow for pulumi new is as follows:
This diagram outlines the steps taken by the pulumi new command, from argument parsing to final instructions for the user.
Sources: pkg/cmd/pulumi/newcmd/new.go:102-368
Key Flags
The pulumi new command supports several flags to customize its behavior, particularly for non-interactive environments like CI/CD.
| Flag | Description | Source File |
|---|---|---|
-s, --stack | The stack name to create or select. | pkg/cmd/pulumi/newcmd/new.go:500-502 |
-n, --name | The project name. | pkg/cmd/pulumi/newcmd/new.go:497-499 |
-d, --description | The project description. | pkg/cmd/pulumi/newcmd/new.go:488-490 |
-y, --yes | Skip prompts and proceed with default values. | pkg/cmd/pulumi/newcmd/new.go:503-505 |
-f, --force | Force content generation even if it overwrites existing files. | pkg/cmd/pulumi/newcmd/new.go:491-493 |
-g, --generate-only | Generate the project only; do not create a stack or install dependencies. | pkg/cmd/pulumi/newcmd/new.go:494-496 |
--ai | Prompt to use for Pulumi AI to generate a new project. | pkg/cmd/pulumi/newcmd/new.go:512-514 |
Sources: pkg/cmd/pulumi/newcmd/new.go:482-525
pulumi about
The pulumi about command is a diagnostic tool that prints information about the current Pulumi environment. This is useful for debugging and reporting issues.
Sources: pkg/cmd/pulumi/about/about.go
Information Gathered
The command collects a comprehensive summary of the environment into a summaryAbout struct.
The structure of the collected data is as follows:
This diagram shows the summaryAbout struct and the various nested structs that hold information about different aspects of the Pulumi environment.
Sources: pkg/cmd/pulumi/about/about.go:94-109
The command gathers the following details:
| Category | Description | Source Function |
|---|---|---|
| CLI | Pulumi CLI version, Go version, and Go compiler. | getCLIAbout |
| Plugins | List of installed resource and language plugins with their versions. | getPluginsAbout |
| Host | Operating system, version, and architecture. | getHostAbout |
| Runtime | Information about the project's language runtime (e.g., Node.js, Python). | lang.About |
| Dependencies | Project dependencies for the specific language. | lang.GetProgramDependencies |
| Backend | Current backend URL, user, and organization details. | getBackendAbout |
| Current Stack | Stack name, resources, and any pending operations. | getCurrentStackAbout |
Sources: pkg/cmd/pulumi/about/about.go:112-184
pulumi package info
This command provides detailed information about a Pulumi package by inspecting its schema. It can display information about the provider, its modules, and specific resources or functions.
Sources: pkg/cmd/pulumi/packagecmd/package_info.go
The command can load a package schema from various sources:
- A provider name (e.g.,
aws). - A local schema file path (e.g.,
./schema.json). - A URL to a schema file.
Based on the flags provided (--module, --resource, --function), it displays different levels of detail:
- Provider Info: Default view. Shows package name, version, description, and a list of modules.
- Module Info: With
--module. Shows resources and functions within that module. - Resource/Function Info: With
--resourceor--function. Shows detailed input and output properties for the specified item.
Sources: pkg/cmd/pulumi/packagecmd/package_info.go:61-90
pulumi gen-markdown
This hidden command is used internally to generate CLI documentation in Markdown format. It creates one file per command, which is used to build the official Pulumi CLI documentation website.
Sources: pkg/cmd/pulumi/markdown/gen.go
Documentation Generation Flow
The process involves several steps to transform the Cobra command definitions into documentation-ready Markdown files.
This diagram shows the workflow for generating CLI documentation, including initial generation via Cobra and subsequent post-processing to fit the documentation site's format.
Sources: pkg/cmd/pulumi/markdown/gen.go:88-124
Key steps in the process include:
filePrepender: A function that adds YAML front matter to each generated file. This includes the pagetitle,aliasesfor redirects, and ameta_descfor SEO purposes. The meta description is dynamically generated based on the command name.linkHandler: A function that formats links between command pages to use pretty URLs (e.g.,/docs/iac/cli/commands/pulumi_up/).- Post-processing: After initial generation, each file is read, and regular expressions are used to clean up the content. The main
## <command>header is removed (as it's redundant with the front matter title), and all###sub-headings are promoted to##to maintain a correct heading hierarchy.
Sources: pkg/cmd/pulumi/markdown/gen.go:30-129
Conclusion
The Pulumi CLI is a sophisticated tool built on the Cobra framework that serves as the central point of interaction for developers. It encapsulates a wide range of functionalities, from project scaffolding and deployment management with commands like pulumi new and pulumi up, to introspection and diagnostics with pulumi about. Internally, it also includes utilities for its own maintenance, such as the gen-markdown command for documentation. This architecture allows for a consistent user experience while providing powerful features to manage infrastructure as code.