This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.

# AWS CDK CLI command reference
<a name="ref-cli-cmd"></a>

This section contains command reference information for the AWS Cloud Development Kit (AWS CDK) Command Line Interface (CLI). The CDK CLI is also referred to as the CDK Toolkit.

## Usage
<a name="ref-cli-cmd-usage"></a>

```
$ cdk <command> <arguments> <options>
```

## Commands
<a name="ref-cli-cmd-commands"></a><a name="ref-cli-cmd-commands-acknowledge"></a>

 ` acknowledge ack `   
Acknowledge a notice by issue number and hide it from displaying again.<a name="ref-cli-cmd-commands-bootstrap"></a>

 ` bootstrap `   
Prepare an AWS environment for CDK deployments by deploying the CDK bootstrap stack, named `CDKToolkit`, into the AWS environment.<a name="ref-cli-cmd-commands-context"></a>

 ` context `   
Manage cached context values for your CDK application.<a name="ref-cli-cmd-commands-deploy"></a>

 ` deploy `   
Deploy one or more CDK stacks into your AWS environment.<a name="ref-cli-cmd-commands-destroy"></a>

 ` destroy `   
Delete one or more CDK stacks from your AWS environment.<a name="ref-cli-cmd-commands-diff"></a>

 ` diff `   
Perform a diff to see infrastructure changes between CDK stacks.<a name="ref-cli-cmd-commands-docs"></a>

 ` docs doc `   
Open CDK documentation in your browser.<a name="ref-cli-cmd-commands-doctor"></a>

 ` doctor `   
Inspect and display useful information about your local CDK project and development environment.<a name="ref-cli-cmd-commands-drift"></a>

 ` drift `   
Detect configuration drift for resources that you define, manage, and deploy using CDK.<a name="ref-cli-cmd-commands-flags"></a>

 ` flags `   
View and modify your feature flag configurations for the CDK CLI.<a name="ref-cli-cmd-commands-import"></a>

 ` import `   
Use AWS CloudFormation resource imports to import existing AWS resources into a CDK stack.<a name="ref-cli-cmd-commands-init"></a>

 ` init `   
Create a new CDK project from a template.<a name="ref-cli-cmd-commands-list"></a>

 ` list, ls `   
List all CDK stacks and their dependencies from a CDK app.<a name="ref-cli-cmd-commands-metadata"></a>

 ` metadata `   
Display metadata associated with a CDK stack.<a name="ref-cli-cmd-commands-migrate"></a>

 ` migrate `   
Migrate AWS resources, AWS CloudFormation stacks, and AWS CloudFormation templates into a new CDK project.<a name="ref-cli-cmd-commands-notices"></a>

 ` notices `   
Display notices for your CDK application.<a name="ref-cli-cmd-commands-publish-assets"></a>

 ` publish-assets `   
Publish assets for the specified CDK stack to their respective destinations without performing a deployment.<a name="ref-cli-cmd-commands-refactor"></a>

 ` refactor `   
Preserve deployed resources when refactoring code in your CDK application.<a name="ref-cli-cmd-commands-synthesize"></a>

 ` synthesize, synth `   
Synthesize a CDK app to produce a cloud assembly, including an AWS CloudFormation template for each stack.<a name="ref-cli-cmd-commands-watch"></a>

 ` watch `   
Continuously watch a local CDK project for changes to perform deployments and hotswaps.

## Global options
<a name="ref-cli-cmd-options"></a>

The following options are compatible with all CDK CLI commands.<a name="ref-cli-cmd-options-app"></a>

 `--app, -a <STRING>`   
Provide the command for running your app or cloud assembly directory.  
 *Required*: Yes<a name="ref-cli-cmd-options-asset-metadata"></a>

 `--asset-metadata <BOOLEAN>`   
Include `aws:asset:*` AWS CloudFormation metadata for resources that use assets.  
 *Required*: No  
 *Default value*: `true` <a name="ref-cli-cmd-options-build"></a>

 `--build <STRING>`   
Command for running a pre-synthesis build.  
 *Required*: No<a name="ref-cli-cmd-options-ca-bundle-path"></a>

 `--ca-bundle-path <STRING>`   
Path to a CA certificate to use when validating HTTPS requests.  
If this option is not provided, the CDK CLI will read from the `AWS_CA_BUNDLE` environment variable.  
 *Required*: Yes<a name="ref-cli-cmd-options-ci"></a>

 `--ci <BOOLEAN>`   
Indicate that CDK CLI commands are being run in a continuous integration (CI) environment.  
This option modifies the behavior of the CDK CLI to better suit automated operations that are typical in CI pipelines.  
When you provide this option, logs are sent to `stdout` instead of `stderr`.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-context"></a>

 `--context, -c <ARRAY>`   
Add contextual string parameters as key-value pairs.<a name="ref-cli-cmd-options-debug"></a>

 `--debug <BOOLEAN>`   
Enable detailed debugging information. This option produces a verbose output that includes a lot more detail about what the CDK CLI is doing behind the scenes.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-ec2creds"></a>

 `--ec2creds, -i <BOOLEAN>`   
Force the CDK CLI to try and fetch Amazon EC2 instance credentials.  
By default, the CDK CLI guesses the Amazon EC2 instance status.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the CDK CLI.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-ignore-errors"></a>

 `--ignore-errors <BOOLEAN>`   
Ignore synthesis errors, which will likely produce an output that is not valid.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-json"></a>

 `--json, -j <BOOLEAN>`   
Use JSON instead of YAML for AWS CloudFormation templates that are printed to standard output (`stdout`).  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-lookups"></a>

 `--lookups <BOOLEAN>`   
Perform context lookups.  
Synthesis will fail if this value is `false` and context lookups need to be performed.  
 *Required*: No  
 *Default value*: `true` <a name="ref-cli-cmd-options-no-color"></a>

 `--no-color <BOOLEAN>`   
Remove color and other styling from the console output.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-notices"></a>

 `--notices <BOOLEAN>`   
Show relevant notices.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-output"></a>

 `--output, -o <STRING>`   
Specify the directory to output the synthesized cloud assembly to.  
 *Required*: Yes  
 *Default value*: `cdk.out` <a name="ref-cli-cmd-options-path-metadata"></a>

 `--path-metadata <BOOLEAN>`   
Include `aws::cdk::path` AWS CloudFormation metadata for each resource.  
 *Required*: No  
 *Default value*: `true` <a name="ref-cli-cmd-options-plugin"></a>

 `--plugin, -p <ARRAY>`   
Name or path of a node package that extends CDK features. This option can be provided multiple times in a single command.  
You can configure this option in the project’s `cdk.json` file or at `~/.cdk.json` on your local development machine:  

```
{
   // ...
   "plugin": [
      "module_1",
      "module_2"
   ],
   // ...
}
```
 *Required*: No<a name="ref-cli-cmd-options-profile"></a>

 `--profile <STRING>`   
Specify the name of the AWS profile, containing your AWS environment information, to use with the CDK CLI.  
 *Required*: Yes<a name="ref-cli-cmd-options-proxy"></a>

 `--proxy <STRING>`   
Use the indicated proxy.  
If this option is not provided, the CDK CLI will read from the `HTTPS_PROXY` environment variable.  
 *Required*: Yes  
 *Default value*: Read from `HTTPS_PROXY` environment variable.<a name="ref-cli-cmd-options-role-arn"></a>

 `--role-arn, -r <STRING>`   
The ARN of the IAM role that the CDK CLI will assume when interacting with AWS CloudFormation.  
 *Required*: No<a name="ref-cli-cmd-options-staging"></a>

 `--staging <BOOLEAN>`   
Copy assets to the output directory.  
Specify `false` to prevent the copying of assets to the output directory. This allows the AWS SAM CLI to reference the original source files when performing local debugging.  
 *Required*: No  
 *Default value*: `true` <a name="ref-cli-cmd-options-strict"></a>

 `--strict <BOOLEAN>`   
Do not construct stacks that contain warnings.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-trace"></a>

 `--trace <BOOLEAN>`   
Print trace for stack warnings.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-verbose"></a>

 `--verbose, -v <COUNT>`   
Show debug logs. You can specify this option multiple times to increase verbosity.  
 *Required*: No<a name="ref-cli-cmd-options-version"></a>

 `--version <BOOLEAN>`   
Show the CDK CLI version number.  
 *Required*: No  
 *Default value*: `false` <a name="ref-cli-cmd-options-version-reporting"></a>

 `--version-reporting <BOOLEAN>`   
Include the ` AWS::CDK::Metadata` resource in synthesized AWS CloudFormation templates.  
 *Required*: No  
 *Default value*: `true` 

## Providing and configuring options
<a name="ref-cli-cmd-configure"></a>

You can pass options through command-line arguments. For most options, you can configure them in a `cdk.json` configuration file. When you use multiple configuration sources, the CDK CLI adheres to the following precedence:

1.  **Command-line values** – Any option provided at the command-line overrides options configured in `cdk.json` files.

1.  **Project configuration file** – The `cdk.json` file in your CDK project’s directory.

1.  **User configuration file** – The `cdk.json` file located at `~/.cdk.json` on your local machine.

## Passing options at the command line
<a name="ref-cli-cmd-pass"></a><a name="ref-cli-cmd-pass-bool"></a>

 **Passing boolean values**   
For options that accept a boolean value, you can specify them in the following ways:  
+ Use `true` and `false` values – Provide the boolean value with the command. The following is an example:

  ```
  $ cdk deploy --watch=true
  $ cdk deploy --watch=false
  ```
+ Provide the option’s counterpart – Modify the option name by adding `no` to specify a `false` value. The following is an example:

  ```
  $ cdk deploy --watch
  $ cdk deploy --no-watch
  ```
+ For options that default to `true` or `false`, you don’t have to provide the option unless you want to change from the default.

# `cdk acknowledge`
<a name="ref-cli-cmd-ack"></a>

Acknowledge a notice by issue number and hide it from displaying again.

This is useful to hide notices that have been addressed or do not apply to you.

Acknowledgements are saved at a CDK project level. If you acknowledge a notice in one CDK project, it will still display in other projects until acknowledged there.

## Usage
<a name="ref-cli-cmd-ack-usage"></a>

```
$ cdk acknowledge <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-ack-args"></a><a name="ref-cli-cmd-ack-args-notice-id"></a>

 **Notice ID**   
The ID of the notice.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-ack-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-ack-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk acknowledge` command.

## Examples
<a name="ref-cli-cmd-ack-examples"></a>

### Acknowledge and hide a notice that displays when running another CDK CLI command
<a name="ref-cli-cmd-ack-examples-1"></a>

```
$ cdk deploy
... # Normal output of the command

NOTICES

16603   Toggling off auto_delete_objects for Bucket empties the bucket

        Overview: If a stack is deployed with an S3 bucket with
                  auto_delete_objects=True, and then re-deployed with
                  auto_delete_objects=False, all the objects in the bucket
                  will be deleted.

        Affected versions: <1.126.0.

        More information at: https://github.com/aws/aws-cdk/issues/16603


17061   Error when building EKS cluster with monocdk import

        Overview: When using monocdk/aws-eks to build a stack containing
                  an EKS cluster, error is thrown about missing
                  lambda-layer-node-proxy-agent/layer/package.json.

        Affected versions: >=1.126.0 <=1.130.0.

        More information at: https://github.com/aws/aws-cdk/issues/17061

$ cdk acknowledge 16603
```

# `cdk bootstrap`
<a name="ref-cli-cmd-bootstrap"></a>

Prepare an AWS environment for CDK deployments by deploying the CDK bootstrap stack, named `CDKToolkit`, into the AWS environment.

The bootstrap stack is a CloudFormation stack that provisions an Amazon S3 bucket and Amazon ECR repository in the AWS environment. The AWS CDK CLI uses these resources to store synthesized templates and related assets during deployment.

## Usage
<a name="ref-cli-cmd-bootstrap-usage"></a>

```
$ cdk bootstrap <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-bootstrap-args"></a><a name="ref-cli-cmd-bootstrap-args-env"></a>

 ** AWS environment**   
The target AWS environment to deploy the bootstrap stack to in the following format: `aws://<account-id>/<region>`.  
Example: `aws://123456789012/us-east-1`   
This argument can be provided multiple times in a single command to deploy the bootstrap stack to multiple environments.  
By default, the CDK CLI will bootstrap all environments referenced in the CDK app or will determine an environment from default sources. This could be an environment specified using the `--profile` option, from environment variables, or default AWS CLI sources.

