github.com/hugorut/terraform@v1.1.3/website/docs/cli/commands/workspace/new.mdx (about)

     1  ---
     2  page_title: 'Command: workspace new'
     3  description: The terraform workspace new command is used to create a new workspace.
     4  ---
     5  
     6  # Command: workspace new
     7  
     8  The `terraform workspace new` command is used to create a new workspace.
     9  
    10  ## Usage
    11  
    12  Usage: `terraform workspace new [OPTIONS] NAME [DIR]`
    13  
    14  This command will create a new workspace with the given name. A workspace with
    15  this name must not already exist.
    16  
    17  If the `-state` flag is given, the state specified by the given path
    18  will be copied to initialize the state for this new workspace.
    19  
    20  The command-line flags are all optional. The supported flags are:
    21  
    22  * `-lock=false` - Don't hold a state lock during the operation. This is
    23    dangerous if others might concurrently run commands against the same
    24    workspace.
    25  * `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s.
    26  * `-state=path`   - Path to an existing state file to initialize the state of this environment.
    27  
    28  ## Example: Create
    29  
    30  ```
    31  $ terraform workspace new example
    32  Created and switched to workspace "example"!
    33  
    34  You're now on a new, empty workspace. Workspaces isolate their state,
    35  so if you run "terraform plan" Terraform will not see any existing state
    36  for this configuration.
    37  ```
    38  
    39  ## Example: Create from State
    40  
    41  To create a new workspace from a pre-existing local state file:
    42  
    43  ```
    44  $ terraform workspace new -state=old.terraform.tfstate example
    45  Created and switched to workspace "example".
    46  
    47  You're now on a new, empty workspace. Workspaces isolate their state,
    48  so if you run "terraform plan" Terraform will not see any existing state
    49  for this configuration.
    50  ```