CLI Commands

The CDK for Terraform CLI has the following commands:

completion

This command outputs a script that you can use to set up autocompletion for bash or zsh.

> cdktf completion

#compdef cdktf
###-begin-cdktf-completions-###
#
# yargs command completion script
#
# Installation: cdktf completion >> ~/.zshrc
#    or cdktf completion >> ~/.zsh_profile on OSX.
#
_cdktf_yargs_completions()
{
  local reply
  local si=$IFS
  IFS=$'
' reply=($(COMP_CWORD="$((CURRENT-1))" COMP_LINE="$BUFFER" COMP_POINT="$CURSOR" cdktf --get-yargs-completions "${words[@]}"))
  IFS=$si
  _describe 'values' reply
}
compdef _cdktf_yargs_completions cdktf
###-end-cdktf-completions-###

The output also contains the installation instructions. For example, here are the instructions for Mac OSX:

cdktf completion >> ~/.bash_profile on OSX.
# or if using zsh instead of bash
cdktf completion >> ~/.zshrc

After you configure auto completion, reload your shell by running source ~/.zshrc, source ~/.bash_profile or opening a new terminal window. You can now autocomplete cdktf commands by pressing the <TAB> key. You may need to enter a space after cdktf for autocomplete to take effect.

> cdktf <TAB>
completion  -- generate completion script
convert     -- Converts a single file of HCL configuration to CDK for Terraform. Takes the file to be converted on stdin.
deploy      -- Deploy the given stacks
destroy     -- Destroy the given stacks
diff        -- Perform a diff (terraform plan) for the given stack
get         -- Generate CDK Constructs for Terraform providers and modules.
init        -- Create a new cdktf project from a template.
list        -- List stacks in app.
login       -- Retrieves an API token to connect to Terraform Cloud.
synth       -- Synthesizes Terraform code for the given app in a directory.
watch       -- [experimental] Watch for file changes and automatically trigger a deploy

convert

This command converts Terraform configuration written in HCL to the equivalent configuration in your preferred language.

->Note: The convert command has known limitations.

cdktf convert

Converts a single file of HCL configuration to CDK for Terraform. Takes the file to be converted on stdin.

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
      --language                                                                                       [choices: "typescript", "python", "csharp", "java", "go"] [default: "typescript"]
      --provider                                 The conversion needs to know which providers are used in addition to the ones in your cdktf.json file. We search for a cdktf.json below
                                                 your current working directory.                                                                                   [array] [default: []]
      --stack                                    Wrap the generated code within a stack class                                                                 [boolean] [default: false]
  -h, --help                                     Show help                                                                                                                     [boolean]

Examples:
  cat main.tf | cdktf convert  --provider integrations/github                                   Takes the HCL content of main.tf and converts it to CDK for Terraform content and prints
                                                                                                it
  cat main.tf | cdktf convert --provider hashicorp/aws > imported.ts                            Takes the HCL content of main.tf and converts it to CDK for Terraform content in
                                                                                                imported.ts
  cat main.tf | cdktf convert --provider 'hashicorp/aws@ ~>3.62.0' 'integrations/github@        Takes the HCL content of main.tf and converts it to CDK for Terraform content in
  ~>4.16.0' --language python > imported.py                                                     imported.py

Examples

Convert a local file.

cat main.tf | cdktf convert > imported.ts

Convert a local file and wrap it into a cdktf.TerraformStack instead of a cdktf.Construct.

cat main.tf | cdktf convert --stack > imported.ts

Convert HCL in your clipboard to Python on OSX.

pbpaste | cdktf convert --language python | pbcopy

deploy

This command deploys a given application.

$ cdktf deploy --help

Help Output

cdktf deploy [stacks...]

Deploy the given stacks

