Configuration

Carlin provides flexible configuration through multiple sources, enabling both simple single-environment setups and complex monorepo scenarios with shared and project-specific settings.

Configuration Precedence

Options are resolved in the following order (highest to lowest priority):

Command-line flags (e.g., --environment Production)
Environment variables (e.g., CARLIN_ENVIRONMENT=Production)
Configuration files (carlin.yml, carlin.ts, etc.)
package.json (carlin property)
Default values

tip

Command-line options always override configuration files and environment variables, making them ideal for CI/CD overrides.

Setting Options

You can set the Carlin commands options in different ways, such as using the command line, environment variables, or a configuration file.

Command Line

You can set the Carlin commands options using the command line. For example, to set the --environment, -e, --env option, you can use the following command:

carlin deploy --environment Production
carlin deploy -e Production

Common CLI Patterns:

# Override region for specific deployment
carlin deploy --region us-west-2

# Multiple options
carlin deploy --environment Staging --stack-name my-custom-stack

# Boolean flags
carlin deploy --skip-build --termination-protection

package.json

You can also provide the options creating a property name carlin in your package.json.

{
  "name": "my-app",
  "version": "0.1.0",
  "carlin": {
    "environment": "Production",
    "region": "us-east-1",
    "awsAccountId": "123456789012"
  }
}

When to use:

Simple projects with a single package.json
Options that rarely change
Committing configuration to version control

caution

Avoid storing sensitive values like awsAccountId in package.json if the repository is public.

Environment Variables

You can set the options as environment variables matching the prefix CARLIN. The examples below are equivalent:

carlin deploy --stack-name MyStackName
CARLIN_STACK_NAME=MyStackName carlin deploy

ENVIRONMENT is a special case because it is used to set the environment option, as well CARLIN_ENVIRONMENT. The examples below are equivalent:

carlin deploy --environment Production
CARLIN_ENVIRONMENT=Production carlin deploy
ENVIRONMENT=Production carlin deploy

Configuration File

If --config isn't provided, the algorithm will search for any of these files and use it to retrieve the options:

carlin.ts
carlin.js
carlin.yml
carlin.yaml
carlin.json

The algorithm also make a find up path to search for other config files that may exist in parent directories. If find more than one file, they'll be merged, in such a way that the files nearest from process.cwd() will take the precedence at the merging.

This is useful if you have a monorepo and have shared and specific configuration. For instance, you may have a config inside packages/app/ folder with the config below:

stackName: MyMonorepoApp
region: us-east-2

And on the root of your monorepo:

awsAccountId: 123456789012
region: us-east-1

The result options that will be passed to the commands executed on packages/app/ will be:

awsAccountId: 123456789012
stackName: MyMonorepoApp
region: us-east-2

If you define your config file programmatically, you can use the your environment variables from a .env file if it exists. For example:

export default {
 environment: process.env.ENVIRONMENT,
 region: process.env.REGION,
}

Supported File Formats:

carlin automatically searches for configuration files in this order:

carlin.ts (TypeScript, evaluated at runtime)
carlin.js (JavaScript)
carlin.yml / carlin.yaml (YAML)
carlin.json (JSON)

Example YAML Configuration:

carlin.yml
# Shared configuration
region: us-east-1
awsAccountId: '123456789012'

# Stack naming
stackName: MyApp

# Deployment settings
terminationProtection: true
skipBuild: false

Example TypeScript Configuration:

carlin.ts
import { config } from 'dotenv';

// Load .env file
config();

export default {
  environment: process.env.ENVIRONMENT,
  region: process.env.AWS_REGION || 'us-east-1',
  awsAccountId: process.env.AWS_ACCOUNT_ID,
  stackName: 'MyApp',
};

Monorepo Configuration (Find-Up Merging):

carlin searches upward from process.cwd() and merges all found config files, with nearest files taking precedence.

monorepo/
├── carlin.yml              # Root config (shared)
│   awsAccountId: 123456789012
│   region: us-east-1
└── packages/
    └── app/
        └── carlin.yml      # Package config (specific)
            stackName: MyMonorepoApp
            region: us-east-2

Resulting configuration in packages/app/:

awsAccountId: '123456789012' # from root
stackName: MyMonorepoApp # from package
region: us-east-2 # package overrides root

Custom Config File Path:

carlin deploy --config ./configs/production.yml