## Options
<a name="ref-cli-cmd-bootstrap-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-bootstrap-options-bootstrap-bucket-name"></a>

 `--bootstrap-bucket-name, --toolkit-bucket-name, -b <STRING>`   
The name of the Amazon S3 bucket that will be used by the CDK CLI. This bucket will be created and must not currently exist.  
Provide this option to override the default name of the Amazon S3 bucket.  
When you use this option, you may have to customize synthesis. To learn more, see [Customize CDK stack synthesis](configure-synth.md#bootstrapping-custom-synth).  
 *Default value*: Undefined<a name="ref-cli-cmd-bootstrap-options-bootstrap-customer-key"></a>

 `--bootstrap-customer-key <BOOLEAN>`   
Create a Customer Master Key (CMK) for the bootstrap bucket (you will be charged but can customize permissions, modern bootstrapping only).  
This option is not compatible with `--bootstrap-kms-key-id`.  
 *Default value*: Undefined<a name="ref-cli-cmd-bootstrap-options-bootstrap-kms-key-id"></a>

 `--bootstrap-kms-key-id <STRING>`   
The AWS KMS master key ID to use for the `SSE-KMS` encryption.  
Provide this option to override the default AWS KMS key used to encrypt the Amazon S3 bucket.  
This option is not compatible with `--bootstrap-customer-key`.  
 *Default value*: Undefined<a name="ref-cli-cmd-bootstrap-options-cloudformation-execution-policies"></a>

 `--cloudformation-execution-policies <ARRAY>`   
The managed IAM policy ARNs that should be attached to the deployment role assumed by AWS CloudFormation during deployment of your stacks.  
By default, stacks are deployed with full administrator permissions using the `AdministratorAccess` policy.  
You can provide this option multiple times in a single command. You can also provide multiple ARNs as a single string, with the individual ARNs separated by commas. The following is an example:  

```
$ cdk bootstrap --cloudformation-execution-policies "arn:aws:iam::aws:policy/AWSLambda_FullAccess,arn:aws:iam::aws:policy/AWSCodeDeployFullAccess"
```
To avoid deployment failures, be sure that the policies you specify are sufficient for any deployments that you will perform into the environment being bootstrapped.  
This option applies to modern bootstrapping only.  
The modern bootstrap template effectively grants the permissions implied by the `--cloudformation-execution-policies` to any AWS account in the `--trust` list. By default, this extends permissions to read and write to any resource in the bootstrapped account. Make sure to [configure the bootstrapping stack](bootstrapping-customizing.md) with policies and trusted accounts that you are comfortable with.
 *Default value*: `[]` <a name="ref-cli-cmd-bootstrap-options-custom-permissions-boundary"></a>

 `--custom-permissions-boundary, -cpb <STRING>`   
Specify the name of a permissions boundary to use.  
This option is not compatible with `--example-permissions-boundary`.  
 *Default value*: Undefined<a name="ref-cli-cmd-bootstrap-options-example-permissions-boundary"></a>

 `--example-permissions-boundary, -epb <BOOLEAN>`   
Use the example permissions boundary, supplied by the AWS CDK.  
This option is not compatible with `--custom-permissions-boundary`.  
The CDK supplied permissions boundary policy should be regarded as an example. Edit the content and reference the example policy if you are testing out the feature. Convert it into a new policy for actual deployments, if one does not already exist. The concern is to avoid drift. Most likely, a permissions boundary is maintained and has dedicated conventions, naming included.  
For more information on configuring permissions, including using permissions boundaries, see the [Security and Safety Dev Guide](https://github.com/aws/aws-cdk/wiki/Security-And-Safety-Dev-Guide).  
 *Default value*: Undefined<a name="ref-cli-cmd-bootstrap-options-execute"></a>

 `--execute <BOOLEAN>`   
Configure whether to execute the change set.  
 *Default value*: `true` <a name="ref-cli-cmd-bootstrap-options-force"></a>

 `--force, -f <BOOLEAN>`   
Always bootstrap, even if it would downgrade the bootstrap template version.  
 *Default value*: `false` <a name="ref-cli-cmd-bootstrap-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk bootstrap` command.<a name="ref-cli-cmd-bootstrap-options-previous-parameters"></a>

 `--previous-parameters <BOOLEAN>`   
Use previous values for existing parameters.  
Once a bootstrap template is deployed with a set of parameters, you must set this option to `false` to change any parameters on future deployments. When `false`, you must re-supply all previously supplied parameters.  
 *Default value*: `true` <a name="ref-cli-cmd-bootstrap-options-public-access-block-configuration"></a>

 `--public-access-block-configuration <BOOLEAN>`   
Block public access configuration on the Amazon S3 bucket that is created and used by the CDK CLI.  
 *Default value*: `true` <a name="ref-cli-cmd-bootstrap-options-qualifier"></a>

 `--qualifier <STRING>`   
Nine-digit string value that is unique for each bootstrap stack. This value is added to the physical ID of resources in the bootstrap stack.  
By providing a qualifier, you avoid resource name clashes when provisioning multiple bootstrap stacks in the same environment.  
When you change the qualifier, your CDK app must pass the changed value to the stack synthesizer. For more information, see [Customize CDK stack synthesis](configure-synth.md#bootstrapping-custom-synth).  
 *Default value*: `hnb659fds`. This value has no significance.<a name="ref-cli-cmd-bootstrap-options-show-template"></a>

 `--show-template <BOOLEAN>`   
Instead of bootstrapping, print the current bootstrap template to the standard output (`stdout`). You can then copy and customize the template as necessary.  
 *Default value*: `false` <a name="ref-cli-cmd-bootstrap-options-tags"></a>

 `--tags, -t <ARRAY>`   
Tags to add to the bootstrap stack in the format of `KEY=VALUE`.  
 *Default value*: `[]` <a name="ref-cli-cmd-bootstrap-options-template"></a>

 `--template <STRING>`   
Use the template from the given file instead of the built-in one.<a name="ref-cli-cmd-bootstrap-options-termination-protection"></a>

 `--termination-protection <BOOLEAN>`   
Toggle AWS CloudFormation termination protection on the bootstrap stack.  
When `true`, termination protection is enabled. This prevents the bootstrap stack from being accidentally deleted.  
To learn more about termination protection, see [Protecting a stack from being deleted](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-protect-stacks.html) in the * AWS CloudFormation User Guide*.  
 *Default value*: Undefined<a name="ref-cli-cmd-bootstrap-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
The name of the bootstrap stack to create.  
By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment. Use this option to provide a different name for your bootstrap stack.  
The CDK CLI uses this value to verify your bootstrap stack version.  
 *Default value*: `CDKToolkit`   
 *Required*: Yes<a name="ref-cli-cmd-bootstrap-options-trust"></a>

 `--trust <ARRAY>`   
The AWS account IDs that should be trusted to perform deployments into this environment.  
The account performing the bootstrapping will always be trusted.  
This option requires that you also provide `--cloudformation-execution-policies`.  
You can provide this option multiple times in a single command.  
This option applies to modern bootstrapping only.  
To add trusted accounts to an existing bootstrap stack, you must specify all of the accounts to trust, including those that you may have previously provided. If you only provide new accounts to trust, the previously trusted accounts will be removed.  
The following is an example that trusts two accounts:  

```
$ cdk bootstrap aws://123456789012/us-west-2 --trust 234567890123 --trust 987654321098 --cloudformation-execution-policies arn:aws:iam::aws:policy/AdministratorAccess
 ⏳  Bootstrapping environment aws://123456789012/us-west-2...
Trusted accounts for deployment: 234567890123, 987654321098
Trusted accounts for lookup: (none)
Execution policies: arn:aws:iam::aws:policy/AdministratorAccess
CDKToolkit: creating CloudFormation changeset...
 ✅  Environment aws://123456789012/us-west-2 bootstrapped.
```
The modern bootstrap template effectively grants the permissions implied by the `--cloudformation-execution-policies` to any AWS account in the `--trust` list. By default, this extends permissions to read and write to any resource in the bootstrapped account. Make sure to [configure the bootstrapping stack](bootstrapping-customizing.md) with policies and trusted accounts that you are comfortable with.
 *Default value*: `[]` <a name="ref-cli-cmd-bootstrap-options-trust-for-lookup"></a>

 `--trust-for-lookup <ARRAY>`   
The AWS account IDs that should be trusted to look up values in this environment.  
Use this option to give accounts permission to synthesize stacks that will be deployed into the environment, without actually giving them permission to deploy those stacks directly.  
You can provide this option multiple times in a single command.  
This option applies to modern bootstrapping only.  
 *Default value*: `[]` 

## Examples
<a name="ref-cli-cmd-bootstrap-examples"></a>

### Bootstrap the AWS environment specified in the prod profile
<a name="ref-cli-cmd-bootstrap-examples-1"></a>

```
$ cdk bootstrap --profile prod
```

### Deploy the bootstrap stack to environments foo and bar
<a name="ref-cli-cmd-bootstrap-examples-2"></a>

```
$ cdk bootstrap --app='node bin/main.js' foo bar
```

### Export the bootstrap template to customize it
<a name="ref-cli-cmd-bootstrap-examples-3"></a>

If you have specific requirements that are not met by the bootstrap template, you can customize it to fit your needs.

You can export the bootstrap template, modify it, and deploy it using AWS CloudFormation. The following is an example of exporting the existing template:

```
$ cdk bootstrap --show-template > bootstrap-template.yaml
```

You can also tell the CDK CLI to use a custom template. The following is an example:

```
$ cdk bootstrap --template my-bootstrap-template.yaml
```

### Bootstrap with a permissions boundary. Then, remove that permissions boundary
<a name="ref-cli-cmd-bootstrap-examples-4"></a>

To bootstrap with a custom permissions boundary, we run the following:

```
$ cdk bootstrap --custom-permissions-boundary my-permissions-boundary
```

To remove the permissions boundary, we run the following:

```
$ cdk bootstrap --no-previous-parameters
```

### Use a qualifier to distinguish resources that are created for a development environment
<a name="ref-cli-cmd-bootstrap-examples-5"></a>

```
$ cdk bootstrap --qualifier dev2024
```

# `cdk context`
<a name="ref-cli-cmd-context"></a>

Manage cached context values for your AWS CDK application.

 *Context* represents the configuration and environment information that can influence how your stacks are synthesized and deployed. Use `cdk context` to do the following:
+ View your configured context values.
+ Set and manage context values.
+ Remove context values.

## Usage
<a name="ref-cli-cmd-context-usage"></a>

```
$ cdk context <options>
```

## Options
<a name="ref-cli-cmd-context-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-context-options-clear"></a>

 `--clear <BOOLEAN>`   
Clear all context.<a name="ref-cli-cmd-context-options-force"></a>

 `--force, -f <BOOLEAN>`   
Ignore missing key error.  
 *Default value*: `false` <a name="ref-cli-cmd-context-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk context` command.<a name="ref-cli-cmd-context-options-reset"></a>

 `--reset, -e <STRING>`   
The context key, or its index, to reset.

# `cdk deploy`
<a name="ref-cli-cmd-deploy"></a>

Deploy one or more AWS CDK stacks into your AWS environment.

During deployment, the CDK CLI will output progress indicators, similar to what can be observed from the AWS CloudFormation console.

If the AWS environment is not bootstrapped, only stacks without assets and with synthesized templates under 51,200 bytes will successfully deploy.

## Usage
<a name="ref-cli-cmd-deploy-usage"></a>

```
$ cdk deploy <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-deploy-args"></a><a name="ref-cli-cmd-deploy-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to deploy.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-deploy-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-deploy-options-all"></a>

 `--all <BOOLEAN>`   
Deploy all stacks in your CDK app.  
 *Default value*: `false` <a name="ref-cli-cmd-deploy-options-asset-parallelism"></a>

 `--asset-parallelism <BOOLEAN>`   
Specify whether to build and publish assets in parallel.<a name="ref-cli-cmd-deploy-options-asset-prebuild"></a>

 `--asset-prebuild <BOOLEAN>`   
Specify whether to build all assets before deploying the first stack. This option is useful for failing Docker builds.  
 *Default value*: `true` <a name="ref-cli-cmd-deploy-options-build-exclude"></a>

 `--build-exclude, -E <ARRAY>`   
Do not rebuild asset with the given ID.  
This option can be specified multiple times in a single command.  
 *Default value*: `[]` <a name="ref-cli-cmd-deploy-options-change-set-name"></a>

 `--change-set-name <STRING>`   
The name of the AWS CloudFormation change set to create.  
This option is not compatible with `--method='direct'`.<a name="ref-cli-cmd-deploy-options-concurrency"></a>

 `--concurrency <NUMBER>`   
Deploy multiple stacks in parallel while accounting for inter-stack dependencies. Use this option to speed up deployments. You must still factor in AWS CloudFormation and other AWS account rate limiting.  
Provide a number to specify the maximum number of simultaneous deployments (dependency permitting) to perform.  
 *Default value*: `1` <a name="ref-cli-cmd-deploy-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
Only deploy requested stacks and don’t include dependencies.<a name="ref-cli-cmd-deploy-options-force"></a>

 `--force, -f <BOOLEAN>`   
When you deploy to update an existing stack, the CDK CLI will compare the template and tags of the deployed stack to the stack about to be deployed. If no changes are detected, the CDK CLI will skip deployment.  
To override this behavior and always deploy stacks, even if no changes are detected, use this option.  
 *Default value*: `false` <a name="ref-cli-cmd-deploy-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk deploy` command.<a name="ref-cli-cmd-deploy-options-hotswap"></a>

 `--hotswap <BOOLEAN>`   
Hotswap deployments for faster development. This option attempts to perform a faster, hotswap deployment if possible. For example, if you modify the code of a Lambda function in your CDK app, the CDK CLI will update the resource directly through service APIs instead of performing a CloudFormation deployment.  
If the CDK CLI detects changes that don’t support hotswapping, those changes will be ignored and a message will display. If you prefer to perform a full CloudFormation deployment as a fall back, use `--hotswap-fallback` instead.  
The CDK CLI uses your current AWS credentials to perform the API calls. It does not assume the roles from your bootstrap stack, even if the `@aws-cdk/core:newStyleStackSynthesis` feature flag is set to `true`. Those roles do not have the necessary permissions to update AWS resources directly, without using CloudFormation. For that reason, make sure that your credentials are for the same AWS account of the stacks that you are performing hotswap deployments against and that they have the necessary IAM permissions to update the resources.  
Hotswapping is currently supported for the following changes:  
+ Code assets (including Docker images and inline code), tag changes, and configuration changes (only description and environment variables are supported) of Lambda functions.
+ Lambda versions and alias changes.
+ Definition changes of AWS Step Functions state machines.
+ Container asset changes of Amazon ECS services.
+ Website asset changes of Amazon S3 bucket deployments.
+ Source and environment changes of AWS CodeBuild projects.
+ VTL mapping template changes for AWS AppSync resolvers and functions.
+ Schema changes for AWS AppSync GraphQL APIs.
Usage of certain CloudFormation intrinsic functions are supported as part of a hotswapped deployment. These include:  
+  `Ref` 
+  `Fn::GetAtt` – Only partially supported. Refer to [this implementation](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/evaluate-cloudformation-template.ts#L477-L492) for supported resources and attributes.
+  `Fn::ImportValue` 
+  `Fn::Join` 
+  `Fn::Select` 
+  `Fn::Split` 
+  `Fn::Sub` 
This option is also compatible with nested stacks.  
+ This option deliberately introduces drift in CloudFormation stacks in order to speed up deployments. For this reason, only use it for development purposes. Do not use this option for your production deployments.
+ This option is considered experimental and may have breaking changes in the future.
+ Defaults for certain parameters may be different with the hotswap parameter. For example, an Amazon ECS service’s minimum healthy percentage will currently be set at `0`. Review the source accordingly if this occurs.
 *Default value*: `false` <a name="ref-cli-cmd-deploy-options-hotswap-fallback"></a>

 `--hotswap-fallback <BOOLEAN>`   
This option is is similar to `--hotswap`. The difference being that `--hotswap-fallback` will fall back to perform a full CloudFormation deployment if a change is detected that requires it.  
For more information about this option, see `--hotswap`.  
 *Default value*: `false` <a name="ref-cli-cmd-deploy-options-ignore-no-stacks"></a>

 `--ignore-no-stacks <BOOLEAN>`   
Perform a deployment even if your CDK app doesn’t contain any stacks.  
This option is helpful in the following scenario: You may have an app with multiple environments, such as `dev` and `prod`. When starting development, your prod app may not have any resources, or the resources may be commented out. This will result in a deployment error with a message stating that the app has no stacks. Use `--ignore-no-stacks` to bypass this error.  
 *Default value*: `false` <a name="ref-cli-cmd-deploy-options-import-existing-resources"></a>

 `--import-existing-resources <BOOLEAN>`   
Import existing, unmanaged AWS CloudFormation resources from your AWS account.  
When you use this option, resources from your synthesized AWS CloudFormation template with the same custom name as existing unmanaged resources in the same account will be imported into your stack.  
You can use this option to import existing resources into new or existing stacks.  
You can import existing resources and deploy new resources in the same `cdk deploy` command.  
To learn more about custom names, see [Name type](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-name.html) in the * AWS CloudFormation User Guide*.  
To learn more about the `ImportExistingResources` CloudFormation parameter, see [AWS CloudFormation simplifies resource import with a new parameter for ChangeSets](https://aws.amazon.com/about-aws/whats-new/2023/11/aws-cloudformation-import-parameter-changesets/).  
For more information on using this option, see [Import existing resources](https://github.com/aws/aws-cdk-cli/tree/main/packages/aws-cdk#import-existing-resources) in the *aws-cdk-cli GitHub repository*.<a name="ref-cli-cmd-deploy-options-logs"></a>

 `--logs <BOOLEAN>`   
Show Amazon CloudWatch log in the standard output (`stdout`) for all events from all resources in the selected stacks.  
This option is only compatible with `--watch`.  
 *Default value*: `true` <a name="ref-cli-cmd-deploy-options-method"></a>

 `--method, -m <STRING>`   
Configure the method to perform a deployment.  
+  `change-set` – Default method. The CDK CLI creates a CloudFormation change set with the changes that will be deployed, then performs deployment.
+  `direct` – Do not create a change set. Instead, apply the change immediately. This is typically faster than creating a change set, but you lose deployment progress details in the CLI output.
+  `prepare-change-set` – Create change set but don’t perform deployment. This is useful if you have external tools that will inspect the change set or if you have an approval process for change sets.
 *Valid values*: `change-set`, `direct`, `prepare-change-set`   
 *Default value*: `change-set` <a name="ref-cli-cmd-deploy-options-notification-arns"></a>

 `--notification-arns <ARRAY>`   
The ARNs of Amazon SNS topics that CloudFormation will notify for stack related events.<a name="ref-cli-cmd-deploy-options-outputs-file"></a>

 `--outputs-file, -O <STRING>`   
The path to where stack outputs from deployments are written to.  
After deployment, stack outputs will be written to the specified output file in JSON format.  
You can configure this option in the project’s `cdk.json` file or at `~/.cdk.json` on your local development machine:  

```
{
   "app": "npx ts-node bin/myproject.ts",
   // ...
   "outputsFile": "outputs.json"
}
```
If multiple stacks are deployed, outputs are written to the same output file, organized by keys representing the stack name.<a name="ref-cli-cmd-deploy-options-parameters"></a>

 `--parameters <ARRAY>`   
Pass additional parameters to CloudFormation during deployment.  
This option accepts an array in the following format: `STACK:KEY=VALUE`.  
+  `STACK` – The name of the stack to associate the parameter with.
+  `KEY` – The name of the parameter from your stack.
+  `VALUE` – The value to pass at deployment.
If a stack name is not provided, or if `*` is provided as the stack name, parameters will be applied to all stacks being deployed. If a stack does not make use of the parameter, deployment will fail.  
Parameters do not propagate to nested stacks. To pass parameters to nested stacks, use the ` [NestedStack](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.NestedStack.html) ` construct.  
 *Default value*: `{}` <a name="ref-cli-cmd-deploy-options-previous-parameters"></a>

 `--previous-parameters <BOOLEAN>`   
Use previous values for existing parameters.  
When this option is set to `false`, you must specify all parameters on every deployment.  
 *Default value*: `true` <a name="ref-cli-cmd-deploy-options-progress"></a>

 `--progress <STRING>`   
Configure how the CDK CLI displays deployment progress.  
+  `bar` – Display stack deployment events as a progress bar, with the events for the resource currently being deployed.
+  `events` – Provide a complete history, including all CloudFormation events.
You can also configure this option in the project’s `cdk.json` file or at `~/.cdk.json` on your local development machine:  

```
{
   "progress": "events"
}
```
 *Valid values*: `bar`, `events`   
 *Default value*: `bar` <a name="ref-cli-cmd-deploy-options-require-approval"></a>

 `--require-approval <STRING>`   
Specify what changes require manual approval.  
+  `any-change` – Manual approval required for any change to the stack.
+  `broadening` – Manual approval required if changes involve a broadening of permissions or security group rules.
+  `never` – Approval is not required.
 *Valid values*: `any-change`, `broadening`, `never`   
 *Default value*: `broadening` <a name="ref-cli-cmd-deploy-options-rollback"></a>

 `--rollback` \$1 `--no-rollback`, `-R`   
During deployment, if a resource fails to be created or updated, the deployment will roll back to the latest stable state before the CDK CLI returns. All changes made up to that point will be undone. Resources that were created will be deleted and updates that were made will be rolled back.  
Specify `--no-rollback` to turn off this behavior. If a resource fails to be created or updated, the CDK CLI will leave changes made up to that point in place and return. This will leave your deployment in a failed, paused state. From here, you can update your code and try the deployment again. This may be helpful in development environments where you are iterating quickly.  
If a deployment performed with `--no-rollback` fails, and you decide that you want to rollback the deployment, you can use the `cdk rollback` command. For more information, see [cdk rollback](ref-cli-cmd-rollback.md).  
With `--no-rollback`, deployments that cause resource replacements will always fail. You can only use this option value for deployments that update or create new resources.
 *Default value*: `--rollback` <a name="ref-cli-cmd-deploy-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
The name of the existing CDK Toolkit stack.  
By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment. Use this option to provide a different name for your bootstrap stack.  
The CDK CLI uses this value to verify your bootstrap stack version.<a name="ref-cli-cmd-deploy-options-watch"></a>

 `--watch <BOOLEAN>`   
Continuously observe CDK project files, and deploy the specified stacks automatically when changes are detected.  
This option implies `--hotswap` by default.  
This option has an equivalent CDK CLI command. For more information, see [cdk watch](ref-cli-cmd-watch.md).

## Examples
<a name="ref-cli-cmd-deploy-examples"></a>

### Deploy the stack named MyStackName
<a name="ref-cli-cmd-deploy-examples-1"></a>

```
$ cdk deploy MyStackName --app='node bin/main.js'
```

### Deploy multiple stacks in an app
<a name="ref-cli-cmd-deploy-examples-2"></a>

Use `cdk list` to list your stacks:

```
$ cdk list
CdkHelloWorldStack
CdkStack2
CdkStack3
```

To deploy all stacks, use the `--all` option:

```
$ cdk deploy --all
```

To choose which stacks to deploy, provide stack names as arguments:

```
$ cdk deploy CdkHelloWorldStack CdkStack3
```

### Deploy pipeline stacks
<a name="ref-cli-cmd-deploy-examples-3"></a>

Use `cdk list` to show stack names as paths, showing where they are in the pipeline hierarchy:

```
$ cdk list
PipelineStack
PiplelineStack/Prod
PipelineStack/Prod/MyService
```

Use the `--all` option or the wildcard `*` to deploy all stacks. If you have a hierarchy of stacks as described above, `--all` and `*` will only match stacks on the top level. To match all stacks in the hierarchy, use `**`.

You can combine these patterns. The following deploys all stacks in the `Prod` stage:

```
$ cdk deploy PipelineStack/Prod/**
```

### Pass parameters at deployment
<a name="ref-cli-cmd-deploy-examples-4"></a>

Define parameters in your CDK stack. The following is an example that creates a parameter named `TopicNameParam` for an Amazon SNS topic:

```
new sns.Topic(this, 'TopicParameter', {
    topicName: new cdk.CfnParameter(this, 'TopicNameParam').value.toString()
});
```

To provide a parameter value of `parameterized`, run the following:

```
$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterized"
```

You can override parameter values by using the `--force` option. The following is an example of overriding the topic name from a previous deployment:

```
$ cdk deploy --parameters "MyStackName:TopicNameParam=parameterName" --force
```

### Write stack outputs to a file after deployment
<a name="ref-cli-cmd-deploy-examples-5"></a>

Define outputs in your CDK stack file. The following is an example that creates an output for a function ARN:

```
const fn = new lambda.Function(this, "fn", {
  handler: "index.handler",
  code: lambda.Code.fromInline(`exports.handler = \${handler.toString()}`),
  runtime: lambda.Runtime.NODEJS_LATEST
});

new cdk.CfnOutput(this, 'FunctionArn', {
  value: fn.functionArn,
});
```

Deploy the stack and write outputs to `outputs.json`:

```
$ cdk deploy --outputs-file outputs.json
```

The following is an example of `outputs.json` after deployment:

```
{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  }
}
```

From this example, the key `FunctionArn` corresponds to the logical ID of the `CfnOutput` instance.

The following is an example of `outputs.json` after deployment when multiple stacks are deployed:

```
{
  "MyStack": {
    "FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:MyStack-fn5FF616E3-G632ITHSP5HK"
  },
  "AnotherStack": {
    "VPCId": "vpc-z0mg270fee16693f"
  }
}
```

### Modify the deployment method
<a name="ref-cli-cmd-deploy-examples-6"></a>

To deploy faster, without using change sets, use `--method='direct'`:

```
$ cdk deploy --method='direct'
```

To create a change set but don’t deploy, use `--method='prepare-change-set'`. By default, a change set named `cdk-deploy-change-set` will be created. If a previous change set with this name exists, it will be overwritten. If no changes are detected, an empty change set is still created.

You can also name your change set. The following is an example:

```
$ cdk deploy --method='prepare-change-set' --change-set-name='MyChangeSetName'
```

# `cdk destroy`
<a name="ref-cli-cmd-destroy"></a>

Delete one or more AWS CDK stacks from your AWS environment.

When you delete a stack, resources in the stack will be destroyed, unless they were configured with a `DeletionPolicy` of `Retain`.

During stack deletion, this command will output progress information similar to `cdk deploy` behavior.

## Usage
<a name="ref-cli-cmd-destroy-usage"></a>

```
$ cdk destroy <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-destroy-args"></a><a name="ref-cli-cmd-destroy-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to delete.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-destroy-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-destroy-options-all"></a>

 `--all <BOOLEAN>`   
Destroy all available stacks.  
 *Default value*: `false` <a name="ref-cli-cmd-destroy-options-concurrency"></a>

 `--concurrency <NUMBER>`   
Destroy multiple stacks in parallel while accounting for inter-stack dependencies. Use this option to speed up destroy operations. You must still factor in AWS CloudFormation and other AWS account rate limiting.  
Provide a number to specify the maximum number of simultaneous destroy operations (dependency permitting) to perform.  
 *Default value*: `1` <a name="ref-cli-cmd-destroy-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
Only destroy requested stacks and don’t include dependencies.<a name="ref-cli-cmd-destroy-options-force"></a>

 `--force, -f <BOOLEAN>`   
Do not ask for confirmation before destroying the stacks.<a name="ref-cli-cmd-destroy-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk destroy` command.

## Examples
<a name="ref-cli-cmd-destroy-examples"></a>

### Delete a stack named MyStackName
<a name="ref-cli-cmd-destroy-examples-1"></a>

```
$ cdk destroy --app='node bin/main.js' <MyStackName>
```

### Delete multiple stacks in parallel
<a name="ref-cli-cmd-destroy-examples-2"></a>

Use the `--concurrency` option with `--all` to delete all stacks in parallel:

```
$ cdk destroy --all --concurrency 5
```

# `cdk diff`
<a name="ref-cli-cmd-diff"></a>

Perform a diff to see infrastructure changes between AWS CDK stacks.

This command is typically used to compare differences between the current state of stacks in your local CDK app against deployed stacks. However, you can also compare a deployed stack with any local AWS CloudFormation template.

## Usage
<a name="ref-cli-cmd-diff-usage"></a>

```
$ cdk diff <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-diff-args"></a><a name="ref-cli-cmd-diff-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to perform a diff.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-diff-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-diff-options-method"></a>

 `--method, -m <STRING>`   
Specifies how to compute the diff.  
+  `auto` – Default. Creates an AWS CloudFormation change set to display accurate replacement information. If the change set can’t be created (for example, due to missing permissions), falls back to a template-only diff. Uses the deploy role.
+  `change-set` – Always creates a change set and fails if it can’t be created. Use this when you need guaranteed accuracy. Uses the deploy role.
+  `template` – Compares CloudFormation templates directly. Faster, but less accurate. Any change detected to properties that require resource replacement is displayed as a resource replacement, even if the change is purely cosmetic. Uses the lookup role.

   *Default value*: `auto` <a name="ref-cli-cmd-diff-options-change-set"></a>

 `--change-set <BOOLEAN>` *(deprecated)*   
Specifies whether to create a change set to analyze resource replacements. Use `--method` instead.  
 `--change-set` maps to `--method=auto`. `--no-change-set` maps to `--method=template`.<a name="ref-cli-cmd-diff-options-context-lines"></a>

 `--context-lines <NUMBER>`   
Number of context lines to include in arbitrary JSON diff rendering.  
 *Default value*: `3` <a name="ref-cli-cmd-diff-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
Only diff requested stacks and don’t include dependencies.<a name="ref-cli-cmd-diff-options-fail"></a>

 `--fail <BOOLEAN>`   
Fail and exit with a code of `1` if differences are detected.<a name="ref-cli-cmd-diff-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk diff` command.<a name="ref-cli-cmd-diff-options-processed"></a>

 `--processed <BOOLEAN>`   
Specify whether to compare against the template with CloudFormation transforms already processed.  
 *Default value*: `false` <a name="ref-cli-cmd-diff-options-quiet"></a>

 `--quiet, -q <BOOLEAN>`   
Do not print the CDK stack name and default `cdk diff` message to `stdout` when no changes are detected.  
 *Default value*: `false` <a name="ref-cli-cmd-diff-options-security-only"></a>

 `--security-only <BOOLEAN>`   
Only diff for broadened security changes.  
 *Default value*: `false` <a name="ref-cli-cmd-diff-options-strict"></a>

 `--strict <BOOLEAN>`   
Modify `cdk diff` behavior to be more precise or stringent. When true, the CDK CLI will not filter out ` AWS::CDK::Metadata` resources or unreadable non-ASCII characters.  
 *Default value*: `false` <a name="ref-cli-cmd-diff-options-template"></a>

 `--template <STRING>`   
The path to the CloudFormation template to compare a CDK stack with. Implies `--method=template`.

## Examples
<a name="ref-cli-cmd-diff-examples"></a>

### Diff against the currently deployed stack named MyStackName
<a name="ref-cli-cmd-diff-examples-1"></a>

The CDK CLI uses the following symbols in the diff output:
+  `[+]` – Identifies code or resources that will be added if you deploy your changes.
+  `[-]` – Identifies code or resources that will be removed if you deploy your changes.
+  `[~]` – Identifies a resource or property that will be modified if you deploy your changes.

The following is an example that shows a diff of local changes to a Lambda function:

```
$ cdk diff MyStackName
start: Building <asset-hash>:<account:Region>
success: Built <asset-hash>:<account:Region>
start: Publishing <asset-hash>:<account:Region>
success: Published <asset-hash>:<account:Region>
Hold on while we create a read-only change set to get a diff with accurate replacement information (use --method=template to use a less accurate but faster template-only diff)
Stack MyStackName
Resources
[~] AWS::Lambda::Function HelloWorldFunction <resource-logical-ID>
 └─ [~] Code
     └─ [~] .ZipFile:
         ├─ [-]
        exports.handler = async function(event) {
          return {
            statusCode: 200,
            body: JSON.stringify('Hello World!'),
          };
        };

         └─ [+]
        exports.handler = async function(event) {
          return {
            statusCode: 200,
            body: JSON.stringify('Hello from CDK!'),
          };
        };



✨  Number of stacks with differences: 1
```

A `[~]` indicator for resources that will be modified does not always mean a full resource replacement:
+ Some resource properties, like `Code`, will update the resource.
+ Some resource properties, like `FunctionName`, may cause a full resource replacement.

### Diff against a specific CloudFormation template
<a name="ref-cli-cmd-diff-examples-2"></a>

```
$ cdk diff MyStackName --app='node bin/main.js' --template-path='./MyStackNameTemplate.yaml'
```

### Diff a local stack with its deployed stack. don’t print to stdout if no changes are detected
<a name="ref-cli-cmd-diff-examples-3"></a>

```
$ cdk diff MyStackName --app='node bin/main.js' --quiet
```

# `cdk docs`
<a name="ref-cli-cmd-docs"></a>

Open AWS CDK documentation in your browser.

## Usage
<a name="ref-cli-cmd-docs-usage"></a>

```
$ cdk docs <options>
```

## Options
<a name="ref-cli-cmd-docs-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-docs-options-browser"></a>

 `--browser, -b <STRING>`   
The command to use to open the browser, using `%u` as a placeholder for the path of the file to open.  
 *Default value*: `open %u` <a name="ref-cli-cmd-docs-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk docs` command.

## Examples
<a name="ref-cli-cmd-docs-examples"></a>

### Open AWS CDK documentation in Google Chrome
<a name="ref-cli-cmd-docs-examples-1"></a>

```
$ cdk docs --browser='chrome %u'
```

# `cdk doctor`
<a name="ref-cli-cmd-doctor"></a>

Inspect and display useful information about your local AWS CDK project and development environment.

This information can help with troubleshooting CDK issues and should be provided when submitting bug reports.

## Usage
<a name="ref-cli-cmd-doctor-usage"></a>

```
$ cdk doctor <options>
```

## Options
<a name="ref-cli-cmd-doctor-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-doctor-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk doctor` command.

## Examples
<a name="ref-cli-cmd-doctor-examples"></a>

### Simple example of the `cdk doctor` command
<a name="ref-cli-cmd-doctor-examples-1"></a>

```
$ cdk doctor
ℹ️ CDK Version: 1.0.0 (build e64993a)
ℹ️ AWS environment variables:
  - AWS_EC2_METADATA_DISABLED = 1
  - AWS_SDK_LOAD_CONFIG = 1
```

# `cdk drift`
<a name="ref-cli-cmd-drift"></a>

Detect configuration drift for resources that you define, manage, and deploy using the AWS Cloud Development Kit (AWS CDK). Drift occurs when a stack’s actual configuration differs from its expected configuration, which happens when resources are modified outside of AWS CloudFormation.

This command identifies resources that have been modified (for example, through the AWS Console or AWS CLI) by comparing their current state against their expected configuration. These modifications can cause unexpected behavior in your infrastructure.

During drift detection, the CDK CLI will output progress indicators and results, showing:
+ Resources that have drifted from their expected configuration.
+ The total number of resources with drift.
+ A summary indicating whether drift was detected in the stack.

**Important**  
The `cdk drift` and `cdk diff` commands work differently:  
 `cdk drift` calls CloudFormation’s drift detection operation to compare the actual state of resources in AWS ("reality") against their expected configuration in CloudFormation. Not all AWS resources support drift detection. For a list of supported resources, see [Resource type support](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html) in the * AWS CloudFormation User Guide*.
 `cdk diff` compares the CloudFormation template synthesized from your local CDK code against the template of the deployed CloudFormation stack.
Use `cdk drift` when you need to verify if resources have been modified outside of CloudFormation (for example, through the AWS Console or AWS CLI). Use `cdk diff` when you want to preview how your local code changes would affect your infrastructure before deployment.

## Usage
<a name="ref-cli-cmd-drift-usage"></a>

```
$ cdk drift <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-drift-args"></a><a name="ref-cli-cmd-drift-args-stack-name"></a>

 **Stack name**   
The name of the stack that you want to check for drift. The stack must be previously deployed to CloudFormation to perform drift detection.  
 *Type*: String  
 *Required*: No  
If no stack is specified, drift detection will be performed on all stacks defined in your CDK app.

## Options
<a name="ref-cli-cmd-drift-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-drift-options-fail"></a>

 `--fail <BOOLEAN>`   
Return with exit code 1 if drift is detected.  
 *Default value*: `false` <a name="ref-cli-cmd-drift-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk drift` command.

## Examples
<a name="ref-cli-cmd-drift-examples"></a>

### Check drift for a specific stack
<a name="ref-cli-cmd-drift-examples-stack"></a>

```
$ cdk drift MyStackName
```

The command will output results similar to:

```
Stack MyStackName
Modified Resources
[~] AWS::Lambda::Function MyFunction MyLambdaFunc1234ABCD
 └─ [~] /Description
     ├─ [-] My original hello world Lambda function
     └─ [+] My drifted hello world Lambda function

1 resource has drifted from their expected configuration

✨  Number of resources with drift: 1
```

### Check drift when resources have been deleted
<a name="ref-cli-cmd-drift-examples-deleted"></a>

The following example shows what the output looks like when resources have been both modified and deleted:

```
Stack MyStackName
Modified Resources
[~] AWS::Lambda::Function MyFunction MyLambdaFunc1234ABCD
 └─ [~] /Description
     ├─ [-] My original hello world Lambda function
     └─ [+] My drifted hello world Lambda function
Deleted Resources
[-] AWS::CloudWatch::Alarm MyAlarm MyCWAlarmABCD1234

2 resources have drifted from their expected configuration

✨  Number of resources with drift: 2
```

### Check drift with exit code
<a name="ref-cli-cmd-drift-examples-fail"></a>

To have the command return a non-zero exit code if drift is detected:

```
$ cdk drift MyStackName --fail
```

This is useful in CI/CD pipelines to automatically detect and respond to infrastructure drift.

# `cdk flags`
<a name="ref-cli-cmd-flags"></a>

View and modify your feature flag configurations for the CDK CLI.

Feature flags control the behavior of the CDK CLI and you can use them to enable or disable specific features. Use the `cdk flags` command to view your current feature flag configurations and modify them as needed.

**Warning**  
The `cdk flags` command is in development for the AWS CDK. The current features of this command are considered production-ready and safe to use. However, the scope of this command and its features are subject to change. Therefore, you must opt in by providing the `unstable=flags` option to use this command.

## Usage
<a name="ref-cli-cmd-flags-usage"></a>

```
$ cdk flags <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-flags-args"></a><a name="ref-cli-cmd-flags-args-flagname"></a>

 **FLAGNAME**   
The name of the specific feature flag that you want to view or modify.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-flags-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-flags-options-set"></a>

 `--set <BOOLEAN>`   
Modify a feature flag configuration.<a name="ref-cli-cmd-flags-options-all"></a>

 `--all <BOOLEAN>`   
Modify or view all feature flags.<a name="ref-cli-cmd-flags-options-recommended"></a>

 `--recommended <BOOLEAN>`   
Change flags to recommended states.<a name="ref-cli-cmd-flags-options-default"></a>

 `--default <BOOLEAN>`   
Change flags to default states.<a name="ref-cli-cmd-flags-options-unconfigured"></a>

 `--unconfigured <BOOLEAN>`   
Modify unconfigured feature flags.<a name="ref-cli-cmd-flags-options-value"></a>

 `--value <STRING>`   
The value to set the feature flag configuration to.  
 *requiresArg*: true<a name="ref-cli-cmd-flags-options-safe"></a>

 `--safe <BOOLEAN>`   
Enable all feature flags that do not impact your application.<a name="ref-cli-cmd-flags-options-interactive"></a>

 `--interactive, -i <BOOLEAN>`   
Interactive option for the flags command.

## Examples
<a name="ref-cli-cmd-flags-examples"></a>

### View feature flag configurations
<a name="ref-cli-cmd-flags-examples-1"></a>

Run `cdk flags` to view a report of your feature flag configurations that differ from our recommended states. Unconfigured flags are labeled with `<unset>` to indicate that the flag currently has no value. The flags are displayed in the following order:
+ Flags set to a value that doesn’t match our recommended value
+ Flags that you haven’t configured

```
$ cdk flags --unstable=flags
Feature Flag                           Recommended                       User
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         <unset>
```

You can also run `cdk flags --all` to see a report of all feature flags in the following order:
+ Flags set to a value that matches our recommended value
+ Flags set to a value that doesn’t match our recommended value
+ Flags that you haven’t configured

```
$ cdk flags --unstable=flags --all
Feature Flag                              Recommended                     User
@aws-cdk/...                                true                         true
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         <unset>
```

### Modify feature flag values
<a name="ref-cli-cmd-flags-examples-2"></a>

To modify your feature flags interactively, run `cdk flags --interactive` (or `cdk flags -i`) to view a list of menu options.

To change every feature flag to our recommended value, run `cdk flags --set --recommended --all`. This command keeps your feature flag configuration up-to-date with the latest CDK feature flag configurations. Be aware that running this command can potentially overwrite existing configured values.

```
$ cdk flags --unstable=flags --set --recommended --all
Feature Flag                              Recommended Value            User Value
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         false
* @aws-cdk/...                              true                         <unset>
  Synthesizing...
    Resources
    [~] AWS::S3::Bucket MyBucket
    └─ [~] Properties
        └─ [~] Encryption
                ...
    Number of stacks with differences: 2
  Do you want to accept these changes? (y/n) y
  Resynthesizing...
```

If you want to preserve the state of your existing configured flags, run `cdk flags --set --recommended --unconfigured`. This option changes only the unconfigured feature flags to our recommended values.

```
$ cdk flags --unstable=flags --set --recommended --unconfigured
Feature Flag                              Recommended Value            User Value
* @aws-cdk/...                              true                         <unset>
* @aws-cdk/...                              true                         <unset>
  Synthesizing...
    Resources
    [~] AWS::S3::Bucket MyBucket
    └─ [~] Properties
        └─ [~] Encryption
            ├─ [-] None
            └─ [+] ServerSideEncryptionConfiguration:
                    - ...
            ...
    Number of stacks with differences: 2
  Do you want to accept these changes? (y/n) y
  Resynthesizing...
```

If you want to ensure that any unconfigured feature flags don’t interfere with your application, run the `cdk flags --set --default --unconfigured` command to change the unconfigured flags to their default values. For example, if `@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021` is unconfigured, a notification displays after running `cdk synth`. However, if you set the flag to its default state (false), it will be configured, turned off, and not impact your application.

```
$ cdk flags --unstable=flags --set --default --unconfigured
Feature Flag                              Recommended Value            User Value
* @aws-cdk/...                              true                         <unset>
* @aws-cdk/...                              true                         <unset>
  Synthesizing...

  Do you want to accept these changes? (y/n) y
  Resynthesizing...
```

### Inspect specific feature flags
<a name="ref-cli-cmd-flags-examples-3"></a>

#### View more information about a flag
<a name="_view_more_information_about_a_flag"></a>

In addition to running `cdk flags` and `cdk flags --all` to view your feature flag configuration, you can also utilize `cdk flags "FLAGNAME"` to inspect a specific feature flag and find out what the flag does. This can be helpful in cases where you want to understand a particular flag and its impact on your application.

```
$ cdk flags --unstable=flags "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021"
    Description: Enable this feature flag to have cloudfront distributions use the security policy TLSv1.2_2021 by default.
    Recommended Value: true
    User Value: true
```

#### Filter flags by substring
<a name="_filter_flags_by_substring"></a>

You can also run `cdk flags substring` to view all matching feature flags. If there is only one feature flag that matches that substring, specific details are displayed.

```
$ cdk flags --unstable=flags ebs
@aws-cdk/aws-ec2:ebsDefaultGp3Volume
    Description: When enabled, the default volume type of the EBS volume will be GP3
    Recommended Value: true
    User Value: true
```

If multiple flags match the substring, all matching flags are displayed in a table. If you enter multiple substrings, all matching flags that contain any of the substrings are returned.

```
$ cdk flags --unstable=flags s3 lambda
Feature Flag                              Recommended                     User
* @aws-cdk/s3...                            true                         false
* @aws-cdk/lambda...                        true                         false
* @aws-cdk/lambda...                        true                         <unset>
```

#### Modify a specific flag
<a name="_modify_a_specific_flag"></a>

If you need to modify the value of a flag and want to make sure you’re setting it to a correct and supported state, run `cdk flags --set "FLAGNAME" --value="state"`.

```
$ cdk flags --unstable=flags --set "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021" --value="true"
  Synthesizing...
    Resources
    [~] AWS::CloudFront::Distribution MyDistribution
    └─ [~] Properties
        └─ [~] DefaultSecurityPolicy
            ├─ [-] TLSv1.0
            └─ [+] TLSv1.2_2021
                    - ...
    Number of stacks with differences: 2
  Do you want to accept these changes? (y/n) y
  Resynthesizing...
```

# `cdk gc`
<a name="ref-cli-cmd-gc"></a>

Use the AWS Cloud Development Kit (AWS CDK) command line interface (CLI) `cdk gc` command to perform garbage collection on unused assets stored in the resources of your bootstrap stack. Use this command to view, manage, and delete assets that you no longer need.

For Amazon Simple Storage Service (Amazon S3) assets, the CDK CLI will check existing AWS CloudFormation templates in the same environment to see if they are referenced. If not referenced, they will be considered unused and eligible for garbage collection actions.

**Warning**  
The `cdk gc` command is in development for the AWS CDK. The current features of this command are considered production-ready and safe to use. However, the scope of this command and its features are subject to change. Therefore, you must opt in by providing the `unstable=gc` option to use this command.

## Usage
<a name="ref-cli-cmd-gc-usage"></a>

```
$ cdk gc <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-gc-args"></a><a name="ref-cli-cmd-gc-args-env"></a>

 ** AWS environment**   
The target AWS environment to perform garbage collection actions on.  
When providing an environment, use the following format: `aws://<account-id>/<region>`. For example, `aws://<123456789012>/<us-east-1>`.  
This argument can be provided multiple times in a single command to perform garbage collection actions on multiple environments.  
By default, the CDK CLI will perform garbage collection actions on all environments that you reference in your CDK app or provide as arguments. If you don’t provide an environment, the CDK CLI will determine the environment from default sources. These sources include environments that you specify using the `--profile` option, environment variables, or default AWS CLI sources.

## Options
<a name="ref-cli-cmd-gc-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-gc-options-action"></a>

 `--action <STRING>`   
The action that `cdk gc` performs on your assets during a garbage collection.  
+  `delete-tagged` – Deletes assets that have been tagged with a date within the range of buffer days that you provide, but does not tag newly identified unused assets.
+  `full` – Perform all garbage collection actions. This includes deleting assets within the range of buffer days that you provide and tagging newly identified unused assets.
+  `print` – Outputs the number of unused assets at the command prompt but doesn’t make any actual changes within your AWS environment.
+  `tag` – Tags any newly identified unused assets, but doesn’t delete any assets within the range of buffer days that you provide.
 *Accepted values*: `delete-tagged`, `full`, `print`, `tag`   
 *Default value*: `full` <a name="ref-cli-cmd-gc-options-bootstrap-stack-name"></a>

 `--bootstrap-stack-name <STRING>`   
The name of the CDK bootstrap stack in your AWS environment. Provide this option if you customized your bootstrap stack name. If you are using the default `CDKToolkit` stack name, you don’t have to provide this option.  
 *Default value*: `CDKToolkit` <a name="ref-cli-cmd-gc-options-confirm"></a>

 `--confirm <BOOLEAN>`   
Specify whether the CDK CLI will request manual confirmation from you before deleting any assets.  
Specify `false` to automatically delete assets without prompting you for manual confirmation.  
 *Default value*: `true` <a name="ref-cli-cmd-gc-options-created-buffer-days"></a>

 `--created-buffer-days <NUMBER>`   
The number of days an asset must exist before it is eligible for garbage collection actions.  
When you provide a number, assets that have not existed beyond your specified number of days are filtered out from garbage collection actions.  
 *Default value*: `1` <a name="ref-cli-cmd-gc-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk gc` command.<a name="ref-cli-cmd-gc-options-rollback-buffer-days"></a>

 `--rollback-buffer-days <NUMBER>`   
The number of days an asset must be tagged as isolated before it is eligible for garbage collection actions.  
When you provide a number, the CDK CLI will tag unused assets with the current date instead of deleting them. The CDK CLI will also check if any assets have been tagged during previous runs of the `cdk gc` command. Previously tagged assets that fall within the range of buffer days you provide will be deleted.  
 *Default value*: `0` <a name="ref-cli-cmd-gc-options-type"></a>

 `--type <STRING>`   
The bootstrap resource type within your bootstrap stack to perform garbage collection actions on.  
+  `all` – Perform garbage collection actions on all bootstrapped resources.
+  `ecr` – Perform garbage collection actions on assets in the Amazon Elastic Container Registry (Amazon ECR) repository of your bootstrap stack.
+  `s3` – Perform garbage collection actions on assets in the Amazon S3 bucket of your bootstrap stack.
 *Accepted values*: `all`, `ecr`, `s3`   
 *Default value*: `all` <a name="ref-cli-cmd-gc-options-unstable"></a>

 `--unstable <STRING>`   
Allow the usage of CDK CLI commands that are still in development.  
This option is required to use any CDK CLI command that is still in development and subject to change.  
This option can be provided multiple times in a single command.  
To use `cdk gc`, provide `--unstable=gc`.

## Examples
<a name="ref-cli-cmd-gc-examples"></a>

### Basic examples
<a name="ref-cli-cmd-gc-examples-basic"></a>

The following example prompts you for manual confirmation to perform default garbage collection actions on assets in the Amazon S3 bucket of your bootstrap stack:

```
$ cdk gc --unstable=gc --type=s3

 ⏳  Garbage Collecting environment aws://<account-id>/<region>...
Found 99 assets to delete based off of the following criteria:
- assets have been isolated for > 0 days
- assets were created > 1 days ago

Delete this batch (yes/no/delete-all)?
```

The following example performs garbage collection actions on a range of assets in the Amazon S3 bucket of your bootstrap stack. This range includes assets that have been previously tagged by `cdk gc` for over 30 days and have been created 10 days or older. This command will prompt for manual confirmation before deleting any assets:

```
$ cdk gc --unstable=gc --type=s3 --rollback-buffer-days=30 --created-buffer-days=10
```

The following example performs the action of deleting previously tagged assets in the Amazon S3 bucket of your bootstrap stack that have been unused for longer than 30 days:

```
$ cdk gc --unstable=gc --type=s3 --action=delete-tagged --rollback-buffer-days=30
```

# `cdk import`
<a name="ref-cli-cmd-import"></a>

Use [AWS CloudFormation resource imports](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import.html) to import existing AWS resources into a CDK stack.

With this command, you can take existing resources that were created using other methods and start managing them using the AWS CDK.

When considering moving resources into CDK management, sometimes creating new resources is acceptable, such as with IAM roles, Lambda functions, and event rules. For other resources, such as stateful resources like Amazon S3 buckets and DynamoDB tables, creating new resources can cause impacts to your service. You can use `cdk import` to import existing resources with minimal disruption to your services. For a list of supported AWS resources, see [Resource type support](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-supported-resources.html) in the * AWS CloudFormation User Guide*.

 **To import an existing resource to a CDK stack**   

1. Run a `cdk diff` to make sure your CDK stack has no pending changes. When performing a `cdk import`, the only changes allowed in an import operation are the addition of new resources being imported.

1. Add constructs for the resources you want to import to your stack. For example, add the following for an Amazon S3 bucket:

   ```
   new s3.Bucket(this, 'ImportedS3Bucket', {});
   ```

   Do not add any other changes. You must also make sure to exactly model the state that the resource currently has. For the bucket example, be sure to include AWS KMS keys, lifecycle policies, and anything else that is relevant about the bucket. Otherwise, subsequent update operations may not do what you expect.

1. Run `cdk import`. If there are multiple stacks in the CDK app, pass a specific stack name as an argument.

1. The CDK CLI will prompt you to pass in the actual names of the resources you are importing. After you provide this information, import will begin.

1. When `cdk import` reports success, the resource will be managed by the CDK. Any subsequent changes in the construct configuration will be reflected on the resource.

This feature currently has the following limitations:
+ Importing resources into nested stacks isn’t possible.
+ There is no check on whether the properties you specify are correct and complete for the imported resource. Try starting a drift detection operation after importing.
+ Resources that depend on other resources must all be imported together, or individually, in the right order. Otherwise, the CloudFormation deployment will fail with unresolved references.
+ This command uses the deploy role credentials, which is necessary to read the encrypted staging bucket. This requires version 12 of the bootstrap template, which includes the necessary IAM permissions for the deploy role.

## Usage
<a name="ref-cli-cmd-import-usage"></a>

```
$ cdk import <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-import-args"></a><a name="ref-cli-cmd-import-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to import resources to. This argument can be provided multiple times in a single command.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-import-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-import-options-change-set-name"></a>

 `--change-set-name <STRING>`   
The name of the CloudFormation change set to create.<a name="ref-cli-cmd-import-options-execute"></a>

 `--execute <BOOLEAN>`   
Specify whether to execute change set.  
 *Default value*: `true` <a name="ref-cli-cmd-import-options-force"></a>

 `--force, -f <BOOLEAN>`   
By default, the CDK CLI exits the process if the template diff includes updates or deletions. Specify `true` to override this behavior and always continue with importing.<a name="ref-cli-cmd-import-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk import` command.<a name="ref-cli-cmd-import-options-record-resource-mapping"></a>

 `--record-resource-mapping, -r <STRING>`   
Use this option to generate a mapping of existing physical resources to the CDK resources that will be imported. The mapping will be written to the file path that you provide. No actual import operations will be performed.<a name="ref-cli-cmd-import-options-resource-mapping"></a>

 `--resource-mapping, -m <STRING>`   
Use this option to specify a file that defines your resource mapping. The CDK CLI will use this file to map physical resources to resources for import instead of interactively asking you.  
This option can be run from scripts.<a name="ref-cli-cmd-import-options-rollback"></a>

 `--rollback <BOOLEAN>`   
Roll back the stack to stable state on failure.  
To specify `false`, you can use `--no-rollback` or `-R`.  
Specify `false` to iterate more rapidly. Deployments containing resource replacements will always fail.  
 *Default value*: `true` <a name="ref-cli-cmd-import-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
The name of the CDK Toolkit stack to create.  
By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment. Use this option to provide a different name for your bootstrap stack.  
The CDK CLI uses this value to verify your bootstrap stack version.

# `cdk init`
<a name="ref-cli-cmd-init"></a>

Create a new AWS CDK project from a template.

## Usage
<a name="ref-cli-cmd-init-usage"></a>

```
$ cdk init <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-init-args"></a><a name="ref-cli-cmd-init-args-template-type"></a>

 **Template type**   
The CDK template type to initialize a new CDK project from.  
+  `app` – Template for a CDK application.
+  `lib` – Template for an AWS Construct Library.
+  `sample-app` – Example CDK application that includes some constructs.
 *Valid values*: `app`, `lib`, `sample-app` 

## Options
<a name="ref-cli-cmd-init-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-init-options-generate-only"></a>

 `--generate-only <BOOLEAN>`   
Specify this option to generate project files without initiating additional operations such as setting up a git repository, installing dependencies, or compiling the project.  
 *Default value*: `false` <a name="ref-cli-cmd-init-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk init` command.<a name="ref-cli-cmd-init-options-language"></a>

 `--language, -l <STRING>`   
The language to be used for the new project. This option can be configured in the project’s `cdk.json` configuration file or at `~/.cdk.json` on your local development machine.  
 *Valid values*: `csharp`, `fsharp`, `go`, `java`, `javascript`, `python`, `typescript` <a name="ref-cli-cmd-init-options-list"></a>

 `--list <BOOLEAN>`   
List the available template types and languages.

## Examples
<a name="ref-cli-cmd-init-examples"></a>

### List the available template types and languages
<a name="ref-cli-cmd-init-examples-1"></a>

```
$ cdk init --list
Available templates:
* app: Template for a CDK Application
   └─ cdk init app --language=[csharp|fsharp|go|java|javascript|python|typescript]
* lib: Template for a CDK Construct Library
   └─ cdk init lib --language=typescript
* sample-app: Example CDK Application with some constructs
   └─ cdk init sample-app --language=[csharp|fsharp|go|java|javascript|python|typescript]
```

### Create a new CDK app in TypeScript from the library template
<a name="ref-cli-cmd-init-examples-2"></a>

```
$ cdk init lib --language=typescript
```

# `cdk list`
<a name="ref-cli-cmd-list"></a>

List all AWS CDK stacks and their dependencies from a CDK app.

## Usage
<a name="ref-cli-cmd-list-usage"></a>

```
$ cdk list <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-list-args"></a><a name="ref-cli-cmd-list-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to perform this command against.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-list-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-list-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk list` command.<a name="ref-cli-cmd-list-options-long"></a>

 `--long, -l <BOOLEAN>`   
Display AWS environment information for each stack.  
 *Default value*: `false` <a name="ref-cli-cmd-list-options-show-dependencies"></a>

 `--show-dependencies, -d <BOOLEAN>`   
Display stack dependency information for each stack.  
 *Default value*: `false` 

## Examples
<a name="ref-cli-cmd-list-examples"></a>

### List all stacks in the CDK app "node bin/main.js"
<a name="ref-cli-cmd-list-examples-1"></a>

```
$ cdk list --app='node bin/main.js'
Foo
Bar
Baz
```

### List all stacks, including AWS environment details for each stack
<a name="ref-cli-cmd-list-examples-"></a>

```
$ cdk list --app='node bin/main.js' --long
-
    name: Foo
    environment:
        name: 000000000000/bermuda-triangle-1
        account: '000000000000'
        region: bermuda-triangle-1
-
    name: Bar
    environment:
        name: 111111111111/bermuda-triangle-2
        account: '111111111111'
        region: bermuda-triangle-2
-
    name: Baz
    environment:
        name: 333333333333/bermuda-triangle-3
        account: '333333333333'
        region: bermuda-triangle-3
```

# `cdk metadata`
<a name="ref-cli-cmd-metadata"></a>

Display metadata associated with a CDK stack.

## Usage
<a name="ref-cli-cmd-metadata-usage"></a>

```
$ cdk metadata <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-metadata-args"></a><a name="ref-cli-cmd-metadata-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to display metadata for.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-metadata-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-metadata-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk metadata` command.

# `cdk migrate`
<a name="ref-cli-cdk-migrate"></a>

Migrate deployed AWS resources, AWS CloudFormation stacks, and CloudFormation templates into a new AWS CDK project.

This command creates a new CDK app that includes a single stack that is named with the value you provide using `--stack-name`. You can configure the migration source using `--from-scan`, `--from-stack`, or `--from-path`.

For more information on using `cdk migrate`, see [Migrate existing resources and AWS CloudFormation templates to the AWS CDK](migrate.md).

**Note**  
The `cdk migrate` command is experimental and may have breaking changes in the future.

## Usage
<a name="ref-cli-cdk-migrate-usage"></a>

```
$ cdk migrate <options>
```

## Options
<a name="ref-cli-cdk-migrate-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).

### Required options
<a name="ref-cli-cdk-migrate-options-required"></a><a name="ref-cli-cdk-migrate-options-stack-name"></a>

 `--stack-name <STRING>`   
The name of the AWS CloudFormation stack that will be created within the CDK app after migrating.  
 *Required*: Yes

### Conditional options
<a name="ref-cli-cdk-migrate-options-conditional"></a><a name="ref-cli-cdk-migrate-options-from-path"></a>

 `--from-path <PATH>`   
The path to the AWS CloudFormation template to migrate. Provide this option to specify a local template.  
 *Required*: Conditional. Required if migrating from a local AWS CloudFormation template.<a name="ref-cli-cdk-migrate-options-from-scan"></a>

 `--from-scan <STRING>`   
When migrating deployed resources from an AWS environment, use this option to specify whether a new scan should be started or if the AWS CDK CLI should use the last successful scan.  
 *Required*: Conditional. Required when migrating from deployed AWS resources.  
 *Accepted values*: `most-recent`, `new` <a name="ref-cli-cdk-migrate-options-from-stack"></a>

 `--from-stack <BOOLEAN>`   
Provide this option to migrate from a deployed AWS CloudFormation stack. Use `--stack-name` to specify the name of the deployed AWS CloudFormation stack.  
 *Required*: Conditional. Required if migrating from a deployed AWS CloudFormation stack.

### Optional options
<a name="ref-cli-cdk-migrate-options-optional"></a><a name="ref-cli-cdk-migrate-options-account"></a>

 `--account <STRING>`   
The account to retrieve the AWS CloudFormation stack template from.  
 *Required*: No  
 *Default*: The AWS CDK CLI obtains account information from default sources.<a name="ref-cli-cdk-migrate-options-compress"></a>

 `--compress <BOOLEAN>`   
Provide this option to compress the generated CDK project into a `ZIP` file.  
 *Required*: No<a name="ref-cli-cdk-migrate-options-filter"></a>

 `--filter <ARRAY>`   
Use when migrating deployed resources from an AWS account and AWS Region. This option specifies a filter to determine which deployed resources to migrate.  
This option accepts an array of key-value pairs, where **key** represents the filter type and **value** represents the value to filter.  
The following are accepted keys:  
+  `resource-identifier` – An identifier for the resource. Value can be the resource logical or physical ID. For example, `resource-identifier="ClusterName"`.
+  `resource-type-prefix` – The AWS CloudFormation resource type prefix. For example, specify `resource-type-prefix="AWS::DynamoDB::"` to filter all Amazon DynamoDB resources.
+  `tag-key` – The key of a resource tag. For example, `tag-key="myTagKey"`.
+  `tag-value` – The value of a resource tag. For example, `tag-value="myTagValue"`.
Provide multiple key-value pairs for `AND` conditional logic. The following example filters for any DynamoDB resource that is tagged with `myTagKey` as the tag key: `--filter resource-type-prefix="AWS::DynamoDB::", tag-key="myTagKey"`.  
Provide the `--filter` option multiple times in a single command for `OR` conditional logic. The following example filters for any resource that is a DynamoDB resource or is tagged with `myTagKey` as the tag key: `--filter resource-type-prefix="AWS::DynamoDB::" --filter tag-key="myTagKey"`.  
 *Required*: No<a name="ref-cli-cdk-migrate-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk migrate` command.<a name="ref-cli-cdk-migrate-options-language"></a>

 `--language <STRING>`   
The programming language to use for the CDK project created during migration.  
 *Required*: No  
 *Valid values*: `typescript`, `python`, `java`, `csharp`, `go`.  
 *Default*: `typescript` <a name="ref-cli-cdk-migrate-options-output-path"></a>

 `--output-path <PATH>`   
The output path for the migrated CDK project.  
 *Required*: No  
 *Default*: By default, the AWS CDK CLI will use your current working directory.<a name="ref-cli-cdk-migrate-options-region"></a>

 `--region <STRING>`   
The AWS Region to retrieve the AWS CloudFormation stack template from.  
 *Required*: No  
 *Default*: The AWS CDK CLI obtains AWS Region information from default sources.

## Examples
<a name="ref-cli-cdk-migrate-examples"></a>

### Simple example of migrating from a CloudFormation stack
<a name="ref-cli-cdk-migrate-examples-1"></a>

Migrate from a deployed CloudFormation stack in a specific AWS environment using `--from-stack`. Provide `--stack-name` to name your new CDK stack. The following is an example that migrates `myCloudFormationStack` to a new CDK app that is using TypeScript:

```
$ cdk migrate --language typescript --from-stack --stack-name 'myCloudFormationStack'
```

### Simple example of migrating from a local CloudFormation template
<a name="ref-cli-cdk-migrate-examples-2"></a>

Migrate from a local JSON or YAML CloudFormation template using `--from-path`. Provide `--stack-name` to name your new CDK stack. The following is an example that creates a new CDK app in TypeScript that includes a `myCloudFormationStack` stack from a local `template.json` file:

```
$ cdk migrate --stack-name "myCloudFormationStack" --language typescript --from-path "./template.json"
```

### Simple example of migrating from deployed AWS resources
<a name="ref-cli-cdk-migrate-examples-3"></a>

Migrate deployed AWS resources from a specific AWS environment that are not associated with a CloudFormation stack using `--from-scan`. The CDK CLI utilizes the IaC generator service to scan for resources and generate a template. Then, the CDK CLI references the template to create the new CDK app. The following is an example that creates a new CDK app in TypeScript with a new `myCloudFormationStack` stack containing migrated AWS resources:

```
$ cdk migrate --language typescript --from-scan --stack-name "myCloudFormationStack"
```

# `cdk notices`
<a name="ref-cli-cmd-notices"></a>

Display notices for your CDK application.

Notices can include important messages regarding security vulnerabilities, regressions, and usage of unsupported versions.

This command displays relevant notices, regardless of whether they have been acknowledged or not. Relevant notices may also appear after every command by default.

You can suppress notices in the following ways:
+ Through command options. The following is an example:

  ```
  $ cdk deploy --no-notices
  ```
+ Suppress all notices indefinitely through context in the project’s `cdk.json` file:

  ```
  {
    "notices": false,
    "context": {
      // ...
    }
  }
  ```
+ Acknowledge each notice with the `cdk acknowledge` command.

## Usage
<a name="ref-cli-cmd-notices-usage"></a>

```
$ cdk notices <options>
```

## Options
<a name="ref-cli-cmd-notices-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-notices-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk notices` command.

## Examples
<a name="ref-cli-cmd-notices-examples"></a>

### Example of a default notice that displays after running the cdk deploy command
<a name="ref-cli-cmd-notices-examples-1"></a>

```
$ cdk deploy

... # Normal output of the command

NOTICES

16603   Toggling off auto_delete_objects for Bucket empties the bucket

        Overview: If a stack is deployed with an S3 bucket with
                  auto_delete_objects=True, and then re-deployed with
                  auto_delete_objects=False, all the objects in the bucket
                  will be deleted.

        Affected versions: <1.126.0.

        More information at: https://github.com/aws/aws-cdk/issues/16603


17061   Error when building EKS cluster with monocdk import

        Overview: When using monocdk/aws-eks to build a stack containing
                  an EKS cluster, error is thrown about missing
                  lambda-layer-node-proxy-agent/layer/package.json.

        Affected versions: >=1.126.0 <=1.130.0.

        More information at: https://github.com/aws/aws-cdk/issues/17061


If you don’t want to see an notice anymore, use "cdk acknowledge ID". For example, "cdk acknowledge 16603"
```

### Simple example of running the cdk notices command
<a name="ref-cli-cmd-notices-examples-2"></a>

```
$ cdk notices

NOTICES

16603   Toggling off auto_delete_objects for Bucket empties the bucket

        Overview: if a stack is deployed with an S3 bucket with
                  auto_delete_objects=True, and then re-deployed with
                  auto_delete_objects=False, all the objects in the bucket
                  will be deleted.

        Affected versions: framework: <=2.15.0 >=2.10.0

        More information at: https://github.com/aws/aws-cdk/issues/16603


If you don’t want to see a notice anymore, use "cdk acknowledge <id>". For example, "cdk acknowledge 16603"
```

# `cdk publish-assets`
<a name="ref-cli-cmd-publish-assets"></a>

**Important**  
The `cdk publish-assets` command is in development for the AWS CDK. The current features of this command are subject to change. Therefore, you must opt in by providing the `--unstable=publish-assets` option to use this command.

Publish assets such as Docker images and file assets for the specified AWS Cloud Development Kit (AWS CDK) stack to their respective destinations, such as Amazon Elastic Container Registry (Amazon ECR) repositories and Amazon Simple Storage Service (Amazon S3) buckets, without performing a deployment.

This command is useful in CI/CD pipelines where you want to separate the asset publishing phase from the deployment phase. By publishing assets independently, you can validate that all assets are built and available before you start the deployment process.

## Usage
<a name="ref-cli-cmd-publish-assets-usage"></a>

```
$ cdk publish-assets <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-publish-assets-args"></a><a name="ref-cli-cmd-publish-assets-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to publish assets for.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-publish-assets-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-publish-assets-options-all"></a>

 `--all <BOOLEAN>`   
Publish assets for all stacks in your CDK app.  
 *Default value*: `false` <a name="ref-cli-cmd-publish-assets-options-concurrency"></a>

 `--concurrency <NUMBER>`   
Specify the maximum number of simultaneous asset publishing operations to perform.  
 *Default value*: `4` <a name="ref-cli-cmd-publish-assets-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
Only publish assets for requested stacks and don’t include dependencies.<a name="ref-cli-cmd-publish-assets-options-force"></a>

 `--force <BOOLEAN>`   
Re-publish all assets, even if they already exist at the destination.  
 *Default value*: `false` <a name="ref-cli-cmd-publish-assets-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk publish-assets` command.

## Examples
<a name="ref-cli-cmd-publish-assets-examples"></a>

### Publish assets for a specific stack
<a name="ref-cli-cmd-publish-assets-examples-1"></a>

```
$ cdk publish-assets MyStack --unstable=publish-assets
```

### Publish assets for all stacks
<a name="ref-cli-cmd-publish-assets-examples-2"></a>

```
$ cdk publish-assets --all --unstable=publish-assets
```

### Force re-publish assets that already exist
<a name="ref-cli-cmd-publish-assets-examples-3"></a>

```
$ cdk publish-assets MyStack --unstable=publish-assets --force
```

### Publish assets then deploy separately
<a name="ref-cli-cmd-publish-assets-examples-4"></a>

First, publish assets for your stack:

```
$ cdk publish-assets MyStack --unstable=publish-assets
```

Then, deploy the stack:

```
$ cdk deploy MyStack
```

# `cdk refactor`
<a name="ref-cli-cmd-refactor"></a>

**Important**  
The `cdk refactor` command is in preview release and is subject to change.  
You must provide the `--unstable=refactor` option when using this command.

Preserve deployed resources when refactoring code in your AWS Cloud Development Kit (AWS CDK) application.

When you rename constructs or move them across stacks in your CDK code, CloudFormation would typically treat these as new resources, causing replacements that could lead to service interruptions or data loss. The `cdk refactor` command intelligently detects these changes and works with CloudFormation’s refactoring API to preserve your resources while updating their logical IDs.

With `cdk refactor`, you can:
+ Rename constructs for better clarity in your code base without causing resource replacement.
+ Move resources between stacks to improve organization and separation of concerns.
+ Reorganize your construct hierarchy (like grouping AWS resources under a new L3 construct) while preserving the underlying cloud resources.
+ Safely upgrade or switch between construct libraries, including third-party dependencies, without triggering resource replacement when logical IDs change between versions.

This command analyzes your changes, shows you a list of resources that will change locations (stack and logical ID), and handles the complex process of updating CloudFormation resources while maintaining their identity and state.

When run, the command automatically computes mappings by comparing your current code with the deployed state. It verifies that your CDK application contains exactly the same set of resources as the deployed state, differing only in their locations in the construct tree. If the command detects any resource additions, deletions, or modifications, the refactoring operation will be rejected with an error message.

After mapping computation, the command shows you the proposed changes and, after user confirmation, applies the refactoring. If ambiguity is detected (where multiple valid mappings are possible), you can provide an override file with explicit mappings to resolve these cases.

For an introduction, see [Preserve deployed resources when refactoring CDK code](refactor.md).

## Usage
<a name="ref-cli-cmd-refactor-usage"></a>

```
$ cdk refactor <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-refactor-args"></a><a name="ref-cli-cmd-refactor-args-stack-id"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to refactor.  
You can specify multiple stack IDs to focus the refactoring operation on those stacks. If resources are being moved between stacks, and one of those stacks isn’t explicitly included, the refactor command will automatically include the additional stack in the operation.  
If you don’t provide any stack IDs, all stacks in the app will be considered for refactoring.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-refactor-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-refactor-options-dry-run"></a>

 `--dry-run`   
Print the mapping to the console without applying it.  
This option is useful for validating your changes before actually performing the refactoring, especially when working with complex applications. It shows you exactly what changes would be made without modifying any resources.<a name="ref-cli-cmd-refactor-options-force"></a>

 `--force`   
Proceed with refactoring without prompting the user for confirmation.  
This is useful in interactive environments when you’re confident about the changes. In non-interactive environments such as CI/CD pipelines, the CDK CLI automatically proceeds without prompting, so this option isn’t necessary.<a name="ref-cli-cmd-refactor-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk refactor` command.<a name="ref-cli-cmd-refactor-options-override-file"></a>

 `--override-file <FILE>`   
Provide overrides when the CDK CLI is unable to determine a refactoring resolution for resources. This file contains resource mappings in JSON format. The following is an example:  

```
{
    "environments": [
        {
            "account": "123456789012",
            "region": "us-east-2",
            "resources": {
                "StackA.OldName": "StackB.NewName",
                "StackC.Foo": "StackC.Bar"
            }
        }
    ]
}
```<a name="ref-cli-cmd-refactor-options-revert"></a>

 `--revert <FILE>`   
Revert a previous refactor. You must provide an override file with resource mappings.  
This doesn’t completely undo a previous refactor operation. To fully revert a refactor, you need to rollback your app to a previous state and run the refactor process again.

# `cdk rollback`
<a name="ref-cli-cmd-rollback"></a>

Use the AWS Cloud Development Kit (AWS CDK) Command Line Interface (CLI) `cdk rollback` command to rollback a failed or paused stack from an AWS CloudFormation deployment to its last stable state.

**Note**  
To use this command, you must have v23 of the bootstrap template deployed to your environment. For more information, see [Bootstrap template version history](bootstrapping-env.md#bootstrap-template-history).

When you deploy using `cdk deploy`, the CDK CLI will rollback a failed deployment by default. If you specify `--no-rollback` with `cdk deploy`, you can then use the `cdk rollback` command to manually rollback a failed deployment. This will initiate a rollback to the last stable state of your stack.

## Usage
<a name="ref-cli-cmd-rollback-usage"></a>

```
$ cdk rollback <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-rollback-args"></a><a name="ref-cli-cmd-rollback-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to rollback.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-rollback-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-rollback-options-all"></a>

 `--all <BOOLEAN>`   
Rollback all stacks in your CDK app.  
 *Default value*: `false` <a name="ref-cli-cmd-rollback-options-force"></a>

 `--force, -f <BOOLEAN>`   
When you use `cdk rollback`, some resources may fail to rollback. Provide this option to force the rollback of all resources. This is the same behavior as providing the `--orphan` option for each resource in your stack.  
 *Default value*: `false` <a name="ref-cli-cmd-rollback-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk rollback` command.<a name="ref-cli-cmd-rollback-options-orphan"></a>

 `--orphan <LogicalId>`   
When you use `cdk rollback`, some resources may fail to rollback. When this happens, you can try to force the rollback of a resource by using this option and providing the logical ID of the resource that failed to rollback.  
This option can be provided multiple times in a single command The following is an example:  

```
$ cdk rollback MyStack --orphan MyLambdaFunction --orphan MyLambdaFunction2
```
To force the rollback of all resources, use the `--force` option instead.<a name="ref-cli-cmd-rollback-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
The name of the existing CDK Toolkit stack that the environment is bootstrapped with.  
By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment. Use this option to provide a different name for your bootstrap stack.  
The CDK CLI uses this value to verify your bootstrap stack version.<a name="ref-cli-cmd-rollback-options-validate-bootstrap-version"></a>

 `--validate-bootstrap-version <BOOLEAN>`   
Specify whether to validate the bootstrap stack version. Provide `--validate-bootstrap-version=false` or `--no-validate-bootsrap-version` to turn off this behavior.  
 *Default value*: `true` 

# `cdk synthesize`
<a name="ref-cli-cmd-synth"></a>

Synthesize a CDK app to produce a cloud assembly, including an AWS CloudFormation template for each stack.

Cloud assemblies are files that include everything needed to deploy your app to your AWS environment. For example, it includes a CloudFormation template for each stack in your app, and a copy of the file assets or Docker images that you reference in your app.

If your app contains a single stack or if a single stack is provided as an argument, the CloudFormation template will also be displayed in the standard output (`stdout`) in YAML format.

If your app contains multiple stacks, `cdk synth` will synthesize the cloud assembly to `cdk.out`.

## Usage
<a name="ref-cli-cmd-synth-usage"></a>

```
cdk synthesize <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-synth-args"></a><a name="ref-cli-cmd-synth-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to synthesize.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-synth-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-synth-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
Only synthesize requested stacks, don’t include dependencies.<a name="ref-cli-cmd-synth-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk synthesize` command.<a name="ref-cli-cmd-synth-options-quiet"></a>

 `--quiet, -q <BOOLEAN>`   
Do not output the CloudFormation template to `stdout`.  
This option can be configured in the CDK project’s `cdk.json` file. The following is an example:  

```
{
   "quiet": true
}
```
 *Default value*: `false` <a name="ref-cli-cmd-synth-options-validation"></a>

 `--validation <BOOLEAN>`   
Validate the generated CloudFormation templates after synthesis by performing additional checks.  
You can also configure this option through the `validateOnSynth` attribute or `CDK_VALIDATION` environment variable.  
 *Default value*: `true` 

## Examples
<a name="ref-cli-cmd-synth-examples"></a>

### Synthesize the cloud assembly for a CDK stack with logical ID MyStackName and output the CloudFormation template to stdout
<a name="ref-cli-cmd-synth-examples-1"></a>

```
$ cdk synth MyStackName
```

### Synthesize the cloud assembly for all stacks in a CDK app and save them into cdk.out
<a name="ref-cli-cmd-synth-examples-2"></a>

```
$ cdk synth
```

### Synthesize the cloud assembly for MyStackName, but don’t include dependencies
<a name="ref-cli-cmd-synth-examples-3"></a>

```
$ cdk synth MyStackName --exclusively
```

### Synthesize the cloud assembly for MyStackName, but don’t output the CloudFormation template to stdout
<a name="ref-cli-cmd-synth-examples-4"></a>

```
$ cdk synth MyStackName --quiet
```

# `cdk watch`
<a name="ref-cli-cmd-watch"></a>

Continuously watch a local AWS CDK project for changes to perform deployments and hotswaps.

This command is similar to `cdk deploy`, except that it can perform continuous deployments and hotswaps through a single command.

This command is a shortcut for `cdk deploy --watch`.

To end a `cdk watch` session, interrupt the process by pressing `Ctrl+C`.

The files that are observed is determined by the `"watch"` setting in your `cdk.json` file. It has two sub-keys, `"include"` and `"exclude"`, that accepts a single string or an array of strings. Each entry is interpreted as a path relative to the location of the `cdk.json` file. Both `*` and `**` are accepted.

If you create a project using the `cdk init` command, the following default behavior is configured for `cdk watch` in your project’s `cdk.json` file:
+  `"include"` is set to `"**/*"`, which includes all files and directories in the root of the project.
+  `"exclude"` is optional, except for files and folders already ignored by default. This consists of files and directories starting with `.`, the CDK output directory, and the `node_modules` directory.

The minimal setting to configure `watch` is `"watch": {}`.

If either your CDK code or application code requires a build step before deployment, `cdk watch` works with the `"build"` key in the `cdk.json` file.

**Important**  
This command is meant for rapid deployment during the development phase of CDK Apps and not recommended for production deployments.

The same limitations of `cdk deploy --hotswap` applies to `cdk watch`. For more information, see ` cdk deploy --hotswap `.

## Usage
<a name="ref-cli-cmd-watch-usage"></a>

```
$ cdk watch <arguments> <options>
```

## Arguments
<a name="ref-cli-cmd-watch-args"></a><a name="ref-cli-cmd-watch-args-stack-name"></a>

 **CDK stack ID**   
The construct ID of the CDK stack from your app to watch.  
 *Type*: String  
 *Required*: No

## Options
<a name="ref-cli-cmd-watch-options"></a>

For a list of global options that work with all CDK CLI commands, see [Global options](ref-cli-cmd.md#ref-cli-cmd-options).<a name="ref-cli-cmd-watch-options-build-exclude"></a>

 `--build-exclude, -E <ARRAY>`   
Do not rebuild asset with the given ID.  
This option can be specified multiple times in a single command.  
 *Default value*: `[]` <a name="ref-cli-cmd-watch-options-change-set-name"></a>

 `--change-set-name <STRING>`   
The name of the CloudFormation change set to create.<a name="ref-cli-cmd-watch-options-concurrency"></a>

 `--concurrency <NUMBER>`   
Deploy and hotswap multiple stacks in parallel while accounting for inter-stack dependencies. Use this option to speed up deployments. You must still factor in CloudFormation and other AWS account rate limiting.  
Provide a number to specify the maximum number of simultaneous deployments (dependency permitting) to perform.  
 *Default value*: `1` <a name="ref-cli-cmd-watch-options-exclusively"></a>

 `--exclusively, -e <BOOLEAN>`   
Only deploy requested stacks and don’t include dependencies.<a name="ref-cli-cmd-watch-options-force"></a>

 `--force, -f <BOOLEAN>`   
Always deploy stacks, even if templates are identical.  
 *Default value*: `false` <a name="ref-cli-cmd-watch-options-help"></a>

 `--help, -h <BOOLEAN>`   
Show command reference information for the `cdk watch` command.<a name="ref-cli-cmd-watch-options-hotswap"></a>

 `--hotswap <BOOLEAN>`   
By default, `cdk watch` uses hotswap deployments when possible to update your resources. The CDK CLI will attempt to perform a hotswap deployment and will not fall back to a full CloudFormation deployment if unsuccessful. Any changes detected that cannot be updated through a hotswap are ignored.  
 *Default value*: `true` <a name="ref-cli-cmd-watch-options-hotswap-fallback"></a>

 `--hotswap-fallback <BOOLEAN>`   
By default, `cdk watch` attempts to perform hotswap deployments and ignores changes that require CloudFormation deployments. Provide `--hotswap-fallback` to fall back and perform a full CloudFormation deployment if the hotswap deployment is unsuccessful.<a name="ref-cli-cmd-watch-options-logs"></a>

 `--logs <BOOLEAN>`   
By default, `cdk watch` monitors all CloudWatch log groups in your application and streams the log events locally to `stdout`.  
 *Default value*: `true` <a name="ref-cli-cmd-watch-options-progress"></a>

 `--progress <STRING>`   
Configure how the CDK CLI displays deployment progress.  
+  `bar` – Display stack deployment events as a progress bar, with the events for the resource currently being deployed.
+  `events` – Provide a complete history, including all CloudFormation events.
You can also configure this option in the project’s `cdk.json` file or at `~/.cdk.json` on your local development machine:  

```
{
   "progress": "events"
}
```
 *Valid values*: `bar`, `events`   
 *Default value*: `bar` <a name="ref-cli-cmd-watch-options-rollback"></a>

 `--rollback <BOOLEAN>`   
During deployment, if a resource fails to be created or updated, the deployment will roll back to the latest stable state before the CDK CLI returns. All changes made up to that point will be undone. Resources that were created will be deleted and updates that were made will be rolled back.  
Use `--no-rollback` or `-R` to deactivate this behavior. If a resource fails to be created or updated, the CDK CLI will leave changes made up to that point in place and return. This may be helpful in development environments where you are iterating quickly.  
When `false`, deployments that cause resource replacements will always fail. You can only use this value for deployments that update or create new resources.
 *Default value*: `true` <a name="ref-cli-cmd-watch-options-toolkit-stack-name"></a>

 `--toolkit-stack-name <STRING>`   
The name of the existing CDK Toolkit stack.  
By default, `cdk bootstrap` deploys a stack named `CDKToolkit` into the specified AWS environment. Use this option to provide a different name for your bootstrap stack.  
The CDK CLI uses this value to verify your bootstrap stack version.

## Examples
<a name="ref-cli-cmd-watch-examples"></a>

### Watch a CDK stack with logical ID DevelopmentStack for changes
<a name="ref-cli-cmd-watch-examples-1"></a>

```
$ cdk watch DevelopmentStack
Detected change to 'lambda-code/index.js' (type: change). Triggering 'cdk deploy'
DevelopmentStack: deploying...

 ✅  DevelopmentStack
```

### Configure a cdk.json file for what to include and exclude from being watched for changes
<a name="ref-cli-cmd-watch-examples-2"></a>

```
{
   "app": "mvn -e -q compile exec:java",
   "watch": {
    "include": "src/main/**",
    "exclude": "target/*"
   }
}
```

### Build a CDK project using Java before deployment by configuring the cdk.json file
<a name="ref-cli-cmd-watch-examples-3"></a>

```
{
  "app": "mvn -e -q exec:java",
  "build": "mvn package",
  "watch": {
    "include": "src/main/**",
    "exclude": "target/*"
  }
}
```