Positionals:
  stacks  Deploy stacks matching the given ids. Required when more than one stack is present in the app                                                            [array] [default: []]

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
  -a, --app                                      Command to use in order to execute cdktf app                                                [required] [default: "npx ts-node main.ts"]
  -o, --output                                   Output directory for the synthesized Terraform config                                                 [required] [default: "cdktf.out"]
      --auto-approve                             Auto approve                                                                                                 [boolean] [default: false]
      --outputs-file                             Path to file where stack outputs will be written as JSON                                                                       [string]
      --outputs-file-include-sensitive-outputs   Whether to include sensitive outputs in the output file                                                      [boolean] [default: false]
      --ignore-missing-stack-dependencies        Don't check if all stacks specified in the command have their dependencies included as well                  [boolean] [default: false]
      --parallelism                              Number of concurrent CDKTF stacks to run. Defaults to infinity, denoted by -1                                    [number] [default: -1]
      --refresh-only                             Select the "refresh only" planning mode, which checks whether remote objects still match the outcome of the most recent Terraform apply
                                                 but does not propose any actions to undo any changes made outside of Terraform.                              [boolean] [default: false]
      --terraform-parallelism                    Forwards value as the `-parallelism` flag to Terraform. By default, the this flag is not forwarded to Terraform. Note: This flag is not
                                                 supported by remote / cloud backend                                                                              [number] [default: -1]
      --no-color                                 Disables terminal formatting sequences in the output.                                                        [boolean] [default: false]
      --migrate-state                            Pass this flag after switching state backends to approve a state migration for all targeted stacks           [boolean] [default: false]
      --var                                      Set a value for one of the input variables in the stack or stacks to apply. Use this option more than once to set more than one
                                                 variable.                                                                                                         [array] [default: []]
      --var-file                                 Load variable values from the given file, in addition to the default files terraform.tfvars and *.auto.tfvars. Use this option more
                                                 than once to include more than one variables file.                                                                [array] [default: []]
      --skip-synth                               Skip synthesis of the application, assume the synthesized Terraform code is already present and up to date   [boolean] [default: false]
  -h, --help                                     Show help                                                                                                                     [boolean]

Note: The parallelism flag has a different behavior than the terraform parallelism flag. To set the custom terraform parallelism flag, please use the --terraform-parallelism flag instead.

Examples

Deploy an application.

$ cdktf deploy

Deploy an application with automatic approval of the diff (Terraform plan).

$ cdktf deploy --auto-approve my-first-stack my-second-stack my-third-stack

Deploy multiple stacks in one run.

$ cdktf deploy my-first-stack my-second-stack my-third-stack

Deploy all stacks in one run:

$ cdktf deploy '*'

Deploy all stacks ending with -production in one run:

$ cdktf deploy '*-production'

If the stacks have dependencies (through cross stack references or by calling myStack.addDependency(otherStack)) deploy will figure out the right order to run.

For more info on the --outputs-file option, refer to the output command.

destroy

This command destroys a given application.

$ cdktf destroy --help

Help output:

cdktf destroy [stacks..]

Destroy the given stacks

Positionals:
  stacks  Destroy stacks matching the given ids. Required when more than one stack is present in the app                                                           [array] [default: []]

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
  -a, --app                                      Command to use in order to execute cdktf app                                                [required] [default: "npx ts-node main.ts"]
  -o, --output                                   Output directory for the synthesized Terraform config                                                 [required] [default: "cdktf.out"]
      --auto-approve                             Auto approve                                                                                                 [boolean] [default: false]
      --ignore-missing-stack-dependencies        Don't check if all stacks specified in the command have their dependencies included as well                  [boolean] [default: false]
      --parallelism                              Number of concurrent CDKTF stacks to run. Defaults to infinity, denoted by -1                                    [number] [default: -1]
      --terraform-parallelism                    Forwards value as the `-parallelism` flag to Terraform. By default, the this flag is not forwarded to Terraform. Note: This flag is not
                                                 supported by remote / cloud backend                                                                              [number] [default: -1]
      --var                                      Set a value for one of the input variables in the stack or stacks to apply. Use this option more than once to set more than one
                                                 variable.                                                                                                         [array] [default: []]
      --var-file                                 Load variable values from the given file, in addition to the default files terraform.tfvars and *.auto.tfvars. Use this option more
                                                 than once to include more than one variables file.                                                                [array] [default: []]
      --no-color                                 Disables terminal formatting sequences in the output.                                                        [boolean] [default: false]
      --migrate-state                            Pass this flag after switching state backends to approve a state migration for all targeted stacks           [boolean] [default: false]
      --skip-synth                               Skip synthesis of the application, assume the synthesized Terraform code is already present and up to date   [boolean] [default: false]
  -h, --help                                     Show help                                                                                                                     [boolean]

Note: The parallelism flag has a different behavior than the terraform parallelism flag. To set the custom terraform parallelism flag, please use the --terraform-parallelism flag instead.

Examples

Destroy an application.

$ cdktf destroy

Destroy an application with automatic approval of the diff (Terraform plan).

$ cdktf destroy --auto-approve

Destroy multiple stacks in one run.

$ cdktf destroy my-first-stack my-second-stack my-third-stack

