» 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 stack
destroy     -- Destroy the given stack
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.

cdktf convert [OPTIONS]

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

Options:
  --version                   Show version number                                                   [boolean]
  --disable-logging           Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.
                                                                                    [boolean] [default: true]
  --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"]
  -h, --help                  Show help                                                             [boolean]

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

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]

Deploy the given stack

Options:
  --version          Show version number                                                                                                                                           [boolean]
  --disable-logging  Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.                                                                          [boolean] [default: true]
  --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"]
  --auto-approve     Auto approve                                                                                                                                 [boolean] [default: false]
  -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

» destroy

This command destroys a given application.

$ cdktf destroy --help

Help output:

cdktf destroy [OPTIONS]

Destroy the given stack

Options:
  --version          Show version number                                                                                                                                           [boolean]
  --disable-logging  Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.                                                                          [boolean] [default: true]
  --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"]
  --auto-approve     Auto approve                                                                                                                                 [boolean] [default: false]
  -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

» 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]
  --disable-logging  Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.                                                                          [boolean] [default: true]
  --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]
  --disable-logging  Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.                                           [boolean] [default: true]
  --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-logging           Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.
                                                                                          [boolean] [default: true]
  --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]
  -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.

Options:
  --version          Show version number                                                                                                                                           [boolean]
  --disable-logging  Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.                                                                          [boolean] [default: true]
  --log-level        Which log level should be written. Only supported via setting the env CDKTF_LOG_LEVEL                                                                          [string]
  -h, --help         Show help                                                                                                                                                     [boolean]

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]
  --disable-logging  Don't write log files. Supported using the env CDKTF_DISABLE_LOGGING.                                                                          [boolean] [default: true]
  --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"]
  --json             Provide JSON output for the generated Terraform configuration.                                                                               [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 for an application and output the Terraform JSON configuration.

$ cdktf synth --json

» watch

The watch command watches a directory for changes and automatically synthesizes and deploys changes as they happen. It allows for rapid iterations when developing infrastructure, especially when working with serverless services. It currently supports only one stack at a time and automatically deploys changes without asking for confirmation.

Watch reads your root .gitignore file to determine which files trigger a synth and it uses the outdir of your cdktf.json (or the default cdktf.out) to do so for a deploy. It will generate a checksum of the subdirectory containing the Terraform code for your stack to skip deploys if the synthesized Terraform config did not change.

» Requirements

Before using watch you should:

  • Check your root .gitignore file. Your root .gitignore must contain all files that are generated by synth and deploy. If that is not the case, the watch command will trigger itself and continuously try to deploy. Although Git supports nesting .gitignore files, the watch command currently only reads the root .gitignore file.

  • 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 [stack] [OPTIONS]

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

Positionals:
  stack  Deploy 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]
      --disable-logging           Dont write log files. Supported using the env CDKTF_DISABLE_LOGGING.                                                                                                                                                                                                                                             [boolean] [default: true]
      --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]
  -o, --output                    Output directory                                                                                                                                                                                                                                                                                         [required] [default: "cdktf.out"]
      --auto-approve              Auto approve                                                                                                                                                                                                                                                                                                 [boolean] [default: false]
  -h, --help                      Show help

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

» Troubleshoot watch

Set the CDKTF_LOG_LEVEL environment variable to all and set CDKTF_DISABLE_LOGGING to false.

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.