AWS CDK Toolkit (cdk command) - AWS Cloud Development Kit (CDK) v2

This is the AWS CDK v2 Developer Guide. CDK v1 entered maintenance on June 1, 2022 and will now receive only critical bug fixes and security patches. New features will be developed for CDK v2 exclusively.

AWS CDK Toolkit (cdk command)

The AWS CDK Toolkit, the CLI command cdk, is the primary tool for interacting with your AWS CDK app. It executes your app, interrogates the application model you defined, and produces and deploys the AWS CloudFormation templates generated by the AWS CDK. It also provides other features useful for creating and working with AWS CDK projects. This topic contains information about common use cases of the CDK Toolkit.

The AWS CDK Toolkit is installed with the Node Package Manager. In most cases, we recommend installing it globally.

npm install -g aws-cdk # install latest version npm install -g aws-cdk@X.YY.Z # install specific version

If you regularly work with multiple versions of the AWS CDK, you may want to install a matching version of the AWS CDK Toolkit in individual CDK projects. To do this, omit -g from the npm install command. Then use npx aws-cdk to invoke it; this will run the local version if one exists, falling back to a global version if not.

Toolkit commands

All CDK Toolkit commands start with cdk, which is followed by a subcommand (list, synthesize, deploy, etc.). Some subcommands have a shorter version (ls, synth, etc.) that is equivalent. Options and arguments follow the subcommand in any order. The available commands are summarized here.



cdk list (ls)

Lists the stacks in the app

cdk synthesize (synth)

Synthesizes and prints the CloudFormation template for the specified stack(s)

cdk bootstrap

Deploys the CDK Toolkit staging stack; see Bootstrapping

cdk deploy

Deploys the specified stack(s)

cdk destroy

Destroys the specified stack(s)

cdk diff

Compares the specified stack with the deployed stack or a local CloudFormation template

cdk metadata

Displays metadata about the specified stack

cdk init

Creates a new CDK project in the current directory from a specified template

cdk context

Manages cached context values

cdk docs (doc)

Opens the CDK API reference in your browser

cdk doctor

Checks your CDK project for potential problems

For the options available for each command, see Toolkit reference or Built-in help.

Specifying options and their values

Command line options begin with two hyphens (--). Some frequently-used options have single-letter synonyms that begin with a single hyphen (for example, --app has a synonym -a). The order of options in an AWS CDK Toolkit command is not important.

All options accept a value, which must follow the option name. The value may be separated from the name by whitespace or by an equals sign =. The following two options are equivalent

--toolkit-stack-name MyBootstrapStack --toolkit-stack-name=MyBootstrapStack

Some options are flags (Booleans). You may specify true or false as their value. If you do not provide a value, the value is taken to be true. You may also prefix the option name with no- to imply false.

# sets staging flag to true --staging --staging=true --staging true # sets staging flag to false --no-staging --staging=false --staging false

A few options, namely --context, --parameters, --plugin, --tags, and --trust, may be specified more than once to specify multiple values. These are noted as having [array] type in the CDK Toolkit help. For example:

cdk bootstrap --tags costCenter=0123 --tags responsibleParty=jdoe

Built-in help

The AWS CDK Toolkit has integrated help. You can see general help about the utility and a list of the provided subcommands by issuing:

cdk --help

To see help for a particular subcommand, for example deploy, specify it before the --help flag.

cdk deploy --help

Issue cdk version to display the version of the AWS CDK Toolkit. Provide this information when requesting support.

Version reporting

To gain insight into how the AWS CDK is used, the constructs used by AWS CDK applications are collected and reported by using a resource identified as AWS::CDK::Metadata. This resource is added to AWS CloudFormation templates, and can easily be reviewed. This information can also be used by AWS to identify stacks using a construct with known security or reliability issues, and to contact their users with important information.


Prior to version 1.93.0, the AWS CDK reported the names and versions of the modules loaded during synthesis, rather than the constructs used in the stack.

By default, the AWS CDK reports the use of constructs in the following NPM modules that are used in the stack:

  • AWS CDK core module

  • AWS Construct Library modules

  • AWS Solutions Constructs module

  • AWS Render Farm Deployment Kit module

The AWS::CDK::Metadata resource looks something like the following.

  Type: "AWS::CDK::Metadata"
    Analytics: "v2:deflate64:H4sIAND9SGAAAzXKSw5AMBAA0L1b2PdzBYnEAdio3RglglY60zQi7u6TWL/XKmNUlxeQSOKwaPTBqrNhwEWU3hGHiCzK0dWWfAxoL/Fd8mvk+QkS/0X6BdjnCdgmOOQKWz+AqqLDt2Y3YMnLYWwAAAA="

The Analytics property is a gzipped, base64-encoded, prefix-encoded list of the constructs present in the stack.