Destroy all stacks in one run:

$ cdktf destroy '*'

Destroy all stacks ending with production in one run:

$ cdktf destroy '*-production'

If the stacks have dependencies (through cross stack references or by calling myStack.addDependency(otherStack)) deploy will figure out the right order to run.

diff

This command generates a diff for a given application by running Terraform plan.

$ cdktf diff --help

Help output:

cdktf diff [stack]

Perform a diff (terraform plan) for the given stack

Positionals:
  stack  Diff stack which matches the given id only. Required when more than one stack is present in the app                                                                    [string]

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
  -a, --app                                      Command to use in order to execute cdktf app                                                [required] [default: "npx ts-node main.ts"]
  -o, --output                                   Output directory for the synthesized Terraform config                                                 [required] [default: "cdktf.out"]
      --refresh-only                             Select the "refresh only" planning mode, which checks whether remote objects still match the outcome of the most recent Terraform apply
                                                 but does not propose any actions to undo any changes made outside of Terraform.                              [boolean] [default: false]
      --terraform-parallelism                    Forwards value as the `-parallelism` flag to Terraform. By default, the this flag is not forwarded to Terraform. Note: This flag is not
                                                 supported by remote / cloud backend                                                                              [number] [default: -1]
      --var                                      Set a value for one of the input variables in the stack. Use this option more than once to set more than one variable.
                                                                                                                                                                   [array] [default: []]
      --var-file                                 Load variable values from the given file, in addition to the default files terraform.tfvars and *.auto.tfvars. Use this option more
                                                 than once to include more than one variables file.                                                                [array] [default: []]
      --no-color                                 Disables terminal formatting sequences in the output.                                                        [boolean] [default: false]
      --migrate-state                            Pass this flag after switching state backends to approve a state migration for the targeted stack            [boolean] [default: false]
      --skip-synth                               Skip synthesis of the application, assume the synthesized Terraform code is already present and up to date   [boolean] [default: false]
  -h, --help                                     Show help                                                                                                                     [boolean]

Note: The parallelism flag has a different behavior than the terraform parallelism flag. To set the custom terraform parallelism flag, please use the --terraform-parallelism flag instead.

Examples:

Generate a diff for a given application.

$ cdktf diff

get

This command downloads the providers and modules for an application and generates CDK constructs for them. It can use the cdktf.json configuration file to read the list of providers and modules. This command only generates currently missing provider bindings, so it is very fast if nothing changed. The command does not update the version when you specify loose version constraints in your cdktf.json file and have already generated an existing version locally. To update the version anyway, run cdktf get --force to recreate all bindings.

When you change a version constraint, the cdktf get command recreates the bindings for that provider.

$ cdktf get --help

Help Output

cdktf get

Generate CDK Constructs for Terraform providers and modules.

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
  -o, --output                                   Output directory for generated Constructs                                                                    [string] [default: ".gen"]
  -l, --language                                 Output programming language       [string] [required] [choices: "typescript", "python", "java", "csharp", "go"] [default: "typescript"]
      --force                                    Regenerates all generated constructs                                                                         [boolean] [default: false]
      --parallelism                              Number of concurrently generated provider / module bindings. Only applies for languages that are not Typescript (translated by JSII).
                                                 Defaults to infinity, denoted by -1                                                                              [number] [default: -1]
      --show-performance-info                    Shows performance information after generation                                                                                [boolean]
  -h, --help                                     Show help                                                                                                                     [boolean]

Examples

Download the providers and modules defined in the cdktf.json configuration file.

$ cat cdktf.json
{
  "language": "typescript",
  "app": "node main.js",
  "terraformProviders": ["aws@~> 2.0"]
}

$ cdktf get

If you run into issues generating a lot of bindings you can use the --parallelism option to limit the number of bindings generated in parallel.

$ cdktf get --parallelism 1

init

This command creates a new CDK for Terraform project using a template.

$ cdktf init --help

Help Output

cdktf init

