**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.
npm install carlincarlin 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.
``bash`
pnpm add -D carlin
Or install globally:
`bash`
pnpm add -g carlin
Deploy your CloudFormation template with a single command:
`bash`
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
Create a simple CloudFormation template:
`typescript`
// cloudformation.ts
export const template = {
Resources: {
MyBucket: {
Type: 'AWS::S3::Bucket',
Properties: {
BucketName: 'my-app-bucket',
},
},
},
Outputs: {
BucketName: {
Value: { Ref: 'MyBucket' },
},
},
};
Deploy it:
`bash`
carlin deploy
That's it! carlin creates the stack and outputs the bucket name.
carlin automatically generates CloudFormation stack names based on:
1. Package name from package.json
2. Environment (staging, production) or branch name
3. Custom 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)
Define environments using:
- --environment flag: carlin deploy --environment production
- variable: CARLIN_ENVIRONMENT=staging carlin deploy
- Config file: with environment: production
Environments enable:
- Automatic termination protection for production stacks
- Environment-specific configurations
- Multi-stage deployment workflows
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:
`typescript
// 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' },
},
},
},
},
};
`
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:
`bash`
carlin deploy base-stack --environment production
Deploy CloudFormation stacks and resources.
`bash`
carlin deploy [options]
#### Main Options
- --template-path - CloudFormation template file path--stack-name
- - Custom stack name--parameters
- - CloudFormation parameters as JSON object--environment
- - Environment name (enables termination protection)--region
- - AWS region (default: us-east-1)--destroy
- - Delete the stack instead of deploying
#### Subcommands
- deploy static-app - Deploy static websites to S3 + CloudFrontdeploy lambda-layer
- - Deploy Lambda layersdeploy base-stack
- - Deploy base infrastructure stackdeploy cicd
- - Deploy CI/CD pipeline infrastructuredeploy vercel
- - Deploy to Vercel platformdeploy describe
- - Show stack outputs without deploying
See full command documentation for all options and examples.
Generate .env files from CloudFormation stack outputs.
`bash`
carlin generate-env --stack-name MyStack --output .env
Fetches stack outputs and creates environment variables file:
`bash`Generated by carlin
API_URL=https://api.example.com
BUCKET_NAME=my-app-bucket-xyz123
Report ECS task status to GitHub/Slack during CI/CD deployments.
`bash`
carlin cicd-ecs-task-report --cluster my-cluster --task-arn
Configure carlin using CLI options, environment variables, or config files.
Create carlin.yml in your project root:
`yaml`
environment: staging
region: us-east-1
stackName: my-custom-stack
parameters:
DomainName: example.com
CertificateArn: arn:aws:acm:...
Prefix any option with CARLIN_:
`bash`
CARLIN_ENVIRONMENT=production carlin deploy
CARLIN_REGION=eu-west-1 carlin deploy
CARLIN_STACK_NAME=CustomStack carlin deploy
Configuration priority (highest to lowest):
1. CLI options (--environment production)CARLIN_ENVIRONMENT=production
2. Environment variables ()carlin.yml
3. Config file ()
4. Defaults
Deploy to multiple environments with different configurations:
`bashDeploy to staging
carlin deploy --environment staging --parameters '{"InstanceType":"t3.micro"}'
$3
Search for templates in custom locations:
bash
carlin deploy --template-path infrastructure/cloudformation.ts
`$3
Build Lambda functions from Dockerfiles:
bash
carlin deploy --lambda-dockerfile Dockerfile
`carlin automatically:
- Builds the Docker image
- Pushes to ECR
- Updates Lambda function with new image URI
$3
Production stacks are protected from accidental deletion:
bash
This fails if environment is defined
carlin deploy --destroy --environment productionForce deletion by removing environment
carlin deploy --destroy --stack-name my-stack-production
`$3
Deploy feature branches for testing:
bash
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
$3
If deployment fails with "Stack already exists", check:
- Stack name conflicts (use
to customize)
- Existing stacks in AWS Console (CloudFormation → Stacks)
- Branch name conflicts (different branches may create same stack name)$3
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$3
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$3
Ensure AWS credentials have necessary permissions:
-
for stack operations
- s3:* for Lambda code uploads
- iam:* for creating roles
- lambda:*` for function deployments- Terezinha Farm API
- POC - AWS Serverless REST API
Full documentation: https://ttoss.dev/docs/carlin/
MIT © Pedro Arantes