# Global Flags

# Global Flags

Global flags are available for all Atmos commands and control the overall behavior of the CLI. These flags take
precedence over environment variables and configuration files.

## Core Global Flags

These flags are available for every Atmos command:

- **`--chdir` / `-C`**

  Change the working directory before Atmos runs. Equivalent to running `cd <directory>` before executing `atmos`.

  **Use Cases:**
  - **Development workflow**: Test local Atmos builds against different infrastructure repos
  - **CI/CD**: Run Atmos from a build directory while operating on infrastructure elsewhere
  - **Multi-repo operations**: Execute commands across multiple repos without changing your shell
  - **Scripting**: Simplify scripts that operate on different directories
  **Basic Usage:**
  ```bash
  # Run as if you did: cd /path/to/infra && atmos terraform plan
  atmos -C /path/to/infra terraform plan vpc -s prod

  # Use environment variable
  ATMOS_CHDIR=/infrastructure atmos list components
  ```
  How it differs from --base-path

  **`--chdir`**: Changes the **process working directory** (calls `os.Chdir()`)
  - Like running `cd` before `atmos`
  - ALL file operations use the new directory
  - Happens **before** any configuration loading
  **`--base-path`**: Provides a **path prefix** for configuration (just a string)
  - Does **not** change the working directory
  - Used when joining paths: `filepath.Join(basePath, componentPath)`
  - Processed **after** `--chdir`
  **Examples showing the difference:**
  ```bash
  # Without any flags (current directory: /home/user)
  atmos terraform plan
  # Looks for atmos.yaml in: /home/user/atmos.yaml
  # Resolves components from: /home/user/components/terraform/

  # With --chdir (changes working directory)
  atmos --chdir=/infra terraform plan
  # Working directory changed to: /infra
  # Looks for atmos.yaml in: /infra/atmos.yaml
  # Resolves components from: /infra/components/terraform/

  # With --base-path (working directory unchanged)
  atmos --base-path=/infra terraform plan
  # Working directory still: /home/user
  # Base path prefix: /infra
  # Looks for atmos.yaml using: /infra prefix
  # Relative paths in config resolve from: /home/user

  # With both flags
  atmos --chdir=/home/user --base-path=/infra terraform plan
  # First: changes working directory to /home/user
  # Then: uses /infra as base path prefix
  # Result: paths like /infra are resolved relative to /home/user
  ```
- **`--base-path`**

  Specify the Atmos project root directory. Use this when your `atmos.yaml` and components are in a non-standard location.

  **When to use it:**
  - Your `atmos.yaml` and components are in a subdirectory
  - Using Atmos programmatically (like the Terraform provider)
  - Non-standard project layout where the Atmos root isn't the current directory
  **Basic Usage:**
  ```bash
  # Look for atmos.yaml and components using /custom/path as the base
  atmos --base-path=/custom/path terraform plan vpc -s prod

  # Combine with --chdir
  atmos --chdir=/infra --base-path=./custom describe stacks
  ```
  Technical details

  **What it does internally:**
  - Sets `atmosConfig.BasePath` (a configuration value, not a directory change)
  - Used as a prefix when joining paths: `filepath.Join(basePath, componentPath)`
  - Constructs paths to: stacks, terraform components, helmfile components, packer components
  - Does **not** call `os.Chdir()` or change the working directory
  **Path resolution:**
  - Supports both absolute and relative paths
  - Relative paths resolved using `filepath.Abs()` from current working directory
  - If `--chdir` was used, relative paths resolve from the NEW working directory
  - Can also use `ATMOS_BASE_PATH` environment variable
  See `--chdir` section above for detailed comparison of how these flags interact.
- **`--config`**

  Path to a specific Atmos configuration file.
  - Can be used multiple times for deep merging (later files override earlier ones)
  - Example: `--config=base.yaml --config=override.yaml`
- **`--config-path`**

  Path to a directory containing Atmos configuration files.
  - Can be used multiple times
  - Atmos looks for `atmos.yaml`, `.atmos.yaml`, `atmos.yml`, or `.atmos.yml` in these directories
