Introduction

carlin is a CLI tool for deploying AWS infrastructure using CloudFormation templates. It automates Lambda code building, S3 uploads, stack naming, multi-environment deployments, and CI/CD pipelines.

What is carlin?

carlin started in 2018 as deployment scripts for managing CloudFormation stacks across multiple environments (development, staging, production). After streamlining numerous deployments, we packaged these scripts into a unified CLI tool.

Today, carlin handles:

• CloudFormation deployments with automatic stack naming
• Lambda functions with code building and S3 uploads
• Static websites via S3 and CloudFront
• CI/CD pipelines with GitHub and Slack integration
• Environment variables generation from stack outputs
• Multi-environment configurations with termination protection
• Deploy reports posted to GitHub PR comments via carlin deploy report

Why Use carlin?

Simplified AWS Deployments

Deploy CloudFormation stacks with a single command:

carlin deploy

carlin automatically:

• Finds your CloudFormation template
• Builds Lambda function code
• Uploads to S3 with versioning
• Creates or updates stacks
• Displays outputs

Automatic Lambda Handling

No manual Lambda packaging—carlin detects Lambda functions in templates, builds code with esbuild, uploads to S3, and injects parameters automatically.

Multi-Environment Support

Deploy to multiple environments with built-in protection:

carlin deploy --environment Staging
carlin deploy --environment Production # includes termination protection

This supports the E6: U-curve Principle by balancing automation with safety controls.

Branch-Based Deployments

Test feature branches with automatic stack naming:

# On feature/auth branch
carlin deploy
# Creates: my-app-feature-auth

Infrastructure as TypeScript

Write CloudFormation templates in TypeScript with type safety and dynamic generation:

export const template = {
  Resources: {
    Bucket: {
      Type: 'AWS::S3::Bucket',
      Properties: {
        BucketName: `my-app-${process.env.NODE_ENV}`,
      },
    },
  },
};

Use Cases

• Serverless APIs — Deploy Lambda functions with API Gateway via CloudFormation templates
• Static Websites — Deploy React/Vue/Vite apps to S3 + CloudFront via deploy static-app
• Full-Stack Applications — Combine infrastructure, APIs, and frontends using deploy and generate-env

Quick Start

Get started in 5 minutes:

1. Install carlin:

pnpm add -D carlin

2. Create CloudFormation template (cloudformation.ts):

export const template = {
  Resources: {
    MyBucket: {
      Type: 'AWS::S3::Bucket',
    },
  },
  Outputs: {
    BucketName: {
      Value: { Ref: 'MyBucket' },
    },
  },
};

3. Deploy:

carlin deploy

Documentation Structure

• Core Concepts - Stack naming, environments, base stack, templates
• Commands - Complete command reference

Key Features

• Automatic Stack Naming — Generates stack names from package.json and branch/environment
• Lambda Code Building — Automatic code bundling with esbuild, S3 upload, and parameter injection
• Static App Deployment — One command deploys to S3 + CloudFront
• Environment Variables — Generate .env files from stack outputs
• Multi-Environment Support — Automatic termination protection for environment-based deployments

Community and Support

• GitHub: ttoss/ttoss
• Issues: Report bugs or request features
• Examples: Terezinha Farm API