Terraform
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 is only functional for Terraform 1.0 and above. There are also known limitations.
cdktf convert [OPTIONS]
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]
--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]
--language [choices: "typescript", "python", "csharp", "java"] [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: []]
-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@ ~>4.16.0' --language Takes the HCL content of main.tf and converts it to CDK for Terraform content in imported.ts
python > imported.py
Examples
Convert a local file.
cat main.tf | cdktf convert > 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 [OPTIONS] <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] [required] [default: []]
Options:
--version Show version number [boolean]
--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]
-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]
-h, --help Show help [boolean]
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, see the output command below.
destroy
This command destroys a given application.
$ cdktf destroy --help
Help output:
cdktf destroy [OPTIONS] <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] [required] [default: []]
Options:
--version Show version number [boolean]
--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]
-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]
-h, --help Show help [boolean]
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 [OPTIONS]
Perform a diff (terraform plan) for the given stack
Options:
--version Show version number [boolean]
--log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string]
--app, -a Command to use in order to execute cdktf app [required]
--output, -o Output directory [required] [default: "cdktf.out"]
-h, --help Show help [boolean]
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.
$ cdktf get --help
Help Output
cdktf get [OPTIONS]
Generate CDK Constructs for Terraform providers and modules.
Options:
--version Show version number [boolean]
--log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string]
--output, -o Output directory for generated Constructs [string] [default: ".gen"]
--language, -l Output programming language [string] [required] [choices: "typescript", "python", "java", "csharp", "go"]
-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
init
This command creates a new CDK for Terraform project using a template.
$ cdktf init --help
Help Output
cdktf init [OPTIONS]
Create a new cdktf project from a template.
Options:
--version Show version number [boolean]
--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]
--template The template to be used to create a new project. Either URL to zip file or one of the built-in templates: ["csharp", "go", "java", "python",
"python-pip", "typescript"] [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, see https://www.terraform.io/cdktf/telemetry#crash-reporting for more details [boolean]
-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
login
This command helps log in to Terraform Cloud by fetching a Terraform Cloud 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]
--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]
--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 Terraform Cloud.
$ 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 [OPTIONS]
Synthesizes Terraform code for the given app in a directory.
Options:
--version Show version number [boolean]
--log-level Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL [string]
--app, -a Command to use in order to execute cdktf app
--output, -o Output directory [default: "cdktf.out"]
-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"
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 [OPTIONS] <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] [required] [default: []]
Options:
--version Show version number [boolean]
--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]
-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]
-h, --help Show help [boolean]
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.
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 [stack] [OPTIONS]
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 [string]
Options:
--version Show version number [boolean]
--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]
-a, --app Command to use in order to execute cdktf app [required] [default: "npx ts-node main.ts"]
-o, --output Output directory [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]
-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]
--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]
--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 and Maven. CDKTF detects the installed constructs version through Maven.
$ cdktf debug
language: java
cdktf-cli: 0.10.4
node: v16.15.0
cdktf: 0.10.4
constructs: 10.0.5
jsii: 1.59.0
terraform: 1.1.8
arch: x64
os: darwin 21.4.0
java: 17.0.1
maven: Apache Maven 3.8.2 (ea98e05a04480131370aa0c110b8c54cf726c06f)Maven home: /usr/local/Cellar/maven/3.8.2/libexecJava version: 17.0.1, vendor: Homebrew, runtime: /usr/local/Cellar/openjdk/17.0.1_1/libexec/openjdk.jdk/Contents/HomeDefault locale: en_DE, platform encoding: UTF-8OS name: "mac os x", version: "12.3.1", arch: "x86_64", family: "mac"
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]
--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]
--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