{"id":7956,"library":"aws-cdk-cx-api","title":"AWS CDK CX-API","description":"The `aws-cdk-cx-api` library is a core component of the AWS Cloud Development Kit (CDK), defining the Cloud Executable protocol. It provides interfaces and classes for working with Cloud Assemblies, which are the synthesized artifacts produced by CDK applications. These assemblies contain the CloudFormation templates, assets, and metadata required for deployment. This library is part of CDK v2 and is currently at version 2.250.0, with frequent updates tied to the main CDK release cycle.","status":"active","version":"2.250.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws-cdk","cloud-assembly","infrastructure-as-code","iac","aws","cli"],"install":[{"cmd":"pip install aws-cdk-cx-api","lang":"bash","label":"Install `aws-cdk-cx-api`"}],"dependencies":[{"reason":"Runtime compatibility","package":"python","version":">=3.9, <4.0"}],"imports":[{"note":"In CDK v2, all core constructs are under `aws_cdk` namespace. `CloudAssembly` is the primary class for loading synthesized assemblies. The `wrong` example shows a common mistake from CDK v1 (JavaScript) or attempting to import schema directly.","wrong":"from @aws-cdk/cloud-assembly-schema import CloudAssembly","symbol":"CloudAssembly","correct":"from aws_cdk.cx_api import CloudAssembly"},{"note":"Used to programmatically create or build a Cloud Assembly structure.","symbol":"CloudAssemblyBuilder","correct":"from aws_cdk.cx_api import CloudAssemblyBuilder"},{"note":"Enum representing different types of artifacts within a Cloud Assembly (e.g., CloudFormation stack, asset).","symbol":"ArtifactType","correct":"from aws_cdk.cx_api import ArtifactType"}],"quickstart":{"code":"import os\nfrom aws_cdk.cx_api import CloudAssembly, CloudAssemblyBuilder\n\n# Assuming 'cdk.out' exists in the current directory, typically created by 'cdk synth'.\nassembly_path = \"./cdk.out\"\n\nif os.path.isdir(assembly_path):\n    print(f\"Loading Cloud Assembly from: {assembly_path}\")\n    try:\n        assembly = CloudAssembly(directory=assembly_path)\n        print(f\"Assembly ID: {assembly.id}\")\n        print(f\"Version: {assembly.version}\")\n        print(\"Found stacks:\")\n        for stack in assembly.stacks:\n            print(f\"- {stack.stack_name} (Env: {stack.environment.name})\")\n        print(\"Artifacts:\")\n        for artifact in assembly.artifacts:\n            print(f\"- {artifact.id} (Type: {type(artifact).__name__})\")\n    except Exception as e:\n        print(f\"Error loading Cloud Assembly: {e}\")\n        print(\"Ensure 'cdk synth' was run successfully and 'cdk.out' is valid.\")\nelse:\n    print(f\"Directory '{assembly_path}' not found. Please run 'cdk synth' in a CDK project first.\")\n    print(\"Alternatively, you can create an empty assembly programmatically:\")\n    builder = CloudAssemblyBuilder(outdir=\"temp_cdk_out\")\n    builder.build()\n    print(\"Created empty assembly in 'temp_cdk_out'.\")\n    # os.system(\"rm -rf temp_cdk_out\") # Uncomment to clean up automatically\n","lang":"python","description":"This quickstart demonstrates how to load and inspect a synthesized AWS CDK Cloud Assembly. It assumes a `cdk.out` directory has been created by running `cdk synth` in a CDK project. It then prints details about the assembly, including its stacks and artifacts. An alternative path is provided to create an empty assembly programmatically if no `cdk.out` is available."},"warnings":[{"fix":"Update all imports from `aws_cdk.cx_api.ClassName` (or similar v1 patterns like `@aws-cdk/cloud-assembly-schema` in JavaScript) to `from aws_cdk.cx_api import ClassName` for v2.","message":"Migration from AWS CDK v1 to v2 consolidated all modules under the `aws_cdk` namespace. This means import paths for `aws-cdk-cx-api` classes changed significantly.","severity":"breaking","affected_versions":"CDK v1.x to v2.x"},{"fix":"Use `aws-cdk-lib` for defining CDK constructs, stacks, and apps. Use `aws-cdk-cx-api` when you need to programmatically analyze or manipulate the synthesized `cdk.out` output.","message":"The `aws-cdk-cx-api` library is for *inspecting* Cloud Assemblies, not for *defining* CDK applications. It operates on the output of `cdk synth` (the `cdk.out` directory).","severity":"gotcha","affected_versions":"All v2.x versions"},{"fix":"Ensure your `aws-cdk-cx-api` library version and the CDK CLI version used to synthesize the `cdk.out` directory are reasonably compatible. Upgrade both if encountering unexpected parsing failures.","message":"The schema of the Cloud Assembly (`manifest.json`, `tree.json`, etc.) can evolve between minor versions of CDK. Loading an assembly synthesized with a much older or newer CDK CLI version might lead to parsing errors.","severity":"gotcha","affected_versions":"All v2.x versions (minor versions)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install aws-cdk-cx-api`. If migrating from v1, ensure all imports use the `from aws_cdk.cx_api import ...` pattern.","cause":"The `aws-cdk-cx-api` package is not installed, or you are trying to use a CDK v1 import style for v2.","error":"ModuleNotFoundError: No module named 'aws_cdk.cx_api'"},{"fix":"Verify that `cdk synth` has been run successfully in your CDK project, creating the `cdk.out` directory. Check the path passed to `CloudAssembly(directory=...)`.","cause":"The specified directory for `CloudAssembly` (typically `cdk.out`) does not exist or the path is incorrect.","error":"jsii.errors.JavaScriptError: CloudAssembly directory does not exist: '<path_to_cdk.out>'"},{"fix":"Re-run `cdk synth` to ensure a complete and valid `cdk.out` directory is generated. Check the CDK CLI output for any errors during synthesis.","cause":"The `cdk.out` directory exists, but it's either empty, corrupted, or does not contain a valid `manifest.json` file, which is crucial for defining the Cloud Assembly.","error":"jsii.errors.JavaScriptError: Manifest file 'manifest.json' not found in '<path_to_cdk.out>'"}]}