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
  default: "dev"                # Optional: profile loaded when no --profile/ATMOS_PROFILE is set
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)

profiles.default

Name of a profile loaded automatically when neither the --profile flag nor the ATMOS_PROFILE environment variable is set.

The default is treated as implicit — an explicit --profile or ATMOS_PROFILE always wins, and a default profile's own profiles.default is ignored (no recursion).

Default: Not set

Precedence​

Atmos resolves the active profile using this precedence (highest first):

  1. --profile flag
  2. ATMOS_PROFILE environment variable
  3. profiles.default in the base atmos.yaml
  4. No profile

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

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.

Interactive Profile Suggestion​

Atmos offers two complementary prompt flows when your profile selection is missing context for auth.

Identity-specific suggestion​

When you run a command with --identity <name> but that identity isn't defined in the currently loaded config, Atmos checks whether any available profile defines it.

Interactive terminal: Atmos prompts you to switch. If exactly one profile defines the identity, you get a yes/no confirmation; if multiple do, you get a select list. Picking a profile re-executes Atmos with --profile <picked> prepended to your original arguments.

Non-interactive terminal (CI, scripts): The identity not found error is enriched with hints naming the profile(s) and the exact --profile flag to re-run.

Generic fallback for auth commands​

When you run an auth command without --identity — e.g. atmos auth login, atmos auth exec, atmos auth shell, atmos auth env, atmos auth console, atmos auth whoami — and the base configuration has no usable auth.identities or auth.providers, Atmos checks whether any profile defines auth config at all.

Interactive terminal: You get a select list of every profile whose atmos.yaml declares auth.identities or auth.providers. Picking one re-executes your command with --profile <picked> prepended.

Non-interactive terminal (CI, scripts): The no identities available error is enriched with one hint per candidate profile and a closing hint showing the --profile flag to re-run with.

Shared behavior​

The suggestion (either form) is suppressed when you already passed --profile or set ATMOS_PROFILE — an explicit choice is always respected. A profiles.default from config counts as implicit, so the suggestion still fires when the default profile doesn't resolve the identity but another profile does.

A loop guard (ATMOS_PROFILE_FALLBACK=1, set automatically during re-exec) prevents infinite prompt cycles if the selected profile also fails to resolve the identity.

See Also​