> ## Documentation Index
> Fetch the complete documentation index at: https://cdktn.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# CLI Commands - CDK Terrain
> Use the CLI to initialize a new project, deploy your CDKTN app, generate Terraform configuration files, and more.
The CDK Terrain CLI has the following commands:
CDKTN works with both Terraform and OpenTofu. To use OpenTofu, set the `TERRAFORM_BINARY_NAME=tofu` environment variable. Refer to [Environment Variables](/create-and-deploy/environment-variables) for details.
* [completion](/cli-reference/commands#completion)
* [convert](/cli-reference/commands#convert)
* [debug](/cli-reference/commands#debug)
* [deploy](/cli-reference/commands#deploy)
* [destroy](/cli-reference/commands#destroy)
* [diff](/cli-reference/commands#diff)
* [get](/cli-reference/commands#get)
* [init](/cli-reference/commands#init)
* [login](/cli-reference/commands#login)
* [output](/cli-reference/commands#output)
* [provider add](/cli-reference/commands#provider-add)
* [provider upgrade](/cli-reference/commands#provider-upgrade)
* [provider list](/cli-reference/commands#provider-list)
* [synth](/cli-reference/commands#synth)
* [watch](/cli-reference/commands#watch)
## completion
This command outputs a script that you can use to set up autocompletion for bash or zsh.
```
> cdktn completion
#compdef cdktn
###-begin-cdktn-completions-###
#
# yargs command completion script
#
# Installation: cdktn completion >> ~/.zshrc
# or cdktn 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" cdktn --get-yargs-completions "${words[@]}"))
IFS=$si
_describe 'values' reply
}
compdef _cdktf_yargs_completions cdktn
###-end-cdktn-completions-###
```
The output also contains the installation instructions. For example, here are the instructions for Mac OSX:
```
cdktn completion >> ~/.bash_profile on OSX.
# or if using zsh instead of bash
cdktn 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 `cdktn` commands by pressing the `` key. You may need to enter a space after `cdktn` for autocomplete to take effect.
```
> cdktn
completion -- generate completion script
convert -- Converts a single file of HCL configuration to CDK Terrain. 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 cdktn 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.
The `convert` command has [known limitations](https://cdk.tf/convert-limitations).
```
cdktn convert
Converts a single file of HCL configuration to CDK Terrain. 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 | cdktn convert --provider integrations/github Takes the HCL content of main.tf and converts it to CDK Terrain content and prints
it
cat main.tf | cdktn convert --provider hashicorp/aws > imported.ts Takes the HCL content of main.tf and converts it to CDK Terrain content in
imported.ts
cat main.tf | cdktn convert --provider 'hashicorp/aws@ ~>3.62.0' 'integrations/github@ Takes the HCL content of main.tf and converts it to CDK Terrain content in
~>4.16.0' --language python > imported.py imported.py
```
**Examples**
Convert a local file.
```bash theme={null}
cat main.tf | cdktn convert > imported.ts
```
Convert a local file and wrap it into a `cdktn.TerraformStack` instead of a `cdktn.Construct`.
```bash theme={null}
cat main.tf | cdktn convert --stack > imported.ts
```
Convert HCL in your clipboard to Python on OSX.
```bash theme={null}
pbpaste | cdktn convert --language python | pbcopy
```
## deploy
This command deploys a given application.
```bash theme={null}
$ cdktn deploy --help
```
**Help Output**
```
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 cdktn 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 CDKTN 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]
--skip-provider-lock Block `terraform provider lock` from being run for any reason. Warning: This may cause issues when used with HCP Terraform
[boolean] [default: false]
-h, --help Show help
```
The `parallelism` flag has a different behavior than the [terraform parallelism flag](/terraform/cli/commands/apply#parallelism-n). To set the custom terraform parallelism flag, please use the `--terraform-parallelism` flag instead.
If your `cdktf.json` sets `validateInstalledBinary: true`, `deploy` verifies the installed Terraform or OpenTofu binary satisfies your declared [`targetVersions`](/create-and-deploy/configuration-file#declare-target-runtimes) before applying, and errors if it does not.
**Examples**
Deploy an application.
```bash theme={null}
$ cdktn deploy
```
Deploy an application with automatic approval of the diff (Terraform plan).
```bash theme={null}
$ cdktn deploy --auto-approve my-first-stack my-second-stack my-third-stack
```
Deploy multiple stacks in one run.
```bash theme={null}
$ cdktn deploy my-first-stack my-second-stack my-third-stack
```
Deploy all stacks in one run:
```bash theme={null}
$ cdktn deploy '*'
```
Deploy all stacks ending with `-production` in one run:
```bash theme={null}
$ cdktn 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](/cli-reference/commands#output).
## destroy
This command destroys a given application.
```bash theme={null}
$ cdktn destroy --help
```
Help output:
```
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 cdktn 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 CDKTN 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]
--skip-provider-lock Block `terraform provider lock` from being run for any reason. Warning: This may cause issues when used with HCP Terraform
[boolean] [default: false]
-h, --help Show help
```
The `parallelism` flag has a different behavior than the [terraform parallelism flag](/terraform/cli/commands/apply#parallelism-n). To set the custom terraform parallelism flag, please use the `--terraform-parallelism` flag instead.
If your `cdktf.json` sets `validateInstalledBinary: true`, `destroy` verifies the installed Terraform or OpenTofu binary satisfies your declared [`targetVersions`](/create-and-deploy/configuration-file#declare-target-runtimes) before running, and errors if it does not.
**Examples**
Destroy an application.
```bash theme={null}
$ cdktn destroy
```
Destroy an application with automatic approval of the diff (Terraform plan).
```bash theme={null}
$ cdktn destroy --auto-approve
```
Destroy multiple stacks in one run.
```bash theme={null}
$ cdktn destroy my-first-stack my-second-stack my-third-stack
```
Destroy all stacks in one run:
```bash theme={null}
$ cdktn destroy '*'
```
Destroy all stacks ending with production in one run:
```bash theme={null}
$ cdktn 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.
```bash theme={null}
$ cdktn diff --help
```
Help output:
```
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 cdktn 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]
--skip-provider-lock Block `terraform provider lock` from being run for any reason. Warning: This may cause issues when used with HCP Terraform
[boolean] [default: false]
-h, --help Show help
```
The `parallelism` flag has a different behavior than the [terraform parallelism flag](/terraform/cli/commands/plan#parallelism-n). To set the custom terraform parallelism flag, please use the `--terraform-parallelism` flag instead.
If your `cdktf.json` sets `validateInstalledBinary: true`, `diff` verifies the installed Terraform or OpenTofu binary satisfies your declared [`targetVersions`](/create-and-deploy/configuration-file#declare-target-runtimes) before running the plan, and errors if it does not.
Examples:
Generate a diff for a given application.
```bash theme={null}
$ cdktn 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 `cdktn get --force` to recreate all bindings.
When you change a version constraint, the `cdktn get` command recreates the bindings for that provider.
```bash theme={null}
$ cdktn get --help
```
**Help Output**
```
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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.
```bash theme={null}
$ cat cdktf.json
{
"language": "typescript",
"app": "node main.js",
"terraformProviders": ["aws@~> 2.0"]
}
```
```bash theme={null}
$ cdktn 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.
```bash theme={null}
$ cdktn get --parallelism 1
```
## init
This command creates a new CDK Terrain project using a template.
```sh theme={null}
$ cdktn init --help
```
**Help Output**
```
cdktn init
Create a new cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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]
--cdktn-version The cdktn 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.
```bash theme={null}
$ cdktn init --template="typescript"
```
Create a new Python project and use a specific version of the `cdktn` package.
```bash theme={null}
$ cdktn 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.
```bash theme={null}
$ cdktn init --template="typescript" --from-terraform-project /path/to/terraform/project
```
## login
This command helps log in to HCP Terraform by fetching a HCP Terraform API token.
```bash theme={null}
$ cdktn login --help
```
**Help Output**
```
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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:
cdktn login Takes you through the interactive login process
cdktn login --tfe-hostname tfe.my-company.com Takes you through the interactive login process on your companies Terraform Enterprise instance.
cat my-token.txt | cdktn 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.
```bash theme={null}
$ cdktn login
```
## synth
This command synthesizes Terraform configuration for an application. CDKTN 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`.
```sh theme={null}
$ cdktn synth --help
```
**Help Output**
```
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 cdktn 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.
```bash theme={null}
$ cdktn synth
```
Synthesize code when providing a custom command to execute and an output directory.
```bash theme={null}
$ cdktn synth --app="npm compile && node main.js" --output="dirname"
```
Synthesize code in Terraform HCL instead of JSON
```bash theme={null}
$ cdktn synth --hcl
```
## watch
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 `cdktn 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 `cdktn 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 `cdktn-cli` to deploy to your production environment.
### Run watch
```sh theme={null}
$ cdktn watch --help
```
**Help Output**
```
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 cdktn 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 CDKTN 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]
```
The `parallelism` flag has a different behavior than the [terraform parallelism flag](/terraform/cli/commands/apply#parallelism-n). 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.
```
cdktn watch dev --auto-approve
```
Besides for the required `--auto-approve` flag, you can use the same configuration options as in `cdktn 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.
```sh theme={null}
$ cdktn output --help
```
**Help Output**
```
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 cdktn 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]
--skip-provider-lock Block `terraform provider lock` from being run for any reason. Warning: This may cause issues when used with HCP Terraform
[boolean] [default: false]
-h, --help Show help
```
### `--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.
```jsonc theme={null}
{
"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**
```sh theme={null}
$ cdktn debug --help
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 CDKTN collects information about Java, Gradle, and Maven. CDKTN detects the installed `constructs` version through Gradle.
```
$ cdktn debug
cdktn debug
language: java
cdktn-cli: 0.20.1
node: v18.12.0
cdktn: 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
io.cdktn.cdktn-provider-ad (PREBUILT)
terraform provider version: 0.4.4
prebuilt provider version: 8.0.0
cdktn version: ^0.20.0
```
## provider add
This command facilitates adding Terraform providers to a CDKTN project. If a [pre-built provider](/concepts/providers#install-pre-built-providers) is available for the CDKTN 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 `cdktn get` will be automatically invoked to generate [local provider bindings](/concepts/providers#add-provider-to-cdktn-json).
```sh theme={null}
$ cdktn provider add --help
```
**Help Output**
```
cdktn provider add
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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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.
```bash theme={null}
$ cdktn provider add aws
```
Add a specific version of the `aws` provider to the project. You can use the `@` symbol to specify a [version constraint](https://developer.hashicorp.com/terraform/language/providers/requirements#version-constraints).
```bash theme={null}
$ cdktn provider add aws@~>4.0
```
Add multiple providers to the project and force local generation of provider bindings.
```bash theme={null}
$ cdktn provider add kreuzwerker/docker google --force-local
```
Add a provider from a private registry to the project.
```bash theme={null}
$ cdktn provider add registry.example.com/acme/my-provider
```
## provider upgrade
This command lets you upgrade Terraform providers in a CDKTN project to the newest version compatible with your `cdktn` version. You can also optionally add a version constraint.
If your project has the associated [pre-built provider](/concepts/providers#install-pre-built-providers) already installed, CDKTN updates the pre-built provider. Otherwise, CDKTN adds the provider to the `cdktf.json` configuration file and invokes `cdktn get` to generate [local provider bindings](/concepts/providers#add-provider-to-cdktn-json).
```sh theme={null}
$ cdktn provider upgrade --help
cdktn provider upgrade
Upgrade one or more Terraform providers in your project to the newest version compatible with your CDKTN version.
If your project has the associated pre-built provider already installed, CDKTN updates the pre-built provider. Otherwise, CDKTN 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 CDKTN version, and the package name and version (if pre-built provider).
```sh theme={null}
$ cdktn provider list --help
cdktn 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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**
```
cdktn provider upgrade
Upgrade one or more Terraform providers in your project to the newest version compatible with your CDKTN version.
If your project has the associated pre-built provider already installed, CDKTN updates the pre-built provider. Otherwise, CDKTN 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 cdktn get and convert. Supported using the env
CDKTF_EXPERIMENTAL_PROVIDER_SCHEMA_CACHE_PATH. [string] [default: false]
--disable-plugin-cache-env Don't 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 CDKTN should create `cdktf.log` and print logs at the `debug` level. If not set, CDKTN 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 `cdktn` version.
```bash theme={null}
$ cdktn provider add aws
```
Upgrade the `aws` provider to the newest version available for your `cdktn` version and at version `4` of the provider version.
```bash theme={null}
$ cdktn provider add aws@~>4.0
```
Upgrade multiple providers to the latest version available for your `cdktn` version.
```bash theme={null}
$ cdktn provider add kreuzwerker/docker google
```