To opt out of version reporting, use one of the following methods:

  • Use the cdk command with the --no-version-reporting argument to opt out for a single command.

    cdk --no-version-reporting synth

    Remember, the AWS CDK Toolkit synthesizes fresh templates before deploying, so you should also add --no-version-reporting to cdk deploy commands.

  • Set versionReporting to false in ./cdk.json or ~/.cdk.json. This opts out unless you opt in by specifying --version-reporting on an individual command.

    { "app": "...", "versionReporting": false }

Specifying credentials and region

The CDK Toolkit needs to know your AWS account credentials and the AWS region into which you are deploying, not only for deployment operations but also to retrieve context values during synthesis. Together, your account and region make up the environment.


We strongly recommend against using your main AWS account for day-to-day tasks. Instead, create a user in IAM and use its credentials with the CDK.

Credentials and region may be specified using environment variables or in configuration files. These are the same variables and files used by other AWS tools such as the AWS CLI and the various AWS SDKs. The CDK Toolkit looks for this information in the following order.

  • The AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION environment variables. Always specify all three variables, not just one or two.

  • A specific profile defined in the standard AWS config and credentials files, and specified using the --profile option on cdk commands.

  • The [default] section of the standard AWS config and credentials files.


The standard AWS config and credentials files are located at ~/.aws/config and ~/.aws/credentials (macOS/Linux) or %USERPROFILE%\.aws\config and %USERPROFILE%\.aws\credentials (Windows).

The environment specified in your AWS CDK app using the stack's env property is used during synthesis to generate an environment-specific AWS CloudFormation template and during deployment to override the account or region specified by one of the above methods. For more information, see Environments.

If you have the AWS CLI installed, the easiest way to configure your account credentials and a default region is to issue the following command:

aws configure

Provide your AWS access key ID, secret access key, and default region when prompted. These values are written to the [default] section of the config and credentials files.

If you don't have the AWS CLI installed, you can manually create or edit the config and credentials files to contain default credentials and a default region, in the following format.

  • In ~/.aws/config or %USERPROFILE%\.aws\config

    [default] region=us-west-2
  • In ~/.aws/credentials or %USERPROFILE%\.aws\credentials

    [default] aws_access_key_id=AKIAI44QH8DHBEXAMPLE aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

Besides specifying AWS credentials and a region in the [default] section, you can also add one or more [profile NAME] sections, where NAME is the name of the profile.

  • In ~/.aws/config or %USERPROFILE%\.aws\config

    [profile test] region=us-east-1 [profile prod] region=us-west-1
  • In ~/.aws/credentials or %USERPROFILE%\.aws\credentials

    [profile test] aws_access_key_id=AKIAI44QH8DHBEXAMPLE aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY [profile test] aws_access_key_id=AKIAI44QH8DHBEXAMPLE aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

Always add named profiles to both the config and credentials files. The AWS CDK Toolkit does not fall back to using the region in the [default] section when the specified named profile is not found in the config file, as some other AWS tools do.


Do not name a profile default: that is, do not use a [profile default] section in either config or credentials.


Although the AWS CDK uses credentials from the same sources files as other AWS tools and SDKs, including the AWS Command Line Interface, it may behave slightly differently from these tools. See Setting credentials for complete details on setting up credentials for the AWS SDK for JavaScript, which the AWS CDK uses under the hood.

You may optionally use the --role-arn (or -r) option to specify the ARN of an IAM role that should be used for deployment. This role must be assumable by the AWS account being used.

Specifying the app command

Many features of the CDK Toolkit require one or more AWS CloudFormation templates be synthesized, which in turn requires running your application. Since the AWS CDK supports programs written in a variety of languages, it uses a configuration option to specify the exact command necessary to run your app. This option can be specified in two ways.

First, and most commonly, it can be specified using the app key inside the file cdk.json, which is in the main directory of your AWS CDK project. The CDK Toolkit provides an appropriate command when creating a new project with cdk init. Here is the cdk.json from a fresh TypeScript project, for instance.

{ "app": "npx ts-node bin/hello-cdk.ts" }

The CDK Toolkit looks for cdk.json in the current working directory when attempting to run your app, so you might keep a shell open in your project's main directory for issuing CDK Toolkit commands.

The CDK Toolkit also looks for the app key in ~/.cdk.json (that is, in your home directory) if it can't find it in ./cdk.json. Adding the app command here can be useful if you usually work with CDK code in the same language.

If you are in some other directory, or if you want to run your app via a command other than the one in cdk.json, you can use the --app (or -a) option to specify it.

cdk --app "npx ts-node bin/hello-cdk.ts" ls

When deploying, you may also specify a directory containing synthesized cloud assemblies, such as cdk.out, as the value of --app. The specified stacks are deployed from this directory; the app is not synthesized.

