Skip to main content

Pager Default Behavior Corrected

· 3 min read
atmos
atmos
atmos

We've identified and corrected a regression in Atmos where the pager was incorrectly enabled by default, contrary to the intended behavior documented in a previous release.

What Changed​

The pager is now correctly disabled by default in Atmos. This aligns with the behavior that was intended in PR #1430 (September 2025) but was not fully implemented.

Background​

In May 2025, pager support was added to Atmos with the default set to true (enabled). Later, in September 2025, PR #1430 was merged with the intention of changing this default to improve the scripting and automation experience. The PR included:

  • A global --pager flag
  • Support for the NO_PAGER environment variable
  • Documentation stating: "BREAKING CHANGE: Pager is now disabled by default"

However, the actual default value in the configuration system was never changed from true to false, causing the pager to remain enabled by default despite the documentation.

Impact​

If you've been experiencing unexpected pager behavior (output being displayed through a pager like less when you didn't expect it), this fix resolves that issue.

If your workflow relied on the pager being enabled by default, you'll need to explicitly enable it using one of these methods:

Enable Pager via Configuration​

Add to your atmos.yaml:

settings:
  terminal:
    pager: true

Enable Pager via CLI Flag​

Use the --pager flag on any command:

atmos describe component myapp -s prod --pager

Enable Pager via Environment Variable​

Set the ATMOS_PAGER or PAGER environment variable:

export ATMOS_PAGER=true
atmos describe component myapp -s prod

Or specify a custom pager:

export ATMOS_PAGER=less
atmos describe component myapp -s prod

Why This Change Matters​

Having the pager disabled by default provides several benefits:

  1. Better automation/scripting: Output can be piped and processed without unexpected pager interaction
  2. Predictable behavior: Commands behave consistently whether run interactively or in CI/CD
  3. Explicit opt-in: Users who want pagination can easily enable it per their preferences

Migration Guide​

Most users won't need to change anything. If you were relying on the pager being enabled by default:

  1. Add pager: true to your atmos.yaml settings
  2. Or use the --pager flag when you want paginated output
  3. Or set the ATMOS_PAGER environment variable in your shell profile

We apologize for any confusion this regression may have caused and thank the community for bringing it to our attention.

Introducing --chdir: Simplify Your Multi-Repo Workflows

· 6 min read
atmos
atmos
atmos

We're excited to announce a new global flag that makes working with Atmos across multiple repositories and directories significantly easier: --chdir (or -C for short).

The Problem​

If you've ever worked with Atmos in a multi-repository setup or during development, you've probably faced these scenarios:

  • Development workflow: You're building a new Atmos binary and want to test it against your infrastructure repo without installing it globally
  • CI/CD complexity: Your build runs in one directory, but your infrastructure code lives elsewhere
  • Multi-repo operations: You need to quickly check configurations across different infrastructure repositories
  • Script complexity: Your automation scripts have to change directories manually, making them harder to read and maintain

Previously, you had to either:

  • Manually cd to each directory before running Atmos
  • Write wrapper scripts to handle directory changes
  • Modify your PATH or use absolute paths to atmos binaries
  • Copy binaries to specific locations

The Solution​

The new --chdir flag (and its short form -C) changes Atmos's working directory before any other operations, including configuration loading. This mirrors the familiar behavior of tools like git -C and make -C.

Basic Usage​

# Long form
atmos --chdir=/path/to/infrastructure describe stacks

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

# Relative paths work too
atmos --chdir=../other-repo list components

Development Workflow​

Testing a development build against your infrastructure is now trivial:

# Build your changes
make build

# Point the dev binary at your infrastructure repo
./build/atmos -C ~/projects/my-infrastructure describe stacks

# No need to change directories or modify PATH
./build/atmos -C ~/projects/my-infrastructure terraform plan vpc -s dev

CI/CD Pipelines​

Your CI/CD workflows become cleaner and more explicit:

# Before: Manual directory management
cd /infrastructure
atmos terraform plan vpc -s prod
cd -

# After: Explicit and clear
atmos -C /infrastructure terraform plan vpc -s prod

Environment Variable Support​

For scripts and CI/CD environments, you can use the ATMOS_CHDIR environment variable:

