pulumi-new

Choose a template interactively

$ pulumi new

$ pulumi new [provided-template]

$ pulumi new [path/to/templates/aws-typescript]

$ pulumi new [url]

$ pulumi new --secrets-provider [passphrase]

pulumi new [template-name] [options]

template-name
    Optional. The name of the template to use (e.g., 'aws-typescript', 'azure-python'). If omitted, Pulumi will prompt the user to select one from a list of available templates.

--dir directory
    Specify the directory where the new project should be created. If not provided, the current working directory is used.

--name project-name
    Assign a specific name to the new Pulumi project. If not provided, Pulumi will prompt for it.

--description description
    Provide a description for the new Pulumi project, which will be stored in the Pulumi.yaml file.

--stack stack-name
    Create an initial stack with the given name. If not provided, Pulumi will prompt for a stack name.

--secrets-provider provider
    Define the type of secrets manager to use for the new project. Supported values include 'default' (Pulumi Service), 'passphrase', 'awskms', 'azurekeyvault', or 'gcpkms'.

--config-passphrase passphrase
    Specify a passphrase to encrypt secrets when using the 'passphrase' secrets provider. Can also be set via the PULLUMI_CONFIG_PASSPHRASE environment variable.

--generate-only
    Only generate the project files from the template; do not create a stack, log in, or install dependencies.

--force
    Overwrite existing files in the target directory if they conflict with template files.

--yes
    Skip prompts and automatically accept default values or non-interactive choices during project creation.

--offline
    Do not attempt to contact the Pulumi service for templates or configuration. Only use locally available templates.

--template path-or-url
    Specify a local path to a template directory or a URL to a git repository containing a template.

--logtostderr
    Log all output messages to standard error instead of standard output.

--verbose
    Enable verbose logging to display more detailed information during command execution.

--debug
    Enable debug logging, providing the most detailed output for troubleshooting.

The pulumi new command initializes a new Pulumi project from a pre-defined template.

Pulumi projects are directories containing source code that defines infrastructure as code (IaC) using familiar programming languages like TypeScript, Python, Go, C#, Java, or F#. When executed, pulumi new typically prompts the user for essential details such as the project name, stack name, and optionally, a project description. It then fetches the specified template (either from the official Pulumi template registry, a local path, or a remote URL), copies the template files into the target directory, and can optionally install project dependencies (e.g., npm packages for Node.js, pip packages for Python). This command significantly streamlines the process of getting started with infrastructure as code by providing a boilerplate structure for various cloud providers (AWS, Azure, GCP, Kubernetes) and application types, enabling developers to focus on infrastructure logic rather than initial setup.

The command pulumi new typically requires an active internet connection to download templates from the Pulumi registry unless the --offline flag is used or a local template path is provided. It also assumes the Pulumi CLI is installed and configured. If prompts are skipped using --yes, ensure all necessary configuration (like project name, stack name) is provided via command-line flags, otherwise the command might fail or create a project with default/undesired settings.

When using the `passphrase` secrets provider, securely managing the passphrase is crucial, as its loss will make encrypted secrets irrecoverable.

By default, pulumi new is interactive. If a template name is not provided, it presents a list of available templates. It also prompts for project name, description, and stack name, allowing users to configure their new project dynamically. These prompts can be bypassed using specific command-line flags like --yes and providing values for required parameters.

Templates can be sourced from:
1. The official Pulumi template registry (default)
2. A local file path (e.g., --template ./my-local-template)
3. A Git repository URL (e.g., --template https://github.com/my-org/my-templates#main)
This flexibility allows organizations to maintain their own standardized infrastructure templates.

The pulumi new command is an integral part of the Pulumi CLI, which was first publicly released in 2018. It reflects Pulumi's core philosophy of enabling developers to define cloud infrastructure using general-purpose programming languages. From its inception, the `new` command has provided a streamlined entry point for users to quickly bootstrap infrastructure projects across various cloud providers and programming languages, continually evolving with new template types and configuration options as Pulumi's ecosystem expands.

pulumi(1), pulumi up(1), pulumi destroy(1), pulumi stack(1), git(1)