{"id":17163,"library":"aws-cdk","title":"AWS CDK Toolkit CLI","description":"The `aws-cdk` package provides the command-line interface (CLI) for the AWS Cloud Development Kit (CDK), a framework enabling developers to define cloud infrastructure using familiar programming languages (TypeScript, JavaScript, Python, Java, C#, Go) and provision it through AWS CloudFormation. As of version 2.1118.4, the CLI operates on CDK applications to synthesize CloudFormation templates, deploy, diff, and manage AWS resources. It maintains a rapid release cadence, often seeing multiple updates daily, with continuous bug fixes and feature enhancements across various underlying CDK modules. A key differentiator is its ability to abstract CloudFormation complexities, offering higher-level constructs and supporting advanced development workflows like `cdk watch` for rapid iteration and `cdk migrate` for importing existing resources. The CLI and the Construct Library (packaged as `aws-cdk-lib`) have independent release cadences since February 2025, though they remain compatible, with the CLI generally supporting Construct Library versions released before or with it.","status":"active","version":"2.1118.4","language":"javascript","source_language":"en","source_url":"https://github.com/aws/aws-cdk-cli","tags":["javascript","aws","cdk","typescript"],"install":[{"cmd":"npm install aws-cdk","lang":"bash","label":"npm"},{"cmd":"yarn add aws-cdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add aws-cdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `aws-cdk` package is the CLI. For programmatic use in a CDK application, core constructs like `App` are imported from `aws-cdk-lib` (CDK v2).","wrong":"import { App } from 'aws-cdk';","symbol":"App","correct":"import { App } from 'aws-cdk-lib';"},{"note":"In CDK v2, the `Stack` construct, along with most stable AWS Construct Library modules, is consolidated into the single `aws-cdk-lib` package.","wrong":"import { Stack } from '@aws-cdk/core';","symbol":"Stack","correct":"import { Stack } from 'aws-cdk-lib';"},{"note":"AWS service-specific constructs like `Bucket` (for S3) are imported from sub-paths of `aws-cdk-lib` in CDK v2. In v1, they were separate `@aws-cdk/aws-s3` packages.","wrong":"import { Bucket } from '@aws-cdk/aws-s3';","symbol":"Bucket","correct":"import * as s3 from 'aws-cdk-lib/aws-s3';\n// OR\nimport { Bucket } from 'aws-cdk-lib/aws-s3';"}],"quickstart":{"code":"import { App, Stack } from 'aws-cdk-lib';\nimport * as s3 from 'aws-cdk-lib/aws-s3';\nimport * as lambda from 'aws-cdk-lib/aws-lambda';\nimport { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';\n\nconst app = new App();\n\nconst myStack = new Stack(app, 'MySimpleCdkStack', {\n  env: {\n    account: process.env.CDK_DEFAULT_ACCOUNT,\n    region: process.env.CDK_DEFAULT_REGION,\n  },\n});\n\nnew s3.Bucket(myStack, 'MyBucket', {\n  versioned: true,\n  // Ensure bucket name is unique\n  bucketName: `my-unique-cdk-bucket-${myStack.account?.toLowerCase()}-${myStack.region?.toLowerCase()}`\n});\n\nnew NodejsFunction(myStack, 'MyLambdaFunction', {\n  runtime: lambda.Runtime.NODEJS_18_X,\n  entry: 'src/handler.ts',\n  handler: 'handler',\n  environment: {\n    MESSAGE: 'Hello from CDK Lambda!',\n  },\n});\n\n// Dummy handler file for NodejsFunction (src/handler.ts)\n// export async function handler(event: any) {\n//   console.log('Received event:', JSON.stringify(event, null, 2));\n//   return { statusCode: 200, body: process.env.MESSAGE || 'No message' };\n// }\n","lang":"typescript","description":"This TypeScript code defines a basic AWS CDK application with an S3 bucket and a Node.js Lambda function. The `aws-cdk` CLI would then be used to synthesize (`cdk synth`) and deploy (`cdk deploy`) this infrastructure to an AWS account after `cdk init` and `cdk bootstrap`."},"warnings":[{"fix":"Migrate to AWS CDK v2. This involves updating package dependencies to `aws-cdk-lib`, changing import statements, and re-bootstrapping AWS accounts. Tools like `awscdk-v1-stack-finder` can assist.","message":"AWS CDK v1 reached end-of-support on June 1, 2023. Continuing to use v1 exposes projects to security vulnerabilities and unaddressed bugs, and may result in incompatibility with new AWS services and features.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Upgrade your Node.js runtime to an actively supported LTS version (e.g., v18, v20, or v22) in your development environment and CI/CD pipelines.","message":"The AWS CDK CLI requires Node.js v18 or newer. Support for Node.js 14.x and 16.x officially ended on May 30, 2025. Using unsupported Node.js versions may lead to build failures, unexpected behavior, and lack of support.","severity":"breaking","affected_versions":">=2.0.0 (specifically for Node.js <18.0.0)"},{"fix":"Run `cdk bootstrap aws://ACCOUNT-ID/REGION` for each AWS account and region where you plan to deploy CDK applications. For existing V1 bootstrapped accounts, re-bootstrap them for V2.","message":"The AWS account and region must be 'bootstrapped' with a CDK Toolkit stack before the first deployment using `cdk deploy` in that environment. This stack manages assets and deployment permissions.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Regularly update your `aws-cdk` CLI (`npm update -g aws-cdk` or `npm install -g aws-cdk@latest`) at least as often as you update your `aws-cdk-lib` dependencies to maintain compatibility.","message":"The `aws-cdk` CLI and `aws-cdk-lib` (Construct Library) now have independent release cadences, meaning their version numbers may diverge. While the CLI generally supports older library versions, always ensure your CLI is up-to-date.","severity":"gotcha","affected_versions":">=2.1000.0 (for CLI), >=2.175.0 (for Construct Library)"},{"fix":"Review and apply the least-privilege IAM policies to your deployment role. Refer to the AWS CDK documentation for required permissions, especially for asset publishing and SSM parameter access if using the modern bootstrap stack.","message":"CDK deployments require specific IAM permissions for the deploying identity to interact with CloudFormation and provision resources. Default permissions, especially after bootstrapping, might not be sufficient for all resource types.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 18 or higher. Use `nvm install 18 && nvm use 18` or your preferred Node.js version manager.","cause":"The installed Node.js version is below the minimum requirement for AWS CDK v2.","error":"Error: This CDK application is not supported in the current Node.js version."},{"fix":"Navigate to the root directory of your CDK project (where `cdk.json` is located) or verify that `cdk.json` correctly points to your application entry point.","cause":"The `cdk` command was executed outside a CDK project root, or the `cdk.json` file is missing/misconfigured.","error":"No stacks found in the app. Make sure you are in a CDK app directory."},{"fix":"Configure your AWS CLI with valid credentials (`aws configure`) and ensure the `AWS_REGION` environment variable or `--region` flag is specified.","cause":"AWS authentication credentials are not configured in your environment or the default region is not set.","error":"The 'default' credential provider chain failed to retrieve credentials. Regions or sources not set."},{"fix":"Grant the required IAM permissions to the deploying entity. Start with policies like `AdministratorAccess` for testing, then refine to least privilege as you understand the resource requirements.","cause":"The IAM user or role performing the `cdk deploy` command lacks the necessary permissions to create, update, or delete the specified AWS resources.","error":"CloudFormation deployments failed: User: arn:aws:iam::ACCOUNT-ID:user/username is not authorized to perform:..."},{"fix":"Run `cdk bootstrap aws://ACCOUNT-ID/REGION` once per account and region to set up the necessary resources for CDK deployments.","cause":"The required CDK Toolkit CloudFormation stack has not been deployed to the target AWS account and region.","error":"Stack 'CDKToolkit' is not bootstrapped in account 'ACCOUNT-ID' and region 'REGION'."}],"ecosystem":"npm","meta_description":null}