# 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.

> **Key points**
>
> - 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`:

```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):

| Priority | Location | Description |
|----------|----------|-------------|
| 1 | `profiles.base_path` | Custom 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/`) |
| 4 | `profiles/` | 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:

**File:** `profiles/developer/atmos.yaml`

```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
```

**File:** `profiles/ci/atmos.yaml`

```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:

```yaml
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:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
# 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`](/cli/commands/profile/usage) for complete command documentation.

## Use Cases

### Development Workflow

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

settings:
  terminal:
    max_width: 140
    pager: true
    syntax_highlighting:
      enabled: true
      theme: monokai
```

```bash
# Enable during development
atmos --profile developer describe stacks
```

### CI/CD Pipelines

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

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

```bash
# 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

- [Global Flags](/cli/global-flags) - Using the `--profile` flag