Skip to main content

generate-env

Generate .env files from CloudFormation stack outputs.

Overview​

carlin generate-env

This command fetches CloudFormation stack outputs and creates environment variable files for local development or CI/CD pipelines.

Quick Start​

Generate .env from current stack:

carlin generate-env

This creates .env.Staging (default) with stack outputs:

# .env.Staging
API_URL=https://api.example.com
BUCKET_NAME=my-app-bucket-xyz123
TABLE_NAME=my-app-table

Use Cases​

Local Development​

Generate environment variables for local development:

# Deploy stack
carlin deploy --environment staging

# Generate .env file
carlin generate-env --default-environment Staging

# Use in your app
source .env.Staging
pnpm dev

CI/CD Integration​

Generate environment files in GitHub Actions:

# .github/workflows/deploy.yml
- name: Deploy Infrastructure
  run: carlin deploy --environment production

- name: Generate Environment Variables
  run: carlin generate-env --default-environment Production

- name: Deploy Application
  run: |
    source .env.Production
    pnpm build
    pnpm deploy

Multi-Environment Setup​

Generate environment files for all environments:

# Staging
carlin generate-env --stack-name my-app-staging --default-environment Staging

# Production
carlin generate-env --stack-name my-app-production --default-environment Production

Creates:

  • .env.Staging
  • .env.Production

Options​

--default-environment (-d)​

Environment name for the generated file.

carlin generate-env --default-environment Production

Default: Staging

Output: .env.Production

--path (-p)​

Directory where .env files will be created.

carlin generate-env --path config/envs

Default: ./ (current directory)

Output: config/envs/.env.Staging

--stack-name​

CloudFormation stack name to fetch outputs from.

carlin generate-env --stack-name my-custom-stack

Default: Auto-detected based on package name and branch/environment

Examples​

Basic Usage​

carlin generate-env
# Creates .env.Staging with stack outputs

Custom Environment Name​

carlin generate-env --default-environment Development
# Creates .env.Development

Specific Stack​

carlin generate-env \
  --stack-name my-app-production \
  --default-environment Production
# Creates .env.Production with my-app-production stack outputs

Custom Output Path​

carlin generate-env --path .envs
# Creates .envs/.env.Staging

Multiple Environments​

# Generate for all environments
carlin generate-env --stack-name app-dev --default-environment Development
carlin generate-env --stack-name app-staging --default-environment Staging
carlin generate-env --stack-name app-prod --default-environment Production

Output Format​

Generated .env file contains stack outputs as key-value pairs:

# .env.Staging
# Generated by carlin generate-env
# Stack: my-app-staging
# Region: us-east-1
# Generated at: 2025-11-22T10:30:00Z

API_ENDPOINT=https://abc123.execute-api.us-east-1.amazonaws.com/prod
BUCKET_NAME=my-app-staging-bucket
TABLE_NAME=my-app-staging-table
DATABASE_URL=postgresql://user:pass@db.example.com:5432/myapp
CLOUDFRONT_URL=https://d111111abcdef8.cloudfront.net

Output Key Naming​

Stack output keys are converted to uppercase with underscores:

CloudFormation Output Key.env Variable Name
ApiEndpointAPI_ENDPOINT
bucketNameBUCKET_NAME
DatabaseURLDATABASE_URL
cloudFrontDistributionIdCLOUD_FRONT_DISTRIBUTION_ID

CloudFormation Outputs​

Define outputs in your template:

// cloudformation.ts
export const template = {
  Resources: {
    Api: {
      Type: 'AWS::ApiGateway::RestApi',
      Properties: { Name: 'MyApi' },
    },
    Bucket: {
      Type: 'AWS::S3::Bucket',
    },
  },
  Outputs: {
    ApiEndpoint: {
      Description: 'API Gateway endpoint',
      Value: {
        'Fn::Sub':
          'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/prod',
      },
    },
    BucketName: {
      Description: 'S3 bucket name',
      Value: { Ref: 'Bucket' },
    },
  },
};

After deploying:

carlin deploy
carlin generate-env

.env.Staging contains:

API_ENDPOINT=https://abc123.execute-api.us-east-1.amazonaws.com/prod
BUCKET_NAME=my-app-staging-bucket-xyz123

Using Generated Files​

In Node.js/TypeScript​

// Load environment variables
import * as dotenv from 'dotenv';
dotenv.config({ path: '.env.Staging' });

// Use variables
const apiUrl = process.env.API_ENDPOINT;
const bucketName = process.env.BUCKET_NAME;

In Shell Scripts​

#!/bin/bash
source .env.Production

echo "Deploying to: $API_ENDPOINT"
curl $API_ENDPOINT/health

In Docker​

# Dockerfile
FROM node:20
COPY .env.Production .env
ENV $(cat .env | xargs)
CMD ["node", "server.js"]

Workflow Integration​

Deployment + Environment Generation​

#!/bin/bash
# deploy.sh

# Deploy infrastructure
carlin deploy --environment production

# Generate environment variables
carlin generate-env --default-environment Production

# Build application with variables
source .env.Production
pnpm build

# Deploy application
pnpm deploy:app

GitHub Actions​

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Deploy Infrastructure
        run: carlin deploy --environment production

      - name: Generate Environment Variables
        run: carlin generate-env --default-environment Production

      - name: Build Application
        run: |
          source .env.Production
          pnpm install
          pnpm build

      - name: Upload .env to Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: environment-variables
          path: .env.Production

Best Practices​

1. Add .env.* to .gitignore​

# .gitignore
.env.*
!.env.example

Environment files contain sensitive data—never commit them.

2. Create .env.example Template​

# .env.example
API_ENDPOINT=
BUCKET_NAME=
TABLE_NAME=
DATABASE_URL=

Commit this template for documentation.

3. Generate Before Running Application​

{
  "scripts": {
    "deploy": "carlin deploy && carlin generate-env",
    "dev": "source .env.Staging && vite",
    "build": "source .env.Production && vite build"
  }
}

4. Use Different Files Per Environment​

# Development
carlin generate-env --default-environment Development
source .env.Development

# Staging
carlin generate-env --default-environment Staging
source .env.Staging

# Production
carlin generate-env --default-environment Production
source .env.Production

Troubleshooting​

Stack Not Found​

Error: Stack not found

Solution: Deploy stack first or specify correct stack name:

carlin deploy
carlin generate-env

No Outputs Defined​

Error: .env file is empty

Solution: Add outputs to CloudFormation template:

export const template = {
  Outputs: {
    MyOutput: {
      Value: 'some-value',
    },
  },
};

Permission Denied​

Error: Cannot write .env file

Solution: Check directory permissions or use --path:

carlin generate-env --path /tmp