Skip to main content

Profiles

Profiles allow you to define named sets of configuration overrides that can be activated at runtime. Use profiles to switch between development, CI/CD, and production settings without modifying your base configuration.

You will learn

  • Define environment-specific configuration overrides
  • Switch contexts with a single flag or environment variable
  • Define profiles as directories containing configuration files
  • Multiple profiles can be activated and merged together

Configuration​

Configure the profiles system in your atmos.yaml:

profiles:
  base_path: "custom/profiles"  # Optional: custom directory for profiles
profiles.base_path

Custom directory for profile storage. If relative, resolved from the atmos.yaml directory. If absolute, used as-is.

Default: Not set (uses standard profile locations)

Profile Discovery​

Atmos discovers profiles from multiple locations in the following precedence order (highest to lowest):

PriorityLocationDescription
1profiles.base_pathCustom path configured in atmos.yaml
2.atmos/profiles/Project-local hidden profiles
3~/.config/atmos/profiles/XDG user profiles (or $XDG_CONFIG_HOME/atmos/profiles/)
4profiles/Project-local profiles

When the same profile name exists in multiple locations, the higher-priority location takes precedence.

Creating Profiles​

Directory-Based Profiles​

Create a directory for each profile containing configuration files:

profiles/
├── developer/
│   ├── atmos.yaml      # Profile configuration overrides
│   └── auth.yaml       # Additional configuration files
├── ci/
│   └── atmos.yaml
└── production/
    ├── atmos.yaml
    └── auth.yaml

Each profile directory can contain:

  • atmos.yaml - Main configuration overrides
  • Additional YAML files that will be merged

Profile Configuration​

A profile's atmos.yaml can override any Atmos configuration setting:

profiles/developer/atmos.yaml

# Optional metadata
metadata:
  name: developer
  description: Development environment with debug logging
  version: "1.0.0"
  tags:
    - dev
    - local
    - debug

# Configuration overrides
logs:
  level: Debug

settings:
  terminal:
    max_width: 140
    pager: true
    syntax_highlighting:
      enabled: true

profiles/ci/atmos.yaml

metadata:
  name: ci
  description: CI/CD pipeline settings

logs:
  level: Warning
  file: /var/log/atmos.log

settings:
  terminal:
    color: false
    pager: false
    unicode: false

Profile Metadata​

The optional metadata section provides information about the profile:

metadata:
  name: "profile-name"           # Human-readable name
  description: "Description"     # What this profile is for
  version: "1.0.0"              # Semantic version
  tags:                          # Searchable tags
    - development
    - debug
  deprecated: false              # Mark profile as deprecated

Using Profiles​

Command-Line Flag​

Activate a profile using the --profile flag:

# Activate a single profile
atmos --profile developer terraform plan vpc -s prod

# Activate multiple profiles (applied left-to-right)
atmos --profile ci,security terraform plan vpc -s prod

Environment Variable​

Set the ATMOS_PROFILE environment variable:

# Single profile
export ATMOS_PROFILE=developer
atmos terraform plan vpc -s prod

# Multiple profiles (comma-separated)
export ATMOS_PROFILE="ci,security"
atmos terraform apply --auto-approve

Precedence​

When both the flag and environment variable are set, the flag takes precedence:

ATMOS_PROFILE=ci atmos --profile developer describe config
# Uses: developer profile (flag wins)

Profile Merging​

When multiple profiles are activated, they are merged left-to-right. Later profiles override earlier ones:

atmos --profile base,developer,debug terraform plan

Merge order:

  1. Base atmos.yaml configuration
  2. base profile applied
  3. developer profile applied (overrides base)
  4. debug profile applied (overrides developer)

Managing Profiles​

Use the atmos profile command to discover and inspect profiles:

# List all available profiles
atmos profile list

# Show details of a specific profile
atmos profile show developer

# List profiles in JSON format
atmos profile list --format json

See atmos profile for complete command documentation.

Use Cases​

Development Workflow​

# profiles/developer/atmos.yaml
logs:
  level: Debug

settings:
  terminal:
    max_width: 140
    pager: true
    syntax_highlighting:
      enabled: true
      theme: monokai
# Enable during development
atmos --profile developer describe stacks

CI/CD Pipelines​

# profiles/ci/atmos.yaml
logs:
  level: Warning
  file: /var/log/atmos.log

settings:
  terminal:
    color: false
    pager: false
    unicode: false
# In CI pipeline
export ATMOS_PROFILE=ci
atmos terraform apply --auto-approve

Team Collaboration​

Share profiles via version control:

.atmos/profiles/           # Team-shared profiles (gitignored user overrides)
├── team/
│   └── atmos.yaml
└── security-review/
    └── atmos.yaml

profiles/                  # Project-specific profiles
├── staging/
└── production/

User-Specific Profiles​

Store personal profiles in your XDG config directory:

~/.config/atmos/profiles/
├── personal/
│   └── atmos.yaml
└── experimental/
    └── atmos.yaml

These won't be committed to version control but are available across all projects.

See Also​