- **`--profile`**

  Activate configuration profiles for environment-specific settings.

  **Use Cases:**
  - **Development workflow**: Use debug logging and wider terminal output during development
  - **CI/CD**: Disable interactive features and use plain text output in CI environments
  - **Team collaboration**: Share consistent settings across team members via profiles
  - **Multi-environment**: Different settings for staging vs production deployments
  **Basic Usage:**
  ```bash
  # Activate a single profile
  atmos --profile developer terraform plan vpc -s prod

  # Use environment variable
  ATMOS_PROFILE=developer atmos terraform plan vpc -s prod

  # Activate multiple profiles (comma-separated, applied left-to-right)
  atmos --profile ci,security terraform plan vpc -s prod
  ATMOS_PROFILE="developer,debug" atmos describe stacks

  # Flag takes precedence over environment variable
  ATMOS_PROFILE=ci atmos --profile developer describe config
  # Uses: developer profile (flag wins)
  ```
  **Profile Configuration:**

  Profiles are defined in your `atmos.yaml` or in separate profile directories. Each profile can override any Atmos configuration setting:
  ```yaml
  # atmos.yaml
  profiles:
    developer:
      logs:
        level: Debug
      settings:
        terminal:
          max_width: 120

    ci:
      logs:
        level: Info
      settings:
        terminal:
          color: false
          pager: false
  ```
  Or use separate profile directories for better organization:
  ```
  profiles/
  ├── developer/
  │   ├── atmos.yaml      # Developer-specific config
  │   └── auth.yaml       # Developer auth settings
  ├── ci/
  │   ├── atmos.yaml      # CI-specific config
  │   └── auth.yaml       # CI auth settings
  └── production/
      ├── atmos.yaml      # Production config
      └── auth.yaml       # Production auth settings
  ```
  **Available via:**
  - `--profile` flag
  - `ATMOS_PROFILE` environment variable
  > **Note**
  >
  > Profiles are loaded early in Atmos initialization (before stack processing) and can override any configuration setting including logging, terminal settings, and authentication.
- **`--logs-level`**

  Set the logging level for Atmos operations.
  - Options: `Trace`, `Debug`, `Info`, `Warning`, `Off`
  - Default: `Warning`
  - Can also use `ATMOS_LOGS_LEVEL` environment variable
- **`--logs-file`**

  File to write Atmos logs to.
  - Default: `/dev/stderr`
  - Can be any file path or standard file descriptor (`/dev/stdout`, `/dev/stderr`, `/dev/null`)
  - Can also use `ATMOS_LOGS_FILE` environment variable
- **`--no-color`**

  Disable colored terminal output.
  - Useful for CI/CD environments or when piping output
  - Can also use `ATMOS_NO_COLOR` or `NO_COLOR` environment variables
  - The `NO_COLOR` env var follows the standard from https://no-color.org/
  - **Takes highest precedence**: Overrides `--force-color`, `--color`, and all other color settings
- **`--force-tty`**

  Force TTY mode with sane defaults when terminal detection fails.
  - Useful for screenshot generation and documentation
  - Uses default terminal dimensions (width=120, height=40)
  - Forces `IsTTY()` to return `true` even when not a TTY
  - Can also use `ATMOS_FORCE_TTY` environment variable
  - Example: `atmos terraform plan --force-tty --force-color | screenshot.sh`
- **`--force-color`**

  Force TrueColor output even when not a TTY.
  - Useful for screenshot generation and documentation
  - Forces 24-bit TrueColor profile regardless of terminal detection
  - Overrides automatic color degradation
  - Can also use `ATMOS_FORCE_COLOR` environment variable
  - **Note**: The `NO_COLOR` environment variable or `--no-color` flag takes precedence and will disable color even when `--force-color` is set
  - Example: `ATMOS_FORCE_COLOR=true atmos describe stacks | vhs record.tape`
