Build Custom CLI's, Deployment Automation, and more with the AWS CDK Toolkit Library

Alpha Disclaimer: The AWS CDK Toolkit Library is currently in alpha. Its API is subject to change, and it may not yet support all features or have the same level of stability as the cdk CLI.

Building and managing infrastructure with the AWS Cloud Development Kit (CDK) has changed how developers and platform teams define cloud resources using familiar programming languages. Until now, the primary way to interact with the AWS CDK was through the CDK CLI, which presented challenges when building automation around the CDK as users couldn’t directly interact with the CDK toolkit natively in their code. We’re excited to announce the AWS CDK Toolkit Library (Alpha), a new feature that enables users to incorporate the same functionality of the CDK CLI directly into their applications, custom CLIs, and automation workflows.

Why This Feature?

Many teams want tighter integration between their infrastructure tooling and the rest of their platform. By using the AWS CDK Toolkit Library users have more control in how they build:

Custom Testing & Validation: Write programmatic tests that synthesize and deploy a CDK application, invoke resources (e.g., Lambda functions) for validation, and destroy them afterward, ensuring infrastructure and application logic are correct.
Deployment Automation: Move beyond shelling out to cdk deploy from scripts. Incorporate it seamlessly into existing codebase and frameworks.
Guardrails & Compliance: Centralize governance logic and automatically enforce naming conventions, security baselines, or resource tagging, at the code level.
Ephemeral Environments: Programmatically define and manage short-lived testing or preview deployments within a CDK application, whether triggered by pull requests or created for ad-hoc validation, enabling faster feedback loops and cost aware experimentation.

In short, you can completely bypass the typical command-line interactions while still retaining the underlying power of the AWS CDK.

What Is the AWS CDK Toolkit Library?

The AWS CDK Toolkit Library is a Node.js library that provides programmatic access to the same core functionalities found in the cdk CLI. It exposes classes and methods to synthesize, deploy, and destroy stacks, among other capabilities. This opens the door for:

Enterprise CLI Wrappers: Build custom CLIs that simplify or guide how developers provision infrastructure, ensuring consistent default, compliance, or patterns.
Integration Testing: Programmatically spin up ephemeral environments for tests, run validations against created resources, and tear them down without manually invoking CLI commands.
Context-Aware Deployments: Tools can embed CDK’s deployment capabilities directly, customizing how context is provided and consumed.
Typed Input/Output: All actions and outputs are strongly typed, making it easier to detect configuration or compilation issues early.
Separation of Actions & Interactions: The user’s code controls the “action” (synth, deploy, destroy), while “interaction” (like gating or verifying resources) can be abstracted and customized.

Walkthrough: Ephemeral Environment with Automated Testing

In this example, we’ll build a minimal test harness that:

Creates a stack containing a Python Lambda function which requires a payload value of "test-successful", otherwise it fails.
Deploys the stack programmatically using the AWS CDK Toolkit Library.
Retrieves the Lambda function ARN and invokes it with a valid payload to confirm it returns success.
(Optionally, we’ll comment out code that shows how to invoke with an invalid payload and confirm the test fails.)
Destroys the stack once testing completes.

Project Setup

Below are the minimal steps needed to initialize a new TypeScript project and install the required dependencies:

1. Initialize Your Project

2. Install TypeScript and Related Dev Tools

3. Install AWS CDK Libraries and other libraries

4. Install the Toolkit Library (Alpha)

5. Install the AWS SDK v3 for Lambda

You should now have a tsconfig.json file (from npx tsc --init) and a package.json that references the dependencies you just installed.

At this point, you can create new .ts files and run them using npx ts-node <filename>.

Step 1: Define Your Python Lambda

Create a directory named lambda/ containing a file main.py:

The code in the lambda handler is straightforward: If it receives “test-successful” in the payload, it returns status of “ok”, if it does not, it will return the status of “error”. This is how we will test against the function in our test harness below.

Step 2: Create Your CDK Stack (TypeScript Example)

Below is a simple CDK stack that includes the above Python Lambda function. This is the stack code that our test harness will use when synthesizing and building our CDK application.

Save this as payload-check-stack.ts:

Step 3: Set Up Your Test Harness with the Toolkit Library