Specifying stacks

Many CDK Toolkit commands (for example, cdk deploy) work on stacks defined in your app. If your app contains only one stack, the CDK Toolkit assumes you mean that one if you don't specify a stack explicitly.

Otherwise, you must specify the stack or stacks you want to work with. You can do this by specifying the desired stacks by ID individually on the command line. Recall that the ID is the value specified by the second argument when you instantiate the stack.

cdk synth PipelineStack LambdaStack

You may also use wildcards to specify IDs that match a pattern.

  • ? matches any single character

  • * matches any number of characters (* alone matches all stacks)

  • ** matches everything in a hierarchy

You may also use the --all option to specify all stacks.

If your app uses CDK Pipelines, the CDK Toolkit understands your stacks and stages as a hierarchy, and the --all option and the * wildcard only match top-level stacks. To match all the stacks, use **. Also use ** to indicate all the stacks under a particular hierarchy.

When using wildcards, enclose the pattern in quotes, or escape the wildcards with \. If you don't, your shell may try to expand the pattern to the names of files in the current directory. At best, this won't do what you expect; at worst, you could deploy stacks you didn't intend to. This isn't strictly necessary on Windows because cmd.exe does not expand wildcards, but is good practice nonetheless.

cdk synth "*Stack" # PipelineStack, LambdaStack, etc. cdk synth 'Stack?' # StackA, StackB, Stack1, etc. cdk synth \* # All stacks in the app, or all top-level stacks in a CDK Pipelines app cdk synth '**' # All stacks in a CDK Pipelines app cdk synth 'PipelineStack/Prod/**' # All stacks in Prod stage in a CDK Pipelines app

The order in which you specify the stacks is not necessarily the order in which they will be processed. The AWS CDK Toolkit takes into account dependencies between stacks when deciding the order in which to process them. For example, if one stack uses a value produced by another (such as the ARN of a resource defined in the second stack), the second stack is synthesized before the first one because of this dependency. You can add dependencies between stacks manually using the stack's addDependency() method.

Bootstrapping your AWS environment

Deploying stacks with the CDK requires special dedicated AWS CDK resources to be provisioned. The cdk bootstrap command creates the necessary resources for you. You only need to bootstrap if you are deploying a stack that requires these dedicated resources. See Bootstrapping for details.

cdk bootstrap

If issued with no arguments, as shown here, the cdk bootstrap command synthesizes the current app and bootstraps the environments its stacks will be deployed to. If the app contains environment-agnostic stacks, which do not explicitly specify an environment so they can be deployed anywhere, the default account and region are bootstrapped, or the environment specified using --profile.

Outside of an app, you must explicitly specify the environment to be bootstrapped. You may also do so to bootstrap an environment that's not specified in your app or local AWS profile. Credentials must be configured (e.g. in ~/.aws/credentials) for the specified account and region. You may specify a profile that contains the required credentials.

cdk bootstrap ACCOUNT-NUMBER/REGION # e.g. cdk bootstrap 1111111111/us-east-1 cdk bootstrap --profile test 1111111111/us-east-1

Each environment (account/region combination) to which you deploy such a stack must be bootstrapped separately.

You may incur AWS charges for what the AWS CDK stores in the bootstrapped resources. Additionally, if you use -bootstrap-customer-key, a Customer Master Key (CMK) will be created, which also incurs charges per environment.


Older versions of the bootstrap template created a Customer Master Key by default. To avoid charges, re-bootstrap using --no-bootstrap-customer-key.


CDK Toolkit v2 does not support the original bootstrap template, dubbed the legacy template, used by default with CDK v1.


The modern bootstrap template effectively grants the permissions implied by the --cloudformation-execution-policies to any AWS account in the --trust list, which by default will extend permissions to read and write to any resource in the bootstrapped account. Make sure to configure the bootstrapping stack with policies and trusted accounts you are comfortable with.

Creating a new app

To create a new app, create a directory for it, then, inside the directory, issue cdk init.

mkdir my-cdk-app cd my-cdk-app cdk init TEMPLATE --language LANGUAGE

The supported languages (LANGUAGE) are:













TEMPLATE is an optional template. If the desired template is app, the default, you may omit it. The available templates are:



app (default)

Creates an empty AWS CDK app.


Creates an AWS CDK app with a stack containing an Amazon SQS queue and an Amazon SNS topic.

The templates use the name of the project folder to generate names for files and classes inside your new app.

Listing stacks

To see a list of the IDs of the stacks in your AWS CDK application, enter one of the following equivalent commands:

cdk list cdk ls