- **`--pager`**

  Configure pager behavior for command output.
  - `--pager` (no value): Enable pager with default settings
  - `--pager=true` or `--pager=on`: Explicitly enable pager
  - `--pager=false` or `--pager=off`: Explicitly disable pager
  - Any non-boolean value is treated as a pager command (first token) with following tokens as arguments
  **Examples:**
  - `--pager='less -R'`: Use less with raw control chars
  - `--pager="less --RAW-CONTROL-CHARS"`: Alternative syntax for less with options
  - `export ATMOS_PAGER='less -R +Gg'` or `export PAGER='less -R'`: Set via environment variables
  **Environment Variables:**
  - `NO_PAGER`: Standard CLI convention to disable pager (e.g., `NO_PAGER=1`)
  - `ATMOS_PAGER`: Atmos-specific pager configuration
  - `PAGER`: System default pager (fallback)
  **Precedence**: `--pager` flag > `NO_PAGER` > `ATMOS_PAGER` > `PAGER` > config file

  **Default**: Pager is disabled unless explicitly enabled

  **Note**: Use quotes around the value to preserve spaces and prevent shell splitting when passing pager
  arguments. The `NO_PAGER` environment variable follows the standard CLI convention for disabling pagers.
- **`--redirect-stderr`**

  Redirect stderr to a file or file descriptor.
  - Can redirect to any file path or standard file descriptor
  - Example: `--redirect-stderr=/dev/null` to suppress error output
- **`--ai`**

  Enable AI-powered analysis of command output.
  - Default: `false`
  - When enabled, command output is automatically sent to the configured AI provider for analysis
  - Requires AI configuration in `atmos.yaml` (provider, model, API key)
  - Can also use `ATMOS_AI` environment variable
  - Works with any command that produces output (e.g., `terraform plan`, `describe stacks`)
  - See [AI Configuration](/cli/configuration/ai) for setup instructions
  **Examples:**
  ```bash
  # Analyze terraform plan output with AI
  atmos terraform plan vpc -s prod --ai

  # Use environment variable
  ATMOS_AI=true atmos terraform plan vpc -s prod

  # Combine with other flags
  atmos terraform apply vpc -s prod --ai --logs-level=Debug
  ```
- **`--skill`**

  Specify one or more AI skills for domain-specific analysis context (requires `--ai`).
  - Default: empty (no skills)
  - Accepts comma-separated values (`--skill a,b`) or repeated flags (`--skill a --skill b`)
  - Loads each skill's system prompt and prepends them to the AI analysis prompt
  - The AI gains deep knowledge of the specified Atmos subsystems for more accurate analysis
  - Skills are loaded from marketplace installations (`~/.atmos/skills/`) and custom skills in `atmos.yaml`
  - Can also use `ATMOS_SKILL` environment variable (comma-separated)
  - Requires `--ai` flag — using `--skill` without `--ai` produces a helpful error
  - See [AI Skills](/cli/configuration/ai/skills) for available skills
  **Examples:**
  ```bash
  # Use Terraform expertise for plan analysis
  atmos terraform plan vpc -s prod --ai --skill atmos-terraform

  # Combine multiple skills (comma-separated)
  atmos terraform plan vpc -s prod --ai --skill atmos-terraform,atmos-stacks

  # Combine multiple skills (repeated flag)
  atmos terraform plan vpc -s prod --ai --skill atmos-terraform --skill atmos-stacks

  # Use environment variables
  ATMOS_AI=true ATMOS_SKILL=atmos-terraform,atmos-stacks atmos terraform plan vpc -s prod
  ```
- **`--version`**

  Print a minimal single-line Atmos CLI version and exit.
  - Outputs a simple `atmos &lt;version&gt;` format without styling or additional information
  - Does not perform update checks or support `--check`/`--format` flags
  - Available as a persistent flag on all commands
  - Always displays the **Atmos version**, not the version of underlying tools (Terraform, Helmfile, etc.)
  - For richer output and additional flags, use the [`atmos version`](/cli/commands/version/usage) command
  - Example: `atmos --version`
