Skip to main content

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​

Documentation​

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

License​

MIT © Pedro Arantes