Create a new cdktf project from a template.

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
      --template                                 The template to be used to create a new project. Either URL to zip file or one of the built-in templates.                      [string]
      --project-name                             The name of the project.                                                                                                       [string]
      --project-description                      The description of the project.                                                                                                [string]
      --dist                                     Install dependencies from a "dist" directory (for development)                                                                 [string]
      --local                                    Use local state storage for generated Terraform.                                                             [boolean] [default: false]
      --cdktf-version                            The cdktf version to use while creating a new project.                                                      [string] [default: "0.0.0"]
      --from-terraform-project                   Use a terraform project as the basis, CDK constructs will be generated based on the .tf files in the path                      [string]
      --enable-crash-reporting                   Enable crash reporting for the CLI, refer to https://cdk.tf/crash-reporting for more details                                  [boolean]
      --providers                                Providers to add to your project                                                                                  [array] [default: []]
      --providers-force-local                    Force local installation of provider specified in init                                                                        [boolean]
      --tfe-hostname                             The hostname of the Terraform Enterprise instance to use for remote state storage                                              [string]
  -h, --help                                     Show help                                                                                                                     [boolean]

Examples

Create a new Typescript project.

$ cdktf init --template="typescript"

Create a new Python project and use a specific version of the cdktf package.

$ cdktf init --template="python" --cdktf-version="0.0.1"

Create a new Typescript project from an existing Terraform codebase. Currently, you can only use the --from-terraform-project flag with TypeScript, and there are some known limitations.

$ cdktf init --template="typescript" --from-terraform-project /path/to/terraform/project

This command helps log in to HCP Terraform by fetching a HCP Terraform API token.

$ cdktf login --help

Help Output

cdktf login

Retrieves an API token to connect to Terraform Cloud or Terraform Enterprise.

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
      --tfe-hostname                             The Terraform Enterprise hostname to authenticate against. If you use Terraform Cloud you can leave this on the default.
                                                                                                                                                  [string] [default: "app.terraform.io"]
  -h, --help                                     Show help                                                                                                                     [boolean]

Examples:
  cdktf login                                    Takes you through the interactive login process
  cdktf login --tfe-hostname tfe.my-company.com  Takes you through the interactive login process on your companies Terraform Enterprise instance.
  cat my-token.txt | cdktf login                 Uses a locally stored token directly, instead of going through the interactive login process

Please note that we currently expect custom TFE instances to be using the https protocol.

Examples

Fetch an API token from HCP Terraform.

$ cdktf login

synth

This command synthesizes Terraform configuration for an application. CDKTF stores the synthesized configuration in the cdktf.out directory, unless you use the --output flag to specify a different location. The output folder is ephemeral and might be erased for each synth that you run manually or that happens automatically when you run deploy, diff, or destroy.

$ cdktf synth --help

Help Output

cdktf synth

Synthesizes Terraform code for the given app in a directory.

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
  -a, --app                                      Command to use in order to execute cdktf app                                                           [default: "npx ts-node main.ts"]
  -o, --output                                   Output directory for the synthesized Terraform config                                                            [default: "cdktf.out"]
      --check-code-maker-output                  Should `codeMakerOutput` existence check be performed? By default it will be checked if providers or modules are configured.
                                                                                                                                                              [boolean] [default: false]
      --hcl                                      Should the output be in HCL format?                                                                          [boolean] [default: false]
  -h, --help                                     Show help                                                                                                                     [boolean]

Examples

Synthesize code for an application.

$ cdktf synth

Synthesize code when providing a custom command to execute and an output directory.

$ cdktf synth --app="npm compile && node main.js" --output="dirname"

Synthesize code in Terraform HCL instead of JSON

$ cdktf synth --hcl

watch

Warning: The watch command is experimental, so you should only use it in development environments. It also automatically deploys all changes without asking for confirmation.

When the watch command is first run it creates a watchPattern in your cdktf.json based on the language you configured. It's a list of glob patterns matching all files that should be watched.

Whenever a file matching the watch pattern is changed, the command will run cdktf deploy --auto-approve for you. It allows for rapid iterations when developing infrastructure, especially when working with serverless services. You can specify the stacks you want to deploy or you can use cdktf watch --auto-approve '*' to deploy all stacks.

Requirements

Before using watch you should check your environment. The watch command should only be used for development environments. We recommend making sure that the terminal where you want to run watch has no access keys that allow the cdktf-cli to deploy to your production environment.

Run watch

$ cdktf watch --help

Help Output

cdktf watch [stacks..]

[experimental] Watch for file changes and automatically trigger a deploy

Positionals:
  stacks  Deploy stacks matching the given ids. Required when more than one stack is present in the app                                                            [array] [default: []]

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
  -a, --app                                      Command to use in order to execute cdktf app                                                [required] [default: "npx ts-node main.ts"]
  -o, --output                                   Output directory for the synthesized Terraform config                                                 [required] [default: "cdktf.out"]
      --auto-approve                             Auto approve                                                                                                 [boolean] [default: false]
      --parallelism                              Number of concurrent CDKTF stacks to run. Defaults to infinity, denoted by -1                                    [number] [default: -1]
      --terraform-parallelism                    Forwards value as the `-parallelism` flag to Terraform. By default, the this flag is not forwarded to Terraform. Note: This flag is not
                                                 supported by remote / cloud backend                                                                              [number] [default: -1]
  -h, --help                                     Show help                                                                                                                     [boolean]