If your application contains CDK Pipelines stacks, the CDK Toolkit displays stack names as paths according to their location in the pipeline hierarchy (e.g., PipelineStack, PipelineStack/Prod, PipelineStack/Prod/MyService, etc).

If your app contains many stacks, you can specify full or partial stack IDs of the stacks to be listed; see Specifying stacks.

Add the --long flag to see more information about the stacks, including the stack names and their environments (AWS account and region).

Synthesizing stacks

The cdk synthesize command (almost always abbreviated synth) synthesizes a stack defined in your app into a CloudFormation template.

cdk synth # if app contains only one stack cdk synth MyStack cdk synth Stack1 Stack2 cdk synth "*" # all stacks in app

The CDK Toolkit actually runs your app and synthesizes fresh templates before most operations (e.g. when deploying or comparing stacks). These templates are stored by default in the cdk.out directory. The cdk synth command simply prints the generated templates for the specified stack(s).

See cdk synth --help for all available options. A few of the most-frequently-used options are covered below.

Specifying context values

Use the --context or -c option to pass runtime context values to your CDK app.

# specify a single context value cdk synth --context key=value MyStack # specify multiple context values (any number) cdk synth --context key1=value1 --context key2=value2 MyStack

When deploying multiple stacks, the specified context values are normally passed to all of them. If you wish, you may specify different values for each stack by prefixing the stack name to the context value.

# different context values for each stack cdk synth --context Stack1:key=value Stack2:key=value Stack1 Stack2

Specifying display format

By default, the synthesized template is displayed in YAML format. Add the --json flag to display it in JSON format instead.

cdk synth --json MyStack

Specifying output directory

Add the --output (-o) option to write the synthesized templates to a directory other than cdk.out.

cdk synth --output=~/templates

Deploying stacks

The cdk deploy subcommand deploys the specified stack(s) to your AWS account.

cdk deploy # if app contains only one stack cdk deploy MyStack cdk deploy Stack1 Stack2 cdk deploy "*" # all stacks in app

The CDK Toolkit runs your app and synthesizes fresh AWS CloudFormation templates before deploying anything. Therefore, most command line options you can use with cdk synth (for example, --context) can also be used with cdk deploy.

See cdk deploy --help for all available options. A few of the most useful options are covered below.

Skipping synthesis

The cdk deploy command normally synthesizes your app's stacks before deploying to make sure the deployment reflects the latest version of your app. If you know that you haven't made any changes to your code since your last cdk synth, you may suppress the redundant synthesis step when deploying. Simply specify your project's cdk.out directory in the --app option.

cdk deploy --app cdk.out StackOne StackTwo

Disabling rollback

One of AWS CloudFormation's marquee features is its ability to roll back changes so that deployments are atomic—they either succeed or fail as a whole. The AWS CDK inherits this capability because it synthesizes and deploys AWS CloudFormation templates.

Rollback makes sure your resources are in a consistent state at all times, which is vital for production stacks. However, while you're still developing your infrastructure, some failures are inevitable, and rolling back failed deployments just slows you down.

For this reason, the CDK Toolkit; allows you to disable rollback by adding --no-rollback to your cdk deploy command. With this flag, failed deployments are not rolled back. Instead, resources deployed before the failed resource remain in place, and the next deployment starts with the failed resource. You'll spend a lot less time waiting for deployments and a lot more time developing your infrastructure.

Hot swapping

Use the --hotswap flag with cdk deploy to attempt to update your AWS resources directly instead of generating a AWS CloudFormation changeset and deploying it. Deployment falls back to AWS CloudFormation deployment if hot swapping is not possible.

Currently hot swapping supports Lambda functions, Step Functions state machines, and Amazon ECS container images. The --hotswap flag also disables rollback (i.e., implies --no-rollback).


Hot-swapping is not recommended for production deployments.

Watch mode

The CDK Toolkit's watch mode ( cdk deploy --watch, or cdk watch for short) continuously monitors your CDK app's source files and assets for changes and immediately performs a deployment of the specified stacks when a change is detected.

By default, these deployments use the --hotswap flag, which fast-tracks deployment of changes to Lambda functions, and falls back to deploying through AWS CloudFormation if you have changed infrastructure configuration. To have cdk watch always perform full AWS CloudFormation deployments, add the --no-hotswap flag to cdk watch.

Any changes made while cdk watch is already performing a deployment will be combined into a single deployment, which will begin as soon as the in-progress deployment is complete.

Watch mode uses the "watch" key in the project's cdk.json to determine which files to monitor. By default, these files are your application files and assets, but this can be changed by modifying the "include" and "exclude" entries in the "watch" key. The following cdk.json file shows an example of these entries.

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