Multiple Environments

We architected Carlin to work with multiple environments. The environments option is an object that contains specific values for each environment. For instance, you may have a Production and a Staging environment with different values for the same option, like awsAccountId. The environment option is a string that represents the current environment. The environments option is an object that contains the values for each environment. The values of the current environment will be merged with the default values.

For example, if you have the following config file:

awsAccountId: 111111111111

environments:
 Production:
   awsAccountId: 222222222222

 Staging:
   awsAccountId: 333333333333

And you run the following command:

carlin deploy --environment Production

The final awsAccountId value will be 222222222222. If you run the following command:

carlin deploy --environment Staging

The final awsAccountId value will be 333333333333. If you run the deploy command without the --environment option, the final value will be 111111111111.

environments is great to work on CI/CD pipelines. You can set the environment value as an environment variable and Carlin will use the values from the config file.

Common Environment Patterns:

Pattern	Configuration Approach
Single environment per branch	Use `ENVIRONMENT` env var in CI/CD
Shared config, different accounts	Override `awsAccountId` per environment
Environment-specific stacks	Use `stackName` with environment suffix
Multi-region deployments	Override `region` per pipeline stage

Example Multi-Environment Setup:

carlin.yml
# Base configuration
stackName: MyApp

# Development defaults
region: us-east-1
terminationProtection: false

carlin.production.yml
# Production overrides
awsAccountId: '999888777666'
region: us-west-2
terminationProtection: true

# Use different config per environment
carlin deploy --config carlin.production.yml --environment Production

See Multi-Environment Setup Guide for detailed strategies.

Common Configuration Scenarios

Single-Account Multi-Environment

carlin.yml
awsAccountId: '123456789012'
region: us-east-1
# stackName derived from package.json + environment

# Deploys stack: my-app-staging
ENVIRONMENT=staging carlin deploy

# Deploys stack: my-app-production
ENVIRONMENT=production carlin deploy

Multi-Account with Separate AWS Credentials

carlin.staging.yml
awsAccountId: '111111111111'
region: us-east-1

carlin.production.yml
awsAccountId: '999999999999'
region: us-east-2
terminationProtection: true

# Staging deployment (uses staging AWS profile)
AWS_PROFILE=staging carlin deploy --config carlin.staging.yml

# Production deployment (uses production AWS profile)
AWS_PROFILE=production carlin deploy --config carlin.production.yml

Monorepo with Shared Base Configuration

carlin.yml (root)
awsAccountId: '123456789012'
region: us-east-1
terminationProtection: true

packages/api/carlin.yml
stackName: MyAPI
# Inherits awsAccountId and region from root

packages/web/carlin.yml
stackName: MyWeb
region: us-west-2 # Override region for this package

Environment Variable Mapping

All global options can be set via environment variables with the CARLIN_ prefix:

Option	Environment Variable	Example
`environment`	`CARLIN_ENVIRONMENT`	`CARLIN_ENVIRONMENT=Production`
`region`	`CARLIN_REGION`	`CARLIN_REGION=us-west-2`
`stackName`	`CARLIN_STACK_NAME`	`CARLIN_STACK_NAME=CustomStack`
`awsAccountId`	`CARLIN_AWS_ACCOUNT_ID`	`CARLIN_AWS_ACCOUNT_ID=123456789012`

Troubleshooting Configuration

Issue	Cause	Solution
Wrong config loaded	Multiple config files found	Use `--config` to specify exact file
Options not applied	Typo in option name	Check spelling against Global Options
Monorepo config conflicts	Unclear merge order	Place most specific config nearest to package
Environment variable ignored	Wrong prefix	Ensure `CARLIN_` prefix for options

Global Options

Option	Alias	Default	Description	Type
branch				string
config	c		Path to config file. You can create a config file and set all options there. Valid extensions: .js, .json, .ts, .yml, or .yaml.	string
environment	e, env			string
environments
project				string
region	r	us-east-1	AWS region.	string

Configuration Precedence​

Setting Options​

Command Line​

package.json​

Environment Variables​

Configuration File​

Multiple Environments​

Common Configuration Scenarios​

Single-Account Multi-Environment​

Multi-Account with Separate AWS Credentials​

Monorepo with Shared Base Configuration​

Environment Variable Mapping​

Troubleshooting Configuration​

Global Options​