- **`--skip-hooks`**

  Bypass [lifecycle hooks](/stacks/hooks) for the current invocation
  without editing stack configuration.
  - **No value** (`--skip-hooks`): skip every hook.
  - **Comma-separated list** (`--skip-hooks=cost,security`): skip
    only the named hooks; others still run.
  - **Boolean** (`--skip-hooks=true|false`): explicit on/off.
  - Also available as `ATMOS_SKIP_HOOKS` env var (same value syntax).
  - **Per-invocation only** — does not propagate to nested commands
    or workflows.
  - Skipped hooks are logged at `INFO` level so they're visible in
    CI output.
  **Examples:**
  ```bash
  # Skip all hooks for one run (emergency rollback, debugging, etc.)
  atmos terraform apply vpc -s prod --skip-hooks

  # Skip just the cost-estimator and security scanner
  atmos terraform plan vpc -s prod --skip-hooks=cost,security

  # Set once in your shell for a debugging session
  export ATMOS_SKIP_HOOKS=true
  ```

## Command-Specific Flags

These flags are available across multiple commands but not universally:

### Authentication Flags

- **`--identity` / `-i`**

  Specify the identity to use for cloud authentication.
  - Available in: `auth`, `terraform`, `describe` commands
  - Can also use `ATMOS_IDENTITY` environment variable
  **Modes:**
  - **With identity name** (`--identity admin` or `--identity=admin`): Use the specified identity
  - **Without value** (`--identity`): Show interactive selector to choose identity
  - **With `false`** (`--identity=false`): Disable Atmos authentication and use cloud SDK defaults
  - **Omitted**: Use the default identity configured in `atmos.yaml`
  **Examples:**
  ```bash
  # Use specific identity (equals syntax recommended)
  atmos terraform plan vpc -s prod --identity=admin

  # Use specific identity (space syntax)
  atmos terraform plan vpc -s prod --identity admin

  # Interactively select identity
  atmos auth login --identity

  # Disable Atmos authentication
  atmos terraform plan vpc -s prod --identity=false
  ```
  :::tip Flag Placement Best Practice
  When using `--identity` with a value, place it **after other flags** and **before the `--` separator**:
  ```bash
  # Recommended: --identity before -- separator
  atmos terraform plan vpc -s prod --identity=admin -- -var-file=extra.tfvars

  # Also recommended: use equals syntax for clarity
  atmos auth exec --identity=admin -- terraform plan
  ```
  Using the equals syntax (`--identity=admin`) is unambiguous and works in all contexts.
  :::

### Processing Flags

- **`--process-templates`**

  Enable or disable Go template processing in Atmos manifests.
  - Default: `true`
  - Available in: `describe stacks`, `list`, `validate` commands
- **`--process-functions`**

  Enable or disable YAML function processing in Atmos manifests.
  - Default: `true`
  - Available in: `describe stacks`, `list`, `validate` commands
- **`--skip`**

  Skip processing specific Atmos functions in manifests.
  - Can be used multiple times
  - Example: `--skip=terraform.output --skip=include`
  - Available in: `describe` commands

### Output Flags

- **`--format` / `-f`**

  Specify the output format.
  - Common values: `yaml`, `json`, `table`, `csv`
  - Available in: `describe`, `list`, `validate` commands
- **`--file`**

  Write output to a file instead of stdout.
  - Available in: `describe`, `generate` commands
- **`--query` / `-q`**

  Query output using JSONPath or yq expressions.
  - Example: `--query='.components.vpc.vars'`
  - Available in: `describe` commands

### Profiling Flags

- **`--profiler-enabled`**

  Enable the pprof HTTP profiling server.
  - Default: `false`
  - When enabled, starts an HTTP server for interactive profiling
  - Can also use `ATMOS_PROFILER_ENABLED` environment variable
- **`--profiler-host`**

  Host address for the profiling server.
  - Default: `localhost`
  - Use `0.0.0.0` to allow external connections (security consideration)
  - Can also use `ATMOS_PROFILER_HOST` environment variable
- **`--profiler-port`**

  Port for the profiling server.
  - Default: `6060`
  - Can also use `ATMOS_PROFILER_PORT` environment variable