cdk watch executes the "build" command from cdk.json to build your app before synthesis. If your deployment requires any commands to build or package your Lambda code (or anything else that's not in your CDK app proper), add it here.

Git-style wildcards, both * and **, can be used in the "watch" and "build" keys. Each path is interpreted relative to the parent directory of cdk.json. The default value of include is **/*, meaning all files and directories in the project root directory. exclude is optional.


Watch mode is not recommended for production deployments.

Specifying AWS CloudFormation parameters

The AWS CDK Toolkit supports specifying AWS CloudFormation parameters at deployment. You may provide these on the command line following the --parameters flag.

cdk deploy MyStack --parameters uploadBucketName=UploadBucket

To define multiple parameters, use multiple --parameters flags.

cdk deploy MyStack --parameters uploadBucketName=UpBucket --parameters downloadBucketName=DownBucket

If you are deploying multiple stacks, you can specify a different value of each parameter for each stack by prefixing the name of the parameter with the stack name and a colon. Otherwise, the same value is passed to all stacks.

cdk deploy MyStack YourStack --parameters MyStack:uploadBucketName=UploadBucket --parameters YourStack:uploadBucketName=UpBucket

By default, the AWS CDK retains values of parameters from previous deployments and uses them in later deployments if they are not specified explicitly. Use the --no-previous-parameters flag to require all parameters to be specified.

Specifying outputs file

If your stack declares AWS CloudFormation outputs, these are normally displayed on the screen at the conclusion of deployment. To write them to a file in JSON format, use the --outputs-file flag.

cdk deploy --outputs-file outputs.json MyStack

Security-related changes

To protect you against unintended changes that affect your security posture, the AWS CDK Toolkit prompts you to approve security-related changes before deploying them. You can specify the level of change that requires approval:

cdk deploy --require-approval LEVEL

LEVEL can be one of the following:




Approval is never required


Requires approval on any IAM or security-group-related change

broadening (default)

Requires approval when IAM statements or traffic rules are added; removals don't require approval

The setting can also be configured in the cdk.json file.

{ "app": "...", "requireApproval": "never" }

Comparing stacks

The cdk diff command compares the current version of a stack defined in your app with the already-deployed version, or with a saved AWS CloudFormation template, and displays a list of changes .

Stack HelloCdkStack
IAM Statement Changes
│   │ Resource                     │ Effect │ Action                       │ Principal                    │ Condition │
│ + │ ${Custom::S3AutoDeleteObject │ Allow  │ sts:AssumeRole               │ │           │
│   │ sCustomResourceProvider/Role │        │                              │                              │           │
│   │ .Arn}                        │        │                              │                              │           │
│ + │ ${MyFirstBucket.Arn}         │ Allow  │ s3:DeleteObject*             │ AWS:${Custom::S3AutoDeleteOb │           │
│   │ ${MyFirstBucket.Arn}/*       │        │ s3:GetBucket*                │ jectsCustomResourceProvider/ │           │
│   │                              │        │ s3:GetObject*                │ Role.Arn}                    │           │
│   │                              │        │ s3:List*                     │                              │           │
IAM Policy Changes
│   │ Resource                                               │ Managed Policy ARN                                     │
│ + │ ${Custom::S3AutoDeleteObjectsCustomResourceProvider/Ro │ {"Fn::Sub":"arn:${AWS::Partition}:iam::aws:policy/serv │
│   │ le}                                                    │ ice-role/AWSLambdaBasicExecutionRole"}                 │
(NOTE: There may be security-related changes not in this list. See

[+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/S3Bucket AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392S3BucketBF7A7F3F: {"Type":"String","Description":"S3 bucket for asset \"4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\""}
[+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/S3VersionKey AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392S3VersionKeyFAF93626: {"Type":"String","Description":"S3 key for asset version \"4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\""}
[+] Parameter AssetParameters/4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392/ArtifactHash AssetParameters4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392ArtifactHashE56CD69A: {"Type":"String","Description":"Artifact hash for asset \"4cd61014b71160e8c66fe167e43710d5ba068b80b134e9bd84508cf9238b2392\""}

[+] AWS::S3::BucketPolicy MyFirstBucket/Policy MyFirstBucketPolicy3243DEFD
[+] Custom::S3AutoDeleteObjects MyFirstBucket/AutoDeleteObjectsCustomResource MyFirstBucketAutoDeleteObjectsCustomResourceC52FCF6E
[+] AWS::IAM::Role Custom::S3AutoDeleteObjectsCustomResourceProvider/Role CustomS3AutoDeleteObjectsCustomResourceProviderRole3B1BD092
[+] AWS::Lambda::Function Custom::S3AutoDeleteObjectsCustomResourceProvider/Handler CustomS3AutoDeleteObjectsCustomResourceProviderHandler9D90184F
[~] AWS::S3::Bucket MyFirstBucket MyFirstBucketB8884501
 ├─ [~] DeletionPolicy
 │   ├─ [-] Retain
 │   └─ [+] Delete
 └─ [~] UpdateReplacePolicy
     ├─ [-] Retain
     └─ [+] Delete

To compare your app's stack(s) with the existing deployment:

cdk diff MyStack

To compare your app's stack(s) with a saved CloudFormation template:

cdk diff --template ~/stacks/MyStack.old MyStack

Configuration (cdk.json)

Default values for many CDK Toolkit command-line flags may be stored in a project's cdk.json file or in the .cdk.json file in your user directory. Below is an alphabetical reference to the supported configuration settings.

Key Notes CDK Toolkit option
app The command that executes the CDK application. --app
assetMetadata If false, CDK does not add metadata to resources that use assets. --no-asset-metadata
bootstrapKmsKeyId Overrides the ID of the AWS KMS key used to encrypt the Amazon S3 deployment bucket. --bootstrap-kms-key-id
build The command that compiles or builds the CDK application before synthesis. Not permitted in ~/.cdk.json. --build
browser The command for launching a Web browser for the cdk docs subcommand. --browser
context See Runtime context. Context values in a configuration file will not be erased by cdk context --clear. (The CDK Toolkit places cached context values in cdk.context.json.) --context
debug If true, CDK Toolkit emits more detailed information useful for debugging. --debug
language The language to be used for initializing new projects. --language
lookups If false, no context lookups are permitted. Synthesis will fail if any context lookups need to be performed. --no-lookups
notices If false, suppresses the display of messages about security vulnerabilities, regressions, and unsupported versions. --no-notices
output The name of the directory into which the synthesized cloud assembly will be emitted (default "cdk.out"). --outputs-file
outputsFile The file to which AWS CloudFormation outputs from deployed stacks will be written (in JSON format). --outputs-file
pathMetadata If false, CDK path metadata is not added to synthesized templates. --no-path-metadata
plugin JSON array specifying the package names or local paths of packages that extend the CDK --plugin
profile Name of the default AWS profile used for specifying region and account credentials. --profile
progress If set to "events", the CDK Toolkit displays all AWS CloudFormation events during deployment, rather than a progress bar. --progress
requireApproval Default approval level for security changes. See Security-related changes --require-approval
rollback If false, failed deployments are not rolled back. --no-rollback
staging If false, assets are not copied to the output directory (use for local debugging of the source files with AWS SAM). --no-staging
tags JSON object containing tags (key-value pairs) for the stack. --tags
toolkitBucketName The name of the Amazon S3 bucket used for deploying assets such as Lambda functions and container images (see Bootstrapping your AWS environment. --toolkit-bucket-name
toolkitStackName The name of the bootstrap stack (see Bootstrapping your AWS environment. --toolkit-stack-name
versionReporting If false, opts out of version reporting. --no-version-reporting
watch JSON object containing "include" and "exclude" keys that indicate which files should (or should not) trigger a rebuild of the project when changed. See Watch mode. --watch

Toolkit reference

This section provides a reference for the AWS CDK Toolkit derived from its help, first a general reference with the options available with all commands, then (in collapsible sections) specific references with options available only with specific subcommands.

Usage: cdk -a <cdk-app> COMMAND


  cdk list [STACKS..]             Lists all stacks in the app      [aliases: ls]

  cdk synthesize [STACKS..]       Synthesizes and prints the CloudFormation
                                  template for this stack       [aliases: synth]

  cdk bootstrap [ENVIRONMENTS..]  Deploys the CDK toolkit stack into an AWS

  cdk deploy [STACKS..]           Deploys the stack(s) named STACKS into your
                                  AWS account

  cdk import [STACK]              Import existing resource(s) into the given

  cdk watch [STACKS..]            Shortcut for 'deploy --watch'

  cdk destroy [STACKS..]          Destroy the stack(s) named STACKS

  cdk diff [STACKS..]             Compares the specified stack with the deployed
                                  stack or a local template file, and returns
                                  with status 1 if any difference is found

  cdk metadata [STACK]            Returns all metadata associated with this

  cdk acknowledge [ID]            Acknowledge a notice so that it does not show
                                  up anymore                      [aliases: ack]

  cdk notices                     Returns a list of relevant notices

  cdk init [TEMPLATE]             Create a new, empty CDK project from a

  cdk context                     Manage cached context values

  cdk docs                        Opens the reference documentation in a browser
                                                                  [aliases: doc]

  cdk doctor                      Check your set-up for potential problems


  -a, --app                REQUIRED: command-line for executing your app or a
                           cloud assembly directory (e.g. "node bin/my-app.js")

      --build              Command-line for a pre-synth build           [string]

  -c, --context            Add contextual string parameter (KEY=VALUE)   [array]

  -p, --plugin             Name or path of a node package that extend the CDK
                           features. Can be specified multiple times     [array]

      --trace              Print trace for stack warnings              [boolean]

      --strict             Do not construct stacks with warnings       [boolean]

      --lookups            Perform context lookups (synthesis fails if this is
                           disabled and context lookups need to be performed)
                                                       [boolean] [default: true]

      --ignore-errors      Ignores synthesis errors, which will likely produce
                           an invalid output          [boolean] [default: false]

  -j, --json               Use JSON output instead of YAML when templates are
                           printed to STDOUT          [boolean] [default: false]

  -v, --verbose            Show debug logs (specify multiple times to increase
                           verbosity)                   [count] [default: false]

      --debug              Enable emission of additional debugging information,
                           such as creation stack traces of tokens
                                                      [boolean] [default: false]

      --profile            Use the indicated AWS profile as the default
                           environment                                  [string]

      --proxy              Use the indicated proxy. Will read from HTTPS_PROXY
                           environment variable if not specified        [string]

      --ca-bundle-path     Path to CA certificate to use when validating HTTPS
                           requests. Will read from AWS_CA_BUNDLE environment
                           variable if not specified                    [string]

  -i, --ec2creds           Force trying to fetch EC2 instance credentials.
                           Default: guess EC2 instance status          [boolean]

      --version-reporting  Include the "AWS::CDK::Metadata" resource in
                           synthesized templates (enabled by default)  [boolean]

      --path-metadata      Include "aws:cdk:path" CloudFormation metadata for
                           each resource (enabled by default)
                                                       [boolean] [default: true]

      --asset-metadata     Include "aws:asset:*" CloudFormation metadata for
                           resources that uses assets (enabled by default)
                                                       [boolean] [default: true]

  -r, --role-arn           ARN of Role to use when invoking CloudFormation

      --staging            Copy assets to the output directory (use --no-staging
                           to disable, needed for local debugging the source
                           files with SAM CLI)         [boolean] [default: true]

  -o, --output             Emits the synthesized cloud assembly into a directory
                           (default: cdk.out)                           [string]

      --notices            Show relevant notices                       [boolean]

      --no-color           Removes colors and other style from console output
                                                      [boolean] [default: false]

      --version            Show version number                         [boolean]

  -h, --help               Show help                                   [boolean]

If your app has a single stack, there is no need to specify the stack name

If one of cdk.json or ~/.cdk.json exists, options specified there will be used
as defaults. Settings in cdk.json take precedence.
cdk list [STACKS..]

Lists all stacks in the app


  -l, --long               Display environment information for each stack
                                                      [boolean] [default: false]
cdk synthesize [STACKS..]

Synthesizes and prints the CloudFormation template for this stack


  -e, --exclusively        Only synthesize requested stacks, don't include
                           dependencies                                [boolean]

      --validation         After synthesis, validate stacks with the
                           "validateOnSynth" attribute set (can also be
                           controlled with CDK_VALIDATION)
                                                       [boolean] [default: true]

  -q, --quiet              Do not output CloudFormation Template to stdout
                                                      [boolean] [default: false]
cdk bootstrap [ENVIRONMENTS..]

Deploys the CDK toolkit stack into an AWS environment


  -b, --bootstrap-bucket-name,              The name of the CDK toolkit bucket;
  --toolkit-bucket-name                     bucket will be created and must not
                                            exist                       [string]

      --bootstrap-kms-key-id                AWS KMS master key ID used for the
                                            SSE-KMS encryption          [string]

      --bootstrap-customer-key              Create a Customer Master Key (CMK)
                                            for the bootstrap bucket (you will
                                            be charged but can customize
                                            permissions, modern bootstrapping
                                            only)                      [boolean]

      --qualifier                           String which must be unique for each
                                            bootstrap stack. You must configure
                                            it on your CDK app if you change
                                            this from the default.      [string]

      --public-access-block-configuration   Block public access configuration
                                            on CDK toolkit bucket (enabled by
                                            default)                   [boolean]

  -t, --tags                                Tags to add for the stack
                                            (KEY=VALUE)    [array] [default: []]

      --execute                             Whether to execute ChangeSet
                                            (--no-execute will NOT execute the
                                            ChangeSet) [boolean] [default: true]

      --trust                               The AWS account IDs that should be
                                            trusted to perform deployments into
                                            this environment (may be repeated,
                                            modern bootstrapping only)
                                                           [array] [default: []]

      --trust-for-lookup                    The AWS account IDs that should be
                                            trusted to look up values in this
                                            environment (may be repeated, modern
                                            bootstrapping only)
                                                           [array] [default: []]

      --cloudformation-execution-policies   The Managed Policy ARNs that should
                                            be attached to the role performing
                                            deployments into this environment
                                            (may be repeated, modern
                                            bootstrapping only)
                                                           [array] [default: []]

  -f, --force                               Always bootstrap even if it would
                                            downgrade template version
                                                      [boolean] [default: false]

      --termination-protection              Toggle CloudFormation termination
                                            protection on the bootstrap stacks

      --show-template                       Instead of actual bootstrapping,
                                            print the current CLI's
                                            bootstrapping template to stdout for
                                                      [boolean] [default: false]

      --toolkit-stack-name                  The name of the CDK toolkit stack to
                                            create                      [string]

      --template                            Use the template from the given file
                                            instead of the built-in one (use
                                            --show-template to obtain an
                                            example)                    [string]
cdk deploy [STACKS..]

Deploys the stack(s) named STACKS into your AWS account


      --all                  Deploy all available stacks
                                                      [boolean] [default: false]

  -E, --build-exclude        Do not rebuild asset with the given ID. Can be
                             specified multiple times      [array] [default: []]

  -e, --exclusively          Only deploy requested stacks, don't include
                             dependencies                              [boolean]

      --require-approval     What security-sensitive changes need manual
                         [string] [choices: "never", "any-change", "broadening"]

      --ci                   Force CI detection       [boolean] [default: false]

      --notification-arns    ARNs of SNS topics that CloudFormation will notify
                             with stack related events                   [array]

  -t, --tags                 Tags to add to the stack (KEY=VALUE), overrides
                             tags from Cloud Assembly (deprecated)       [array]

      --execute              Whether to execute ChangeSet (--no-execute will NOT
                             execute the ChangeSet)    [boolean] [default: true]

      --change-set-name      Name of the CloudFormation change set to create

  -f, --force                Always deploy stack even if templates are identical
                                                      [boolean] [default: false]

      --parameters           Additional parameters passed to CloudFormation at
                             deploy time (STACK:KEY=VALUE) [array] [default: {}]

  -O, --outputs-file         Path to file where stack outputs will be written as
                             JSON                                       [string]

      --previous-parameters  Use previous values for existing parameters (you
                             must specify all parameters on every deployment if
                             this is disabled)         [boolean] [default: true]

      --toolkit-stack-name   The name of the existing CDK toolkit stack (only
                             used for app using legacy synthesis)       [string]

      --progress             Display mode for stack activity events
                                             [string] [choices: "bar", "events"]

      --rollback             Rollback stack to stable state on failure. Defaults
                             to 'true', iterate more rapidly with --no-rollback
                             or -R. Note: do **not** disable this flag for
                             deployments with resource replacements, as that
                             will always fail                          [boolean]

      --hotswap              Attempts to perform a 'hotswap' deployment, which
                             skips CloudFormation and updates the resources
                             directly, and falls back to a full deployment if
                             that is not possible. Do not use this in production
                             environments                              [boolean]

      --watch                Continuously observe the project files, and deploy
                             the given stack(s) automatically when changes are
                             detected. Implies --hotswap by default    [boolean]

      --logs                 Show CloudWatch log events from all resources in
                             the selected Stacks in the terminal. 'true' by
                             default, use --no-logs to turn off. Only in effect
                             if specified alongside the '--watch' option
                                                       [boolean] [default: true]
cdk destroy [STACKS..]

Destroy the stack(s) named STACKS


      --all                Destroy all available stacks
                                                      [boolean] [default: false]

  -e, --exclusively        Only destroy requested stacks, don't include
                           dependees                                   [boolean]

  -f, --force              Do not ask for confirmation before destroying the
                           stacks                                      [boolean]
cdk diff [STACKS..]

Compares the specified stack with the deployed stack or a local template file,
and returns with status 1 if any difference is found


  -e, --exclusively        Only diff requested stacks, don't include
                           dependencies                                [boolean]

      --context-lines      Number of context lines to include in arbitrary JSON
                           diff rendering                  [number] [default: 3]

      --template           The path to the CloudFormation template to compare
                           with                                         [string]

      --security-only      Only diff for broadened security changes
                                                      [boolean] [default: false]

      --fail               Fail with exit code 1 in case of diff
                                                      [boolean] [default: false]
cdk init [TEMPLATE]

Create a new, empty CDK project from a template.


  -l, --language           The language to be used for the new project (default
                           can be configured in ~/.cdk.json)
    [string] [choices: "csharp", "fsharp", "go", "java", "javascript", "python",

      --list               List the available templates                [boolean]

      --generate-only      If true, only generates project files, without
                           executing additional operations such as setting up a
                           git repo, installing dependencies or compiling the
                           project                    [boolean] [default: false]
cdk context

Manage cached context values


  -e, --reset              The context key (or its index) to reset      [string]

      --clear              Clear all context                           [boolean]