Using the CDK CLI
Relevant source files
The following files were used as context for generating this wiki page:The AWS CDK Command Line Interface (CLI) is an open-source tool and the primary mechanism for interacting with AWS CDK applications. It allows developers to perform essential operations such as initializing a new project, synthesizing cloud infrastructure into AWS CloudFormation templates, deploying applications to an AWS account, and comparing local changes against a deployed stack. The CLI is designed to streamline the development lifecycle from project creation to deployment and management.
Sources: README.md:19-27
The CLI is built with Node.js and can be installed via npm. It supports projects written in TypeScript, JavaScript, Python, Java, C#, and Go. The toolkit's commands are defined in package.json and provide a comprehensive suite for managing CDK applications.
Sources: README.md:43-46, packages/aws-cdk/package.json:8-25
Getting Started
Installation
The CDK CLI is installed globally using npm. It requires Node.js version 10.13.0 or later.
Sources: README.md:43-44
npm i -g aws-cdk
Sources: README.md:47-49
Project Initialization (cdk init)
The cdk init command initializes a new CDK project in an empty directory. It uses a template-based system to scaffold a project structure for a specified language.
Sources: packages/aws-cdk/lib/init.ts:22-25, 303-305
Templates and Languages
The CLI provides different templates, such as app or sample-app, which can be instantiated for various programming languages. If no template or language is specified, the CLI lists the available options.
Sources: packages/aws-cdk/lib/init.ts:23-28, 321-330
The InitTemplate class manages the logic for each template, including its name, description, supported languages, and installation process.
Sources: packages/aws-cdk/lib/init.ts:60-78
InitTemplate Property | Description |
|---|---|
name | The unique name of the template (e.g., 'app'). |
description | A short description of the template's purpose. |
languages | An array of supported programming languages (e.g., 'typescript', 'python'). |
aliases | A set of alternative names for the template. |
| Sources: packages/aws-cdk/lib/init.ts:69-78 |
Initialization Flow
The initialization process involves several steps, from selecting a template to setting up the local development environment.
This diagram shows the high-level workflow of the cdk init command.
Key steps in the flow include:
- Directory Check: Ensures the target directory is empty.
Sources: packages/aws-cdk/lib/init.ts:303-305 - Template Installation: Copies files from the selected template and language, processing any
.templatefiles by replacing placeholders like%name%and%cdk-version%.
Sources: packages/aws-cdk/lib/init.ts:100-123 - Future Flag Application: Updates the
cdk.jsonfile to include context flags for enabling upcoming features, ensuring new projects are configured with the latest recommended behaviors.
Sources: packages/aws-cdk/lib/init.ts:166-186 - Git Initialization: If not already in a Git repository, it initializes a new one and creates an initial commit.
Sources: packages/aws-cdk/lib/init.ts:308-309, 317-325 - Post-Install Hooks: For languages like TypeScript and Java, it runs package installation commands (
npm install,mvn package) to download dependencies.
Sources: packages/aws-cdk/lib/init.ts:327-367
Core Commands
The CDK CLI provides a set of commands to manage the application lifecycle. The available commands are often listed in the README.md file of a newly initialized project.
| Command | Description |
|---|---|
cdk init | Initializes a new CDK project from a template. |
cdk synth | Synthesizes and prints the CloudFormation template for specified stacks. |
cdk deploy | Deploys the specified stacks to your AWS account. |
cdk diff | Compares the current stack with the deployed version and shows a diff. |
cdk ls | Lists the stacks in the app. |
cdk docs | Opens the CDK API reference and developer guide. |
npm run test | A project-specific script to run unit tests (common in JS/TS projects). |
| Sources: README.md:56-59, packages/aws-cdk/lib/init-templates/v2/app/javascript/README.md:7-11, packages/aws-cdk/lib/init-templates/v2/app/java/README.md:11-17 |
This sequence diagram illustrates a typical developer workflow using the CLI.
Sources: README.md:46-62
Application Synthesis (cdk synth)
The cdk synth command is responsible for executing the CDK app and producing a "cloud assembly" in the cdk.out directory. This assembly contains the AWS CloudFormation templates for each stack in the app, along with other artifacts like assets and the construct tree.
Sources: README.md:23-25, 58, design/construct-tree.md:106-108
The Construct Tree (tree.json)
A key artifact generated during synthesis is tree.json. This file represents the hierarchical structure of the constructs in the CDK application, known as the construct tree. It is intended to provide insight into the application's composition, which aids in debugging and building developer tooling.
Sources: design/construct-tree.md:7-8, 106-108
The tree provides a complete view of the application's structure, from the root App down to individual L1 CloudFormation resources, without needing to connect to AWS.
Sources: design/construct-tree.md:88-90
The structure of tree.json is defined as follows:
| Property | Type | Description |
|---|---|---|
version | string | The version of the tree artifact schema (e.g., "tree-0.1"). |
tree | object | The root node of the construct tree. |
tree.id | string | The ID of the construct (e.g., "App"). |
tree.path | string | The full path of the construct within the tree. |
tree.children | object | An object containing the direct children of this construct. |
tree.attributes | object | A key-value map of metadata about the construct, such as its CloudFormation type and properties. |
| Sources: design/construct-tree.md:111-121, 127-130 |
This diagram illustrates the nested structure of the tree.json file.
Sources: design/construct-tree.md:135-167
Below is an example snippet from a tree.json file, showing a stack with a single SNS topic.
{
"version": "tree-0.1",
"tree": {
"id": "App",
"path": "",
"children": {
"mystack": {
"path": "mystack",
"children": {
"mytopic": {
"path": "mystack/mytopic",
"attributes": {
"aws:cdk:cloudformation:type": "AWS::SNS::Topic",
"aws:cdk:cloudformation:properties": {
"DisplayName": "MyTopic"
}
}
}
}
}
}
}
}
Sources: design/construct-tree.md:135-167
Summary
The CDK CLI is the essential command-line tool for managing the entire lifecycle of an AWS CDK application. It provides a standardized and powerful interface for initializing projects from templates, synthesizing infrastructure as code into deployable artifacts, and managing deployments on AWS. By exposing detailed structural information through artifacts like tree.json, the CLI also enables a richer developer experience with enhanced tooling and debugging capabilities.
Sources: README.md:19-27, design/construct-tree.md:73-76