Skip to main content
The CDK Terrain (CDKTN) CLI allows you to initialize a new CDKTN project, adjust project settings, synthesize your infrastructure into Terraform configuration files, deploy your CDKTN application, and more. You can also use some Terraform CLI commands like terraform apply and terraform destroy directly, but we recommend using the available cdktn cli commands where possible.
CDKTN works with both Terraform and OpenTofu. To use OpenTofu, set the TERRAFORM_BINARY_NAME=tofu environment variable. Refer to Environment Variables for details.

​
Install

$ npm install -g cdktn-cli

​
Use

$ cdktn --help
Help output: 
Commands:
  cdktn init [OPTIONS]                Create a new cdktn project from a template.
  cdktn get [OPTIONS]                 Generate CDK Constructs for Terraform providers and modules.
  cdktn convert [OPTIONS]             Converts a single file of HCL configuration to CDK Terrain. Takes the file to be converted on stdin.
  cdktn deploy [OPTIONS] <stacks..>   Deploy the given stacks                                                                                                                                    [aliases: apply]
  cdktn destroy [OPTIONS] <stacks..>  Destroy the given stacks
  cdktn diff [stack] [OPTIONS]        Perform a diff (terraform plan) for the given stack                                                                                                         [aliases: plan]
  cdktn list [OPTIONS]                List stacks in app.
  cdktn login                         Retrieves an API token to connect to Terraform Cloud.
  cdktn synth [stack] [OPTIONS]       Synthesizes Terraform code for the given app in a directory.                                                                                          [aliases: synthesize]
  cdktn watch [stack] [OPTIONS]       [experimental] Watch for file changes and automatically trigger a deploy
  cdktn output [stack] [OPTIONS]      Prints the output of a stack
  cdktn debug                         Get debug information about the current project and environment
  cdktn provider                      A set of subcommands that facilitates provider management                                                                                                                             [aliases: outputs]
  cdktn completion                    generate completion script

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]
  -h, --help                  Show help                                                                                                                                                                            [boolean]

Options can be specified via environment variables with the "CDKTF_" prefix (e.g. "CDKTF_OUTPUT")

​
CI Environment

If you are running the CLI in an automated environment, you can force the dynamic CLI output rendering to be static by setting the CI environment variable to true.

​
Configuration File

You can configure the behavior of the Terraform CDK CLI by modifying the cdktf.json file in your project root directory. Refer to the cdktf.json documentation for more detail on how you can supply custom configuration settings for your application.

​
Telemetry

The CDKTN CLI (cdktn-cli interacts with a HashiCorp service called Checkpoint to report project metrics such as cdktn version, project language, provider name, platform name, and other details that help guide the project maintainers with feature and roadmap decisions. The code that interacts with Checkpoint is part of the CDK Terrain CLI. The use of Checkpoint is completely optional. Refer to the telemetry documentation for more information about Checkpoint and you can disable it if desired.

​
node-gyp errors

CDKTN CLI invokes the Terraform CLI interactively in a pseudo-terminal (PTY) for the deploy and destroy commands. This requires native code that needs to be compiled for the architecture of the system the CDKTN CLI is installed on. To make things easier, we maintain a fork that includes pre-compiled native bindings for multiple target architectures and Node.js versions. However, there is still the rare possibility, that no precompiled binary is available. In such a case node-gyp will attempt to compile the native libraries upon installation of the cdktn-cli package and will require additional software to compile the native code that might not be installed yet. For example, you might encounter the following error when installing the CDKTN CLI: 
npm ERR! Prebuild binary missing for platform.
npm ERR! prebuild-install WARN install No prebuilt binaries found (target=19.4.0 runtime=node arch=x64 libc= platform=win32)
...
npm ERR! gyp ERR! find VS msvs_version not set from command line or npm config
npm ERR! gyp ERR! find VS VCINSTALLDIR not set, not running in VS Command Prompt
npm ERR! gyp ERR! find VS could not use PowerShell to find Visual Studio 2017 or newer, try re-running with '--loglevel silly' for more details
npm ERR! gyp ERR! find VS not looking for VS2015 as it is only supported up to Node.js 18
npm ERR! gyp ERR! find VS not looking for VS2013 as it is only supported up to Node.js 8
npm ERR! gyp ERR! find VS
npm ERR! gyp ERR! find VS **************************************************************
npm ERR! gyp ERR! find VS You need to install the latest version of Visual Studio
npm ERR! gyp ERR! find VS including the "Desktop development with C++" workload.
npm ERR! gyp ERR! find VS For more information consult the documentation at:
npm ERR! gyp ERR! find VS https://github.com/nodejs/node-gyp#on-windows
npm ERR! gyp ERR! find VS **************************************************************
npm ERR! gyp ERR! find VS
npm ERR! gyp ERR! configure error
npm ERR! gyp ERR! stack Error: Could not find any Visual Studio installation to use
npm ERR! gyp ERR! stack     at VisualStudioFinder.fail (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:122:47)
npm ERR! gyp ERR! stack     at C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:75:16
npm ERR! gyp ERR! stack     at VisualStudioFinder.findVisualStudio2013 (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:369:14)
npm ERR! gyp ERR! stack     at C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:71:14
npm ERR! gyp ERR! stack     at VisualStudioFinder.findVisualStudio2015 (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:353:14)
npm ERR! gyp ERR! stack     at C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:67:12
npm ERR! gyp ERR! stack     at failPowershell (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:156:7)
npm ERR! gyp ERR! stack     at VisualStudioFinder.parseData (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:170:14)
npm ERR! gyp ERR! stack     at C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:143:14
npm ERR! gyp ERR! stack     at ChildProcess.exithandler (node:child_process:411:7)
npm ERR! gyp ERR! System Windows_NT 10.0.20348
npm ERR! gyp ERR! command "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\node_modules\\node-gyp\\bin\\node-gyp.js" "rebuild"
npm ERR! gyp ERR! cwd C:\Users\Administrator\node_modules\node-pty-prebuilt-multiarch
npm ERR! gyp ERR! node -v v19.4.0
npm ERR! gyp ERR! node-gyp -v v9.3.0
npm ERR! gyp ERR! not ok
If you encounter this or a similar error message, install the additional tools, as described in the node-gyp documentation for UNIX, Mac OS X, and Windows. You might also encounter this message if you’re using a Node.js version for which we don’t pre-compile native code. We currently support Node.js versions 17, 18, 19, and 20. If you’re using a different Node.js version you can either install the required additional software as described above or switch your Node.js versions to a supported one.