Note: The parallelism flag has a different behavior than the terraform parallelism flag. To set the custom terraform parallelism flag, please use the --terraform-parallelism flag instead.

Examples

Run watch on the development stack (dev). The --auto-approve flag skips the explicit plan approval step and is currently always required.

cdktf watch dev --auto-approve

Besides for the required --auto-approve flag, you can use the same configuration options as in cdktf deploy.

Troubleshoot watch

Set the CDKTF_LOG_LEVEL environment variable to all and set CDKTF_LOG_FILE_DIRECTORY to your projects root directory.

The debug output is directed to a cdktf.log file in your projects root directory. The log contains information about detected file system changes and the actions they triggered.

output

This command gets the outputs defined in the Terraform configuration of the given stack. It uses terraform output under the hood.

$ cdktf output --help

Help Output

cdktf output [stacks..]

Prints the output of stacks

Positionals:
  stacks  Get outputs of the stacks matching the given ids. Required when more than one stack is present in the app                                                [array] [default: []]

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
  -a, --app                                      Command to use in order to execute cdktf app                                                [required] [default: "npx ts-node main.ts"]
  -o, --output                                   Output directory for the synthesized Terraform config                                                 [required] [default: "cdktf.out"]
      --outputs-file                             Path to file where stack outputs will be written as JSON                                                                       [string]
      --outputs-file-include-sensitive-outputs   Whether to include sensitive outputs in the output file                                                      [boolean] [default: false]
      --skip-synth                               Skip synthesis of the application, assume the synthesized Terraform code is already present and up to date   [boolean] [default: false]
  -h, --help                                     Show help                                                                                                                     [boolean]
➜

`--outputs-file`

The --outputs-file option allows you to specify a file where the stack outputs will be written as JSON. The JSONs structure is matching your construct structure, the name of each construct is used as a key.

{
  "MyStack": {
    "MyConstructInstance": {
      "MyOutput": "my-value",
      "MySecretOutput": "my-secret-value" // not present if --outputs-file-include-sensitive-outputs is not set
    }
  }
}

Please be aware that sensitive outputs are only written to the file if the --outputs-file-include-sensitive-outputs option is used.

debug

This command prints debug information about the current project and environment to help troubleshoot issues.

Help Output

$ cdktf debug --help

cdktf debug

Get debug information about the current project and environment

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
      --json                                     If set, output will be in JSON format.                                                                       [boolean] [default: false]
  -h, --help                                     Show help                                                                                                                     [boolean]

The debug information depends on the programming language. The following example is from a Java application, where CDKTF collects information about Java, Gradle, and Maven. CDKTF detects the installed constructs version through Gradle.

$ cdktf debug
cdktf debug
language: java
cdktf-cli: 0.20.1
node: v18.12.0
cdktf: 0.20.1
constructs: 10.1.167
jsii: null
terraform: 1.4.0
arch: x64
os: darwin 22.6.0
java:
maven: Apache Maven 3.9.3 (21122926829f1ead511c958d89bd2f672198ae9f)Maven home: /usr/local/Cellar/maven/3.9.3/libexecJava version: 20.0.1, vendor: Homebrew, runtime: /usr/local/Cellar/openjdk/20.0.1/libexec/openjdk.jdk/Contents/HomeDefault locale: en_DE, platform encoding: UTF-8OS name: "mac os x", version: "13.5.2", arch: "x86_64", family: "mac"
gradle: ------------------------------------------------------------Gradle 8.2.1------------------------------------------------------------Build time:   2023-07-10 12:12:35 UTCRevision:     a38ec64d3c4612da9083cc506a1ccb212afeecaaKotlin:       1.8.20Groovy:       3.0.17Ant:          Apache Ant(TM) version 1.10.13 compiled on January 4 2023JVM:          20.0.1 (Homebrew 20.0.1)OS:           Mac OS X 13.5.2 x86_64
providers
kreuzwerker/docker@~>2.0 (LOCAL)
        terraform provider version: 2.25.0
com.hashicorp.cdktf-provider-ad (PREBUILT)
        terraform provider version: 0.4.4
        prebuilt provider version: 8.0.0
        cdktf version: ^0.20.0