export ATMOS_CHDIR=/infrastructure

# All atmos commands now run in that directory
atmos terraform plan vpc -s prod
atmos describe stacks
atmos list components

The CLI flag takes precedence over the environment variable, allowing you to override the default when needed:

export ATMOS_CHDIR=/default-infra

# Use the default
atmos describe stacks

# Override for specific command
atmos -C /other-infra describe stacks

How It Works with --base-path​

It's important to understand the difference between --chdir and --base-path:

  • --chdir: Changes the working directory (like running cd first)
  • --base-path: Overrides the Atmos project root (where atmos.yaml lives)

Processing Order​

  1. --chdir executes first, changing the working directory
  2. --base-path is then resolved relative to the new working directory
  3. All other configuration loading and operations proceed

Example​

# Change to /infra directory, then look for atmos.yaml in ./config subdirectory
atmos -C /infra --base-path=./config terraform plan vpc -s dev

# This is equivalent to:
# cd /infra
# atmos --base-path=./config terraform plan vpc -s dev

When to Use Each​

  • Use --chdir when you want Atmos to run as if you had changed directories first
  • Use --base-path when your Atmos project root is in a non-standard location
  • Combine them when your working directory and Atmos project root are in different places
# Just change working directory (atmos.yaml is in the root)
atmos -C /path/to/infra terraform plan vpc -s prod

# Just override project root (stay in current directory)
atmos --base-path=/custom/location terraform plan vpc -s prod

# Both: change directory AND override project root
atmos -C /infra --base-path=./custom terraform plan vpc -s prod

Real-World Examples​

Multi-Repo Infrastructure Management​

# Check production infrastructure
atmos -C ~/projects/prod-infra describe affected

# Compare with staging
atmos -C ~/projects/staging-infra describe affected

# All without leaving your current directory

Development and Testing​

# Test local changes against test environment
./build/atmos -C ~/infra terraform plan vpc -s test

# Once satisfied, use installed version for production
atmos -C ~/infra terraform apply vpc -s prod

Automated Scripts​

#!/bin/bash
# Script can stay in your tools repo while operating on infrastructure

INFRA_DIR="/path/to/infrastructure"

echo "Validating stacks..."
atmos -C "$INFRA_DIR" validate stacks

echo "Checking for drift..."
atmos -C "$INFRA_DIR" terraform plan vpc -s prod --detailed-exitcode

echo "Generating documentation..."
atmos -C "$INFRA_DIR" docs generate

Error Handling​

Atmos provides clear error messages when things go wrong:

  • Directory doesn't exist: Clear message with the path that was attempted
  • Path is a file, not a directory: Explicit error explaining the issue
  • Permission denied: OS-level error with context
  • Invalid path: Path resolution errors are caught and reported

Platform Compatibility​

The --chdir flag works consistently across:

  • Linux - All distributions
  • macOS - All versions
  • Windows - Native support

Both absolute and relative paths work as expected on all platforms, with proper path separator handling.

Technical Details​

For those interested in the implementation:

  • Execution order: --chdir → config loading → --base-path resolution → command execution
  • Path resolution: Relative paths are resolved from the current working directory
  • Symlinks: Symlinks to directories work correctly
  • Environment variable: ATMOS_CHDIR follows the same precedence rules as other Atmos env vars
  • Flag precedence: CLI flag > environment variable > current directory

Getting Started​

The --chdir flag is available starting in Atmos vX.X.X. To start using it:

# Upgrade to the latest version
brew upgrade atmos  # macOS
# or download from GitHub releases

# Start using the flag immediately
atmos --chdir=/your/infra describe stacks

# Or set it as an environment variable for your session
export ATMOS_CHDIR=/your/infra

Conclusion​

The --chdir flag is a small addition that makes a big difference in daily workflows. It removes friction from multi-repo operations, development workflows, and automation scripts.

We designed it to feel natural if you've used similar flags in other tools (git -C, make -C, tar -C), while integrating seamlessly with Atmos's existing flag system.

Try it out and let us know what you think! We'd love to hear how you're using it in your workflows.

Resources​

Have feedback or questions? Join our Slack community or open an issue on GitHub.