cloudformation-cli (cfn-cli)

0.2.39 verified Sat May 09 auth: no python

CloudFormation CLI (cfn-cli) is the official AWS tool for building, testing, and publishing AWS CloudFormation resource type providers, modules, and hooks. The current version is 0.2.39. It allows developers to create custom CloudFormation resource types using Java or Python, run contract tests, and submit them to the CloudFormation registry. The release cadence is irregular, with 3-4 minor releases per year.

pip install cloudformation-cli

Common errors

error pkg_resources.DistributionNotFound: The 'cloudformation-cli' distribution was not found and is required by the application ↓

cause The cloudformation-cli package is not installed in the current Python environment.

fix

Run pip install cloudformation-cli.

error ModuleNotFoundError: No module named 'cloudformation_cli_python_lib' ↓

cause The Python resource type library is missing. It is a separate package, not included automatically with cloudformation-cli.

fix

Run pip install cloudformation-cli-python-lib (or add it to your project's requirements).

error botocore.exceptions.NoCredentialsError: Unable to locate credentials ↓

cause AWS credentials not configured for calls made by `cfn submit` or `cfn test`.

fix

Configure credentials via aws configure or environment variables.

error cfn test: error: argument --endpoint: expected one argument ↓

cause The `cfn test` command requires an endpoint URL (Lambda or local simulation) which is missing.

fix

Use cfn test --endpoint http://localhost:3001 (or your Lambda endpoint). For local testing, first start the sandbox: cfn invoke-resource --endpoint http://localhost:3001 (or use Docker).

Warnings

gotcha When running `cfn test`, ensure Docker is installed and the daemon is running, as contract tests spin up a local Lambda-like container. ↓

fix Install Docker Desktop and start the daemon before running `cfn test`.

gotcha The `cfn submit` command requires valid AWS credentials with permissions to register resource types. Many users fail to configure credentials, leading to `AccessDenied` errors. ↓

fix Run `aws configure` or set environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION.

breaking In v0.2.30+, the `cfn generate` command requires the CloudFormation resource schema to be present; omitted schema leads to `FileNotFoundError`. ↓

fix Ensure you are in the project root with a valid `resource-role.yaml` or schema file before running `cfn generate`.

deprecated Python 3.6 support ended with v0.2.33; the latest versions require Python >=3.7. ↓

fix Upgrade to Python 3.7 or later (recommend 3.9+).

Install

pip install cloudformation-cli[local-testing]

Imports

cloudformation_cli_python_lib
```
from cloudformation_cli_python_lib import BaseResourceHandler, exceptions
```
No common wrong import; the library is installed as a separate package (cloudformation-cli-python-lib) and imported as cloudformation_cli_python_lib.

Quickstart

Initialize a CloudFormation resource type project and implement a basic resource handler using the Python library.

import os
import json

# Initialize a new resource type project
os.system('cfn init')

# Example: simple resource handler (Java in README, Python equivalent)
# Usually generated; here's a minimal Python handler placeholder
from cloudformation_cli_python_lib import BaseResourceHandler, exceptions

class MyResource(BaseResourceHandler):
    def create(self, request):
        # model = request.desiredResourceState
        # ... implement create logic
        return {"resourceModel": request.desiredResourceState}
    
    def read(self, request):
        pass
    
    def update(self, request):
        pass
    
    def delete(self, request):
        pass

# To run contract tests:
# os.system('cfn test')