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

Profiles apply on top of whatever base configuration was selected — including a base loaded via --config or --config-path — so atmos --config ./main.yaml --profile ci ... merges the ci profile over main.yaml, the same way it would over an auto-discovered atmos.yaml.

Pinning a Profile Per Project​

You can pin a profile for a whole project by setting ATMOS_PROFILE in a committed dotenv file and including it in the base atmos.yaml env section:

.env
ATMOS_PROFILE=dev
atmos.yaml
env: !include .env

Atmos promotes ATMOS_-prefixed variables from the env section into its own environment before it resolves the active profile, so every atmos command in the project uses the dev profile automatically. An exported ATMOS_PROFILE (or a --profile flag) still wins, so per-command overrides like ATMOS_PROFILE=ci atmos … continue to work. See Pinning Atmos Configuration Per Project for details.

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

__SELECT__ is a reserved profile directory name — it's the sentinel bare --profile uses to trigger interactive selection, so a profile with that name can never be activated explicitly. Atmos excludes any __SELECT__ directory from discovery.

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

Interactive Selection​

Use --profile without a value to open a multi-select picker listing every profile Atmos discovers (see Profile Discovery). Nothing is pre-checked by default — toggle the profiles you want with space, then confirm — they're activated left-to-right in the order shown, same as if you'd typed them explicitly.

atmos auth login -i core-auto/terraform --profile

Any profile name already typed explicitly alongside the bare flag (e.g. --profile ci --profile) starts pre-checked in the picker, since you asked for it — but the form is still yours to edit, including unchecking it.

This requires an interactive terminal. In CI, scripts, or any non-interactive context, use --profile=<name> or ATMOS_PROFILE explicitly instead — --profile used bare there returns an error rather than hanging.

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.

Related Commands​

See Also​