carlin

carlin is a CLI tool for deploying AWS cloud resources using CloudFormation templates. It streamlines infrastructure deployment with automatic Lambda code building, S3 upload handling, stack naming, and multi-environment support.

Installation

pnpm add -D carlin

Or install globally:

pnpm add -g carlin

Quick Start

Deploy your CloudFormation template with a single command:

carlin deploy

carlin automatically:

• Searches for your CloudFormation template (cloudformation.ts, cloudformation.yml, or template.yml)
• Builds and uploads Lambda function code to S3
• Creates or updates your CloudFormation stack
• Displays stack outputs after deployment

First Deployment Example

Create a simple CloudFormation template:

// cloudformation.ts
export const template = {
  Resources: {
    MyBucket: {
      Type: 'AWS::S3::Bucket',
      Properties: {
        BucketName: 'my-app-bucket',
      },
    },
  },
  Outputs: {
    BucketName: {
      Value: { Ref: 'MyBucket' },
    },
  },
};

Deploy it:

carlin deploy

That's it! carlin creates the stack and outputs the bucket name.

Core Concepts

Stack Naming

carlin automatically generates CloudFormation stack names based on:

1. Package name from package.json
2. Environment (staging, production) or branch name
3. Custom --stack-name option (overrides automatic naming)

Example stack names:

• my-app-production (package: my-app, environment: production)
• my-app-feature-auth (package: my-app, branch: feature/auth)
• CustomStack (using --stack-name CustomStack)

Environments

Define environments using:

• --environment flag: carlin deploy --environment production
• CARLIN_ENVIRONMENT variable: CARLIN_ENVIRONMENT=staging carlin deploy
• Config file: carlin.yml with environment: production

Environments enable:

• Automatic termination protection for production stacks
• Environment-specific configurations
• Multi-stage deployment workflows

Lambda Functions

carlin automatically handles Lambda deployment:

1. Detects Lambda functions in your CloudFormation template
2. Builds code using esbuild
3. Uploads to S3 with versioning
4. Injects S3 parameters into your template

Example Lambda function:

// src/handler.ts
export const handler = async (event) => {
  return { statusCode: 200, body: 'Hello World' };
};

// cloudformation.ts
export const template = {
  Resources: {
    MyFunction: {
      Type: 'AWS::Lambda::Function',
      Properties: {
        Runtime: 'nodejs20.x',
        Handler: 'handler.handler', // carlin finds and builds src/handler.ts
        Code: {
          S3Bucket: { Ref: 'LambdaS3Bucket' },
          S3Key: { Ref: 'LambdaS3Key' },
          S3ObjectVersion: { Ref: 'LambdaS3ObjectVersion' },
        },
      },
    },
  },
};

Base Stack

The base stack provides shared infrastructure:

• S3 bucket for Lambda code storage
• CloudFront distribution for static apps
• Lambda image builder for container deployments

Deploy base stack once per environment:

carlin deploy base-stack --environment production

Commands

deploy

Deploy CloudFormation stacks and resources.

carlin deploy [options]

Main Options

• --template-path <path> - CloudFormation template file path
• --stack-name <name> - Custom stack name
• --parameters <json> - CloudFormation parameters as JSON object
• --environment <env> - Environment name (enables termination protection)
• --region <region> - AWS region (default: us-east-1)
• --destroy - Delete the stack instead of deploying

Subcommands

• deploy static-app - Deploy static websites to S3 + CloudFront
• deploy lambda-layer - Deploy Lambda layers
• deploy base-stack - Deploy base infrastructure stack
• deploy cicd - Deploy CI/CD pipeline infrastructure
• deploy vercel - Deploy to Vercel platform
• deploy describe - Show stack outputs without deploying

See full command documentation for all options and examples.

generate-env

Generate .env files from CloudFormation stack outputs.

carlin generate-env --stack-name MyStack --output .env

Fetches stack outputs and creates environment variables file:

# Generated by carlin
API_URL=https://api.example.com
BUCKET_NAME=my-app-bucket-xyz123

cicd-ecs-task-report

Report ECS task status to GitHub/Slack during CI/CD deployments.

carlin cicd-ecs-task-report --cluster my-cluster --task-arn <arn>

Configuration

Configure carlin using CLI options, environment variables, or config files.

Config File

Create carlin.yml in your project root:

environment: staging
region: us-east-1
stackName: my-custom-stack
parameters:
  DomainName: example.com
  CertificateArn: arn:aws:acm:...

Environment Variables

Prefix any option with CARLIN_:

CARLIN_ENVIRONMENT=production carlin deploy
CARLIN_REGION=eu-west-1 carlin deploy
CARLIN_STACK_NAME=CustomStack carlin deploy

Priority

Configuration priority (highest to lowest):

1. CLI options (--environment production)
2. Environment variables (CARLIN_ENVIRONMENT=production)
3. Config file (carlin.yml)
4. Defaults

Advanced Usage

Multi-Environment Deployment

Deploy to multiple environments with different configurations:

# Deploy to staging
carlin deploy --environment staging --parameters '{"InstanceType":"t3.micro"}'

# Deploy to production
carlin deploy --environment production --parameters '{"InstanceType":"t3.large"}'

Custom Template Paths

Search for templates in custom locations:

carlin deploy --template-path infrastructure/cloudformation.ts

Docker-Based Lambda Functions

Build Lambda functions from Dockerfiles:

carlin deploy --lambda-dockerfile Dockerfile

carlin automatically:

• Builds the Docker image
• Pushes to ECR
• Updates Lambda function with new image URI

Termination Protection

Production stacks are protected from accidental deletion:

# This fails if environment is defined
carlin deploy --destroy --environment production

# Force deletion by removing environment
carlin deploy --destroy --stack-name my-stack-production

Branch-Based Deployments

Deploy feature branches for testing:

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

# On main branch
carlin deploy --environment production
# Creates stack: my-app-production

Troubleshooting

Stack Already Exists

If deployment fails with "Stack already exists", check:

• Stack name conflicts (use --stack-name to customize)
• Existing stacks in AWS Console (CloudFormation → Stacks)
• Branch name conflicts (different branches may create same stack name)

Lambda Build Failures

If Lambda code building fails:

• Verify Handler path points to existing file (src/handler.ts)
• Check --lambda-entry-points-base-dir matches your source directory
• Review build logs for missing dependencies

Template Too Large

CloudFormation templates over 51,200 bytes must be uploaded to S3:

• carlin automatically uploads large templates to base stack bucket
• Ensure base stack exists: carlin deploy base-stack
• Or reduce template size by removing comments/whitespace

Permission Errors

Ensure AWS credentials have necessary permissions:

• cloudformation:* for stack operations
• s3:* for Lambda code uploads
• iam:* for creating roles
• lambda:* for function deployments

Examples

• Terezinha Farm API
• POC - AWS Serverless REST API

Documentation

Full documentation: https://ttoss.dev/docs/carlin/

License

MIT © Pedro Arantes