Skip to main content
Welcome — in this lesson we’ll work with Projects in Terraform Cloud (HCP Terraform). You’ll learn how to create a project, review and configure its settings (including Execution Mode and Auto-destroy), and migrate existing workspaces into a project. These steps apply to the Terraform Cloud web UI and the common Terraform CLI workflow. First, open the Terraform Cloud web UI and view the Workspaces for your organization (here: cloudsand-hcp).
A screenshot of the Terraform Cloud web UI showing the "Workspaces" page with a list of workspaces (e.g., customer-data-prod, hcp-demo, networking-prod, web-prod), their run status (one marked Applied) and recent change timestamps. The left sidebar shows navigation items like Projects, Stacks, Registry, and Settings.

​
Create a new Project

To create a project:
  • In the top-left navigation choose Projects.
  • Click New Project.
  • Provide a name (for this demo: hcp-demo) and an optional description.
  • Save the project.
Example: after creating the project you’ll land on the project’s page. Initially it shows no teams, workspaces, or tags assigned.
A screenshot of the Terraform Cloud web UI with a "Create a new project" modal open showing the project name "hcp-demo-project" and a description being typed. The background displays the Projects page and left-side navigation (Stacks, Workspaces, Registry, Usage, Settings).
A screenshot of the Terraform Cloud web UI showing a project page titled "hcp-demo-project" with no workspaces and a prompt to "Add your first workspace." The left sidebar lists Overview, Workspaces, Stacks, and Settings, and there's a blue "New" button on the page.

​
Project settings and defaults

Project settings define behavior that applies by default to any workspace associated with the project. The most important settings include:
  • Execution Mode — choose the default run mode for workspaces in this project:
    • Organization Default
    • Remote (Terraform Cloud)
    • Local
    • Agent
  • Team access — control which teams can view or modify project workspaces.
  • Variable sets — apply shared variables across all project workspaces.
  • Auto-destroy Workspaces — schedule automatic terraform destroy runs for ephemeral environments or demos.
You can update or delete the project from the General settings pane.
A browser screenshot of the Terraform Cloud project settings page for "hcp-demo-project," showing the Project description field, Execution Mode options (Organization Default, Remote, Local, Agent), and buttons to update or delete the project.
Auto-destroy is especially useful for demo or ephemeral projects — it automates terraform destroy after a configured interval so test environments don’t linger.
A screenshot of the Terraform Cloud project settings page showing the "Auto-destroy workspaces" section with explanatory bullet points and a "Set up default" button. The left sidebar lists other project settings like General, Team access, and Variable sets.

​
How to move existing workspaces into a project

There are two common methods to add a workspace to a project: Permissions: moving workspaces requires appropriate organization/workspace permissions. After you move workspaces, the project’s Workspaces list will show them (for example, web-prod and networking-prod).

​
Using Terraform CLI with Terraform Cloud projects

If you run Terraform locally but want the configuration to use Terraform Cloud, the typical workflow is:
  1. Authenticate to Terraform Cloud:
  1. Configure your local HCL to target the organization and workspace:
  1. Initialize and run Terraform:
If you manage multiple environments, consider naming conventions for projects and workspaces (for example, project-name-env) and use variable sets and team access to enforce policy and reduce configuration drift.

​
Deleting a Project

To delete a project: Settings → General → Delete Project. Terraform Cloud prevents deletion if the project still contains workspaces — you must move or remove them first.
Before deleting a project, ensure all associated workspaces have been removed or reassigned. Terraform Cloud will not allow deletion of a project that still contains workspaces.

​
Summary

You now know how to:
  • Create a Terraform Cloud project and set defaults (Execution Mode, variable sets, team access).
  • Configure Auto-destroy for ephemeral environments.
  • Move workspaces into a project via the Workspaces list or workspace settings.
  • Use Terraform CLI with Terraform Cloud-targeted configurations.
Further reading and references:

Watch Video