The following script: lambda-test-harness.ts, illustrates how you might use the Toolkit Library to build an ephemeral test environment to validate functionality of an application, deployed to a real world environment. In the below code, we deploy the PayloadCheckStack, test the functionality of the lambda python application by invoking the Lambda, and once our tests are complete, destroy the stack.

Some Key Points in This Snippet

· Programmatic CDK Deployment: The first step is to define how the cloud assembly is built, using the toolkit.fromAssemblyBuilder function. We then take the assembly object and use the toolkit.deploy() method to create the stack, just like running cdk deploy but entirely in code and with optional parameters to define the deployment specific to the needs of the use case.

· Access CFN Outputs Natively: Because the stack exports the function ARN as a CloudFormation Output, we can easily access it from the DeployedStack interface using the outputs property. This provides flexibility for users when needing to derive information related to resources deployed from the CDK application. Whether it’s to interact with those resources, store those resource ID’s somewhere for reference, users can build extensive automation around their use cases, all natively in code.

· Test the Lambda Function: Since we are able to access the outputs, we are able to grab the Lambda Function ARN, which we use to invoke it using the AWS SDK for JavaScript v3, verifying the test case works as expected.

· Clean Up: Once testing is done, we tear down the stack with toolkit.destroy().

Let’s walk through a run of the above automation to better understand what this looks like.

For the first run of the test harness, we will invoke the lambda function by sending the correct payload. This in return will show that our test was successful as it proceeds to then destroy the stack. Start by uncommenting the invokeLambda call where the payload provided is “test-successful”.

await invokeLambda(functionArn, { payload: 'test-successful' });

Next, run the test harness.

The first two steps in the automation are to synthesize the CDK cloud assembly, then deploy it. The output from the logs offers the same experience that one would see when deploying using the CLI, with some additional logging that we added.

The next step in the automation (after the CDK deployment is complete) is to get the ARN for the Lambda Function that was just deployed (via a CloudFormation Output), and invoke that function with a payload that defined above, which will provide a successful response.

Now that the function test is complete, the last step will destroy the CDK stack.

That’s it! Now let’s change the payload we send during the test and get the failed test response. First uncomment the invokeLambda call with the wrong payload, and comment out the one with the correct payload.

// Uncomment to test a successful payload
//await invokeLambda(functionArn, { payload: 'test-successful' });
// Uncomment to test a failed payload
await invokeLambda(functionArn, { payload: 'test-failed' });

And run the test again with npx ts-node payload-check-stack.ts.

The log output will all remain the same with the build and destroy steps, but the output from the lambda invocation, will show that the Lambda function failed the test.

Lambda test failing — Lambda Test Failure

In the above walkthrough, we showed one of the many use cases where this library can help teams build powerful automation around the CDK, without having to use the CLI.

Limitations and Considerations

Alpha Status: The AWS CDK Toolkit Library is in alpha. Some APIs may change, and it may not have a perfect 1:1 mapping with the CLI for all features.
Local & CI Usage: Remember to set your AWS credentials and region environment variables or configuration within your code or CI system.
Cloud Assembly Output: The library still produces a Cloud Assembly (e.g., cdk.out). These outputs are important and used in the same way that the CDK CLI synths, deploys, etc.
Language Support: At this time, the toolkit library is only supported in Typescript. CDK Apps can still be written in any of the supported languages. We expect that over time, this will be made available in other languages, but encourage users to reach out with what languages they’d like to see supported.

Conclusion and Call to Action

The AWS CDK Toolkit Library (Alpha) opens up a whole new range of possibilities for platform engineers and developers who need finer grained control over how and when their infrastructure is deployed and tested. By embedding the library into your own testing frameworks, custom CLIs, or automation pipelines, you can:

Automatically validate application logic (like our payload checking Lambda example).
Maintain ephemeral environments for integration or end to end testing.
Clean up resources immediately after tests complete, reducing cloud costs and “drift.”

Next Steps

Try It Out: Read the API documentation and experiment with the sample code above.
Share Feedback: As you implement custom workflows, share your experience via GitHub issues or in the AWS CDK community channels (CDK.dev Slack Workspace). This helps shape the direction of the library.
Stay Informed: Keep an eye on AWS CDK release notes for updates on the Toolkit Library. Because it’s alpha, expect rapid improvements and breaking changes as the API evolves.

We hope this inspires you to automate your infrastructure testing and deployment workflows in new ways using the AWS CDK Toolkit Library.

Site Terms, Privacy, and more.