- **`--profile-file`**

  Write profiling data to the specified file (enables profiling automatically).
  - When specified, enables file-based profiling instead of server-based
  - File extension should match profile type (e.g., `.prof` for CPU, `.out` for trace)
  - Can also use `ATMOS_PROFILE_FILE` environment variable
- **`--profile-type`**

  Type of profile to collect when using `--profile-file`.
  - Options: `cpu`, `heap`, `allocs`, `goroutine`, `block`, `mutex`, `threadcreate`, `trace`
  - Default: `cpu`
  - Only used with `--profile-file`, ignored for server-based profiling
  - Can also use `ATMOS_PROFILE_TYPE` environment variable

### Performance Heatmap Flags

- **`--heatmap`**

  Display performance heatmap visualization after command execution.
  - Default: `false`
  - Shows function call counts, execution times, and performance metrics
  - Automatically tracks function execution with microsecond precision
  - Includes P95 latency calculations using High Dynamic Range histograms
  - Displays interactive TUI if terminal is available, otherwise static output
- **`--heatmap-mode`**

  Visualization mode for the performance heatmap.
  - Options: `bar`, `ascii`, `sparkline`, `table`
  - Default: `bar`
  - `bar`: Colored horizontal bar chart with function names and durations
  - `ascii`: Color-coded ASCII bars (Red >1ms, Orange >500µs, Yellow >100µs, Green \<100µs)
  - `sparkline`: Compact sparklines showing relative performance
  - `table`: Interactive table with sortable columns
  - Only used with `--heatmap` flag

## Environment Variables

All global flags can be set using environment variables. The precedence order is:

1. Command-line flags (the highest priority)
2. Environment variables
3. Configuration file (`atmos.yaml`)
4. Default values (lowest priority)

### Core Environment Variables

- **`ATMOS_CHDIR`**

  Change to the specified directory before executing any command.
  - Equivalent to the `--chdir` / `-C` flag
  - CLI flag takes precedence over this environment variable
  - Useful for CI/CD pipelines and scripting
- **`ATMOS_BASE_PATH`**
  Sets the base path for the Atmos project
- **`ATMOS_PROFILE`**

  Activate configuration profiles (comma-separated).
  - Equivalent to the `--profile` flag
  - CLI flag takes precedence over this environment variable
  - Supports multiple profiles: `ATMOS_PROFILE="developer,debug"`
  - Example: `ATMOS_PROFILE=ci atmos terraform plan vpc -s prod`
- **`ATMOS_LOGS_LEVEL`**
  Sets the logging level
- **`ATMOS_LOGS_FILE`**
  Sets the log file location
- **`ATMOS_COLOR` / `COLOR`**

  Enable or disable colored output.
  - Set to `true` to enable color (default)
  - Set to `false` to disable color
  - Both `ATMOS_COLOR` and `COLOR` are supported for maximum portability
