{"id":27656,"library":"cloudformation-cli","title":"cloudformation-cli (cfn-cli)","description":"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.","status":"active","version":"0.2.39","language":"python","source_language":"en","source_url":"https://github.com/aws-cloudformation/cloudformation-cli","tags":["aws","cloudformation","cli","resource-type","provider"],"install":[{"cmd":"pip install cloudformation-cli","lang":"bash","label":"default"},{"cmd":"pip install cloudformation-cli[local-testing]","lang":"bash","label":"with local testing dependencies"}],"dependencies":[{"reason":"Required for credential management and AWS API calls if not using boto3 directly.","package":"awscli","optional":true},{"reason":"Required for contract tests that run lambda-like environments.","package":"docker","optional":true}],"imports":[{"note":"No common wrong import; the library is installed as a separate package (cloudformation-cli-python-lib) and imported as cloudformation_cli_python_lib.","wrong":"","symbol":"cloudformation_cli_python_lib","correct":"from cloudformation_cli_python_lib import BaseResourceHandler, exceptions"}],"quickstart":{"code":"import os\nimport json\n\n# Initialize a new resource type project\nos.system('cfn init')\n\n# Example: simple resource handler (Java in README, Python equivalent)\n# Usually generated; here's a minimal Python handler placeholder\nfrom cloudformation_cli_python_lib import BaseResourceHandler, exceptions\n\nclass MyResource(BaseResourceHandler):\n    def create(self, request):\n        # model = request.desiredResourceState\n        # ... implement create logic\n        return {\"resourceModel\": request.desiredResourceState}\n    \n    def read(self, request):\n        pass\n    \n    def update(self, request):\n        pass\n    \n    def delete(self, request):\n        pass\n\n# To run contract tests:\n# os.system('cfn test')","lang":"python","description":"Initialize a CloudFormation resource type project and implement a basic resource handler using the Python library."},"warnings":[{"fix":"Install Docker Desktop and start the daemon before running `cfn test`.","message":"When running `cfn test`, ensure Docker is installed and the daemon is running, as contract tests spin up a local Lambda-like container.","severity":"gotcha","affected_versions":"all"},{"fix":"Run `aws configure` or set environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION.","message":"The `cfn submit` command requires valid AWS credentials with permissions to register resource types. Many users fail to configure credentials, leading to `AccessDenied` errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure you are in the project root with a valid `resource-role.yaml` or schema file before running `cfn generate`.","message":"In v0.2.30+, the `cfn generate` command requires the CloudFormation resource schema to be present; omitted schema leads to `FileNotFoundError`.","severity":"breaking","affected_versions":">=0.2.30"},{"fix":"Upgrade to Python 3.7 or later (recommend 3.9+).","message":"Python 3.6 support ended with v0.2.33; the latest versions require Python >=3.7.","severity":"deprecated","affected_versions":">=0.2.33"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Run `pip install cloudformation-cli`.","cause":"The cloudformation-cli package is not installed in the current Python environment.","error":"pkg_resources.DistributionNotFound: The 'cloudformation-cli' distribution was not found and is required by the application"},{"fix":"Run `pip install cloudformation-cli-python-lib` (or add it to your project's requirements).","cause":"The Python resource type library is missing. It is a separate package, not included automatically with cloudformation-cli.","error":"ModuleNotFoundError: No module named 'cloudformation_cli_python_lib'"},{"fix":"Configure credentials via `aws configure` or environment variables.","cause":"AWS credentials not configured for calls made by `cfn submit` or `cfn test`.","error":"botocore.exceptions.NoCredentialsError: Unable to locate credentials"},{"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).","cause":"The `cfn test` command requires an endpoint URL (Lambda or local simulation) which is missing.","error":"cfn test: error: argument --endpoint: expected one argument"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}