provider add

This command facilitates adding Terraform providers to a CDKTF project. If a pre-built provider is available for the CDKTF version you are using and the Terraform provider version you requested (if any), it will be installed using e.g. npm install or dotnet add depending on the language you are using. Otherwise, the provider will be added to the cdktf.json config and cdktf get will be automatically invoked to generate local provider bindings.

$ cdktf provider add --help

Help Output

cdktf provider add <provider...>

Add one or more Terraform providers to your project.

Positionals:
  provider  Name of the provider to add. Can include a version constraint (e.g. aws@~>4.0).                                                             [array] [required] [default: []]

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
      --force-local                              force local provider installation, even if pre-built provider exists                                                          [boolean]
  -h, --help                                     Show help                                                                                                                     [boolean]

Examples

Add the aws provider to the project. As the namespace of the AWS Terraform provider is hashicorp it can be left out.

$ cdktf provider add aws

Add a specific version of the aws provider to the project. You can use the @ symbol to specify a version constraint.

$ cdktf provider add aws@~>4.0

Add multiple providers to the project and force local generation of provider bindings.

$ cdktf provider add kreuzwerker/docker google --force-local

Add a provider from a private registry to the project.

$ cdktf provider add registry.example.com/acme/my-provider

provider upgrade

This command lets you upgrade Terraform providers in a CDKTF project to the newest version compatible with your cdktf version. You can also optionally add a version constraint.

If your project has the associated pre-built provider already installed, CDKTF updates the pre-built provider. Otherwise, CDKTF adds the provider to the cdktf.json configuration file and invokes cdktf get to generate local provider bindings.

$ cdktf provider upgrade --help
cdktf provider upgrade <provider...>

Upgrade one or more Terraform providers in your project to the newest version compatible with your CDKTF version.
If your project has the associated pre-built provider already installed, CDKTF updates the pre-built provider. Otherwise, CDKTF adds the specified provider to the cdktf.json
configuration file and generates local provider bindings.

Positionals:
  provider  Name of the provider to upgrade. Can include a version constraint (e.g. aws@~>4.0).                                                         [array] [required] [default: []]

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
  -h, --help                                     Show help                                                                                                                     [boolean]

provider list

This command prints out a table (or json with the --json option) containing details about the providers installed for the project. It gathers information for both locally built and pre-built providers.

Information printed varies between locally generated and prebuilt providers. The information for each provider includes the Terraform provider version, the CDKTF version, and the package name and version (if pre-built provider).

$ cdktf provider list --help
cdktf provider list [flags]

List installed providers

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
      --json                                     get providers list as json                                                                                   [boolean] [default: false]
  -h, --help                                     Show help                                                                                                                     [boolean]

Help Output

cdktf provider upgrade <provider...>

Upgrade one or more Terraform providers in your project to the newest version compatible with your CDKTF version.
If your project has the associated pre-built provider already installed, CDKTF updates the pre-built provider. Otherwise, CDKTF adds the specified provider to the cdktf.json
configuration file and generates local provider bindings.

Positionals:
  provider  Name of the provider to upgrade. Can include a version constraint (e.g. aws@~>4.0).                                                         [array] [required] [default: []]

Options:
      --version                                  Show version number                                                                                                           [boolean]
      --experimental-provider-schema-cache-path  An experimental schema cache that can be used to improve the speed of cdktf get and convert. Supported using the env
                                                 CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH.                                                                [string] [default: false]
      --disable-plugin-cache-env                 Dont set TF_PLUGIN_CACHE_DIR automatically. This is useful when the plugin cache is configured differently. Supported using the env
                                                 CDKTF_DISABLE_PLUGIN_CACHE_ENV.                                                                              [boolean] [default: false]
      --log-level                                Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                          [string]
      --log-file-directory                       The directory path where CDKTF should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTF writes logs to standard
                                                 out at the level specified in `CDKTF_LOG_LEVEL`. Only supported via setting the env CDKTF_LOG_FILE_DIRECTORY
  -h, --help                                     Show help                                                                                                                     [boolean]

Examples

Upgrade the aws provider to the newest version available for your cdktf version.

$ cdktf provider add aws

Upgrade the aws provider to the newest version available for your cdktf version and at version 4 of the provider version.

$ cdktf provider add aws@~>4.0

Upgrade multiple providers to the latest version available for your cdktf version.

$ cdktf provider add kreuzwerker/docker google