- **`ATMOS_NO_COLOR` / `NO_COLOR`**

  Disable colored output (any non-empty value disables color).
  - `NO_COLOR` is a standard environment variable supported by many CLI tools (https://no-color.org/)
  - Maintained for portability across different systems and CI/CD environments
  - **Highest precedence**: Takes precedence over `ATMOS_FORCE_COLOR`, `CLICOLOR_FORCE`, `ATMOS_COLOR`, and `COLOR` settings
  - Overrides `--force-color` flag
  - Both `ATMOS_NO_COLOR` and `NO_COLOR` are fully supported
- **`ATMOS_FORCE_TTY`**

  Force TTY mode with sane defaults when terminal detection fails.
  - Useful for screenshot generation and documentation
  - Uses default terminal dimensions (width=120, height=40)
  - Example: `ATMOS_FORCE_TTY=true atmos describe stacks`
- **`ATMOS_FORCE_COLOR` / `CLICOLOR_FORCE`**

  Force TrueColor output even when not a TTY.
  - Both `ATMOS_FORCE_COLOR` and `CLICOLOR_FORCE` are equivalent and fully supported
  - `CLICOLOR_FORCE` is a standard environment variable (https://bixense.com/clicolors/)
  - Useful for screenshot generation and piping to color-aware tools
  - Forces 24-bit TrueColor profile regardless of terminal detection
  - **Note**: `NO_COLOR` environment variable takes precedence and will disable color even when this is set
  - Example: `ATMOS_FORCE_COLOR=true atmos describe config | bat`
  - Example: `CLICOLOR_FORCE=1 atmos terraform plan`
- **`ATMOS_PAGER` / `PAGER`**

  Configure pager settings.
  - `PAGER` is a standard Unix environment variable maintained for portability
  - Both `ATMOS_PAGER` and `PAGER` are supported to ensure compatibility across different systems
- **`ATMOS_IDENTITY`**

  Set the identity for cloud authentication.
  - Equivalent to the `--identity` / `-i` flag
  - CLI flag takes precedence over this environment variable
  - Set to `false` or `__DISABLED__` to skip Atmos authentication
  - Example: `ATMOS_IDENTITY=admin atmos terraform plan vpc -s prod`
- **`ATMOS_SKIP_HOOKS`**

  Skip [lifecycle hooks](/stacks/hooks) for the current invocation.
  - Equivalent to the `--skip-hooks` flag
  - Accepts `true` / `false` / a comma-separated list of hook names
  - CLI flag takes precedence over this environment variable
  - Per-invocation only; does not propagate to nested commands
  - Example: `ATMOS_SKIP_HOOKS=cost,security atmos terraform plan vpc -s prod`
- **`ATMOS_PROFILER_ENABLED`**
  Enable the pprof HTTP profiling server
- **`ATMOS_PROFILER_HOST`**
  Set the host address for the profiling server
- **`ATMOS_PROFILER_PORT`**
  Set the port for the profiling server
- **`ATMOS_PROFILE_FILE`**
  Set the file path for file-based profiling
- **`ATMOS_PROFILE_TYPE`**
  Set the profile type for file-based profiling (cpu, heap, allocs, goroutine, block, mutex, threadcreate, trace)
- **`ATMOS_AI`**

  Enable AI-powered analysis of command output.
  - Equivalent to the `--ai` flag
  - Set to `true` to enable AI analysis globally
  - CLI flag takes precedence over this environment variable
  - Example: `ATMOS_AI=true atmos terraform plan vpc -s prod`
- **`ATMOS_SKILL`**

  Specify one or more AI skills for domain-specific analysis context (comma-separated).
  - Equivalent to the `--skill` flag
  - Requires `ATMOS_AI=true` or `--ai` flag
  - CLI flag takes precedence over this environment variable
  - Example: `ATMOS_AI=true ATMOS_SKILL=atmos-terraform,atmos-stacks atmos terraform plan vpc -s prod`

### AI Integration Environment Variables

- **`ATMOS_AI`**

  Enable AI-powered analysis of command output.
  - Equivalent to the `--ai` flag
  - Set to `true` to enable AI analysis
  - CLI flag takes precedence over this environment variable
  - Example: `ATMOS_AI=true atmos aws security analyze -s prod`

### AI Assistant Environment Variables

- **`ANTHROPIC_API_KEY` / `ATMOS_ANTHROPIC_API_KEY`**

  API key for Anthropic Claude AI provider.
  - Both standard and Atmos-prefixed versions are supported
  - Used when `default_provider: "anthropic"` is configured
- **`OPENAI_API_KEY` / `ATMOS_OPENAI_API_KEY`**

  API key for OpenAI GPT AI provider.
  - Both standard and Atmos-prefixed versions are supported
  - Used when `default_provider: "openai"` is configured
- **`GEMINI_API_KEY` / `ATMOS_GEMINI_API_KEY`**

  API key for Google Gemini AI provider.
  - Both standard and Atmos-prefixed versions are supported
  - Used when `default_provider: "gemini"` is configured
- **`XAI_API_KEY` / `ATMOS_XAI_API_KEY`**

  API key for xAI Grok AI provider.
  - Both standard and Atmos-prefixed versions are supported
  - Used when `default_provider: "grok"` is configured
- **`ATMOS_AI_SEND_CONTEXT`**

  Control whether stack configurations are sent to AI provider for context-aware answers.
  - Options: `true` or `false`
  - Default: `false` (context not sent)
  - When `true`, stack YAML files are read and included in AI prompts
  - **Privacy Note**: Enables sending repository configuration to external AI services
  - Takes precedence over `send_context` setting in `atmos.yaml`

### XDG Base Directory Environment Variables

- **`ATMOS_XDG_CACHE_HOME` / `XDG_CACHE_HOME`**

  Override the default XDG cache directory for Atmos.
  - Default: `~/.cache` on Linux/Unix/macOS, `%LOCALAPPDATA%\cache` on Windows
  - Used for: Cache files (`cache.yaml`), auth provisioning cache
  - Example: `ATMOS_XDG_CACHE_HOME=/custom/cache atmos describe stacks`
- **`ATMOS_XDG_DATA_HOME` / `XDG_DATA_HOME`**

  Override the default XDG data directory for Atmos.
  - Default: `~/.local/share` on Linux/Unix/macOS, `%LOCALAPPDATA%` on Windows
  - Used for: File-based keyring storage
  - Example: `ATMOS_XDG_DATA_HOME=/custom/data atmos auth login`
- **`ATMOS_XDG_CONFIG_HOME` / `XDG_CONFIG_HOME`**

  Override the default XDG config directory for Atmos.
  - Default: `~/.config` on Linux/Unix/macOS, `%APPDATA%` on Windows
  - Reserved for future use
  - Example: `ATMOS_XDG_CONFIG_HOME=/custom/config`

## Portability Notes

Atmos supports both standard and Atmos-prefixed environment variables to ensure maximum portability:

- **Standard Variables** (`NO_COLOR`, `COLOR`, `PAGER`): Work across many CLI tools and Unix systems
- **Atmos Variables** (`ATMOS_NO_COLOR`, `ATMOS_COLOR`, `ATMOS_PAGER`): Provide namespace isolation when needed

This dual support ensures your scripts and CI/CD pipelines work consistently across different environments without modification.

## Examples

### Basic Usage

```bash
# Disable color and pager for CI environment
atmos describe config --no-color --pager=off

# Use specific pager with custom log level
atmos describe stacks --pager=less --logs-level=Debug

# Multiple config files with base path
atmos --base-path=/infrastructure \
      --config=base.yaml \
      --config=override.yaml \
      terraform plan vpc -s prod
```

### Directory Change Examples

```bash
# Change to infrastructure directory before running command
atmos --chdir=/path/to/infrastructure describe stacks

# Use short form (-C) for brevity
atmos -C /infra terraform plan vpc -s prod

# Relative path from current directory
atmos --chdir=../other-repo list components

# Use with other flags - chdir processes first
atmos -C /infra --base-path=./config describe component vpc -s dev

# Environment variable for scripting
export ATMOS_CHDIR=/infrastructure
atmos terraform apply vpc -s prod

# Development workflow - point dev binary at different repo
./build/atmos -C ~/projects/my-infrastructure describe stacks

# CI/CD pipeline example
cd /build
atmos --chdir=/infrastructure terraform plan vpc -s prod
```

### Pager Control Examples

```bash
# Enable pager (multiple ways)
atmos describe config --pager                # Enable with default pager
atmos describe config --pager=true           # Explicitly enable
atmos describe config --pager=less           # Use specific pager
ATMOS_PAGER=true atmos describe config      # Via environment variable

# Disable pager (explicit)
atmos describe config --pager=false          # Explicitly disable
atmos describe config --pager=off            # Alternative syntax
ATMOS_PAGER=false atmos describe config     # Via environment variable

# Disable pager using NO_PAGER (standard CLI convention)
NO_PAGER=1 atmos describe config            # Standard way to disable pager
export NO_PAGER=1; atmos describe config    # Set for entire session

# Default behavior (no flag = pager disabled)
atmos describe config                        # Pager is OFF by default
```

### Color Control Examples

```bash
# Multiple ways to disable color
atmos describe config --no-color           # Using flag
NO_COLOR=1 atmos describe config          # Using NO_COLOR standard
ATMOS_NO_COLOR=1 atmos describe config    # Using ATMOS_NO_COLOR
ATMOS_COLOR=false atmos describe config   # Using ATMOS_COLOR
COLOR=false atmos describe config         # Using COLOR

# Explicitly enable color (overrides config file setting)
ATMOS_COLOR=true atmos describe config
```

### Environment Variable Usage

```bash
# Set environment variables
export ATMOS_PAGER=off
export ATMOS_COLOR=false
export ATMOS_LOGS_LEVEL=Debug

# Commands will use these settings
atmos describe config
```

### AI-Powered Analysis Examples

```bash
# Enable AI analysis for security findings
atmos aws security analyze --ai -s prod

# Enable AI analysis via environment variable
ATMOS_AI=true atmos aws security analyze --severity=critical -s prod

# AI analysis with compliance reports
atmos aws compliance report --ai --framework=cis-aws -s prod
```

### CI/CD Configuration

```bash
# Typical CI/CD settings
export ATMOS_NO_COLOR=true
export ATMOS_PAGER=off
export ATMOS_LOGS_LEVEL=Warning
export ATMOS_LOGS_FILE=/var/log/atmos.log

# Run commands without interactive features
atmos terraform apply --auto-approve
```

### Profiling Examples

```bash
# File-based CPU profiling (default profile type)
atmos terraform plan vpc -s prod --profile-file=cpu.prof

# File-based memory heap profiling
atmos terraform plan vpc -s prod --profile-file=heap.prof --profile-type=heap

# File-based execution trace profiling
atmos terraform plan vpc -s prod --profile-file=trace.out --profile-type=trace

# Server-based profiling for interactive analysis
atmos terraform apply vpc -s prod --profiler-enabled --profiler-port=8080

# Environment variable configuration
export ATMOS_PROFILE_FILE=debug.prof
export ATMOS_PROFILE_TYPE=goroutine
atmos describe stacks

# Multiple profile types for comprehensive analysis
atmos terraform plan vpc -s prod --profile-file=cpu.prof --profile-type=cpu
atmos terraform plan vpc -s prod --profile-file=heap.prof --profile-type=heap
atmos terraform plan vpc -s prod --profile-file=trace.out --profile-type=trace
```

### AI-Powered Analysis Examples

```bash
# Analyze terraform plan output with AI
atmos terraform plan vpc -s prod --ai

# Enable AI via environment variable
export ATMOS_AI=true
atmos terraform plan vpc -s prod

# One-off AI analysis
ATMOS_AI=true atmos terraform apply vpc -s prod

# Use a skill for domain-specific analysis
atmos terraform plan vpc -s prod --ai --skill atmos-terraform

# Combine multiple skills (comma-separated)
atmos terraform plan vpc -s prod --ai --skill atmos-terraform,atmos-stacks

# Combine multiple skills (repeated flag)
atmos terraform plan vpc -s prod --ai --skill atmos-terraform --skill atmos-stacks

# Skills via environment variables
ATMOS_AI=true ATMOS_SKILL=atmos-terraform,atmos-stacks atmos terraform plan vpc -s prod
```

### CI/CD Portability Example

```bash
# These environment variables work across many tools, not just Atmos
export NO_COLOR=1        # Disables color in Atmos and other NO_COLOR-compliant tools
export ATMOS_PAGER=off  # Properly disables paging in Atmos

# Run various CLI tools - all respect the same env vars
atmos describe config
terraform plan
kubectl get pods
```

> **Note**
>
> When output is piped to another command, Atmos automatically disables color output and pager to ensure
> compatibility:
>
> ```bash
> # Color and pager automatically disabled
> atmos describe stacks | grep production
> ```

## See Also

- [CLI Configuration](/cli/configuration) - Detailed configuration file reference
- [Terminal Settings](/cli/configuration/settings/terminal) - Terminal-specific configuration options
- [Environment Variables](/cli/environment-variables) - Complete environment variable reference