Atmos

https://github.com/cloudposse/atmos
Admin
Atmos is a framework that simplifies complex cloud architectures and DevOps workflows into intuitive...
Tokens:6,266,497
Snippets:50,453
Trust Score:10
License:Apache-2.0
Update:1 day ago
Show doc for...
Tokens:
Raw
### Getting Started in 2 Minutes

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2025-12-06-native-devcontainer-support.mdx

Install Atmos with Homebrew, navigate to your infrastructure repo, and launch the devcontainer shell. All other tools are pulled from the container image automatically.

```bash
# 1. Install Atmos (one binary)
brew install atmos

# 2. Navigate to your infrastructure repo
cd my-infrastructure

# 3. Launch your devcontainer
atmos devcontainer shell

# You're in. Start working immediately.
```

--------------------------------

### Run all setup commands with make all

Source: https://github.com/cloudposse/atmos/blob/main/website/README.md

Shortcut to run all the setup commands (brew bundle install, pnpm install, schema generation, build, and start) in one go.

```make
make all
```

--------------------------------

### Install pact-go and native libraries

Source: https://github.com/cloudposse/atmos/blob/main/specs/001-pact-consumer-contracts/quickstart.md

One-time setup for Pact consumer tests. Requires native pact libraries; installs pact-go as a dev dependency and downloads ~15 MB of native libraries. If pact-go is not on PATH after go install, add $(go env GOPATH)/bin to your shell's PATH.

```bash
# Add pact-go as a dev dependency (already in go.mod after first checkout)
go install github.com/pact-foundation/pact-go/v2@latest

# Download and install the required native libraries (~15 MB, one-time setup)
pact-go -l DEBUG install
```

--------------------------------

### Quick start: install Atmos and launch Geodesic

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2025-12-06-geodesic-production-ready-devcontainer.mdx

Shows the minimal steps to get started: install the Atmos binary with Homebrew, navigate to your infrastructure repository, and launch the Geodesic devcontainer. After launching, you can run commands like terraform plan, kubectl get pods, and helm list inside the container.

```bash
# 1. Install Atmos (one binary)
brew install atmos

# 2. Navigate to your infrastructure repo
cd my-infrastructure

# 3. Launch Geodesic
atmos devcontainer shell geodesic

# You're in. Start working.
$ atmos terraform plan vpc -s prod
$ kubectl get pods
$ helm list
```

--------------------------------

### Quick Start with Examples

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2025-12-06-native-devcontainer-support.mdx

Clone the Atmos repository and explore the devcontainer examples. The example includes a complete configuration and can be launched with the devcontainer shell.

```bash
# Clone Atmos repo (or just browse examples on GitHub)
git clone https://github.com/cloudposse/atmos.git
cd atmos/examples/devcontainer

# The example includes a complete configuration
cat atmos.yaml

# Launch it
atmos devcontainer shell
```

--------------------------------

### Multiple TryExample usage with TryExamples and labels

Source: https://github.com/cloudposse/atmos/blob/main/website/src/components/TryExample/README.md

For multiple examples in one section, wrap direct TryExample children in TryExamples and give each a short label. This renders one 'Install Atmos' tab followed by the named example tabs, preserving each project's instructions.

```mdx
import TryExample, { TryExamples } from '@site/src/components/TryExample';

## Try it out

<TryExamples>
  <TryExample example="devcontainer" label="Dev Container">
    Install Docker or Podman, then run `atmos devcontainer list`.
  </TryExample>
  <TryExample example="devcontainer-build" label="Build Geodesic">
    Follow the README to build the Geodesic development container.
  </TryExample>
</TryExamples>
```

--------------------------------

### Install all tools from .tool-versions

Source: https://github.com/cloudposse/atmos/blob/main/cmd/markdown/atmos_toolchain_install.md

Run `atmos toolchain install` to install all tools listed in the `.tool-versions` file.

```bash
 $ atmos toolchain install
```

--------------------------------

### Run development setup with atmos dev setup

Source: https://github.com/cloudposse/atmos/blob/main/docs/development.md

Initializes the development environment by installing Go dependencies, pre-commit, golangci-lint (via brew, apt, or pip), pre-commit hooks, and required Go tools. Run after cloning the repository.

```bash
atmos dev setup
```

--------------------------------

### Run the example with make all

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/tutorials/atmos-example-infra.mdx

Execute these commands in a terminal to run the example. `cd example` changes into the example directory, and `make all` builds the Docker image, builds the CLI tool inside the image, and starts the container.

```bash
cd example
```

```bash
make all
```

--------------------------------

### Start local web server with pnpm start

Source: https://github.com/cloudposse/atmos/blob/main/website/README.md

Starts the local web server for the documentation site.

```bash
pnpm start
```

--------------------------------

### Initialize Atmos project from example directory

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2026-10-08-initialize-from-examples.mdx

Initializes a complete Atmos project from the quick-start-simple example into ./my-project. The destination defaults to the source directory's name; supply a second argument to choose another destination.

```shell
atmos init examples/quick-start-simple ./my-project
```

--------------------------------

### atmos toolchain install examples

Source: https://github.com/cloudposse/atmos/blob/main/agent-skills/skills/atmos-toolchain/references/commands-reference.md

Examples of installing tools: warm/install .tool-versions for a shell or cache, ad-hoc install a specific version, or bootstrap a repo-wide default tool.

```shell
atmos toolchain install                        # Warm/install .tool-versions for a shell or cache
```

```shell
atmos toolchain install terraform@1.9.8        # Ad-hoc install a specific version
```

```shell
atmos toolchain install jq                     # Bootstrap a repo-wide default tool
```

--------------------------------

### Quick Start: Run custom commands

Source: https://github.com/cloudposse/atmos/blob/main/examples/custom-commands/README.md

Lists available custom commands and runs basic examples: hello, ip, github status, greet, and weather with a flag.

```shell
# View available custom commands
atmos --help

# Run basic commands
atmos hello
atmos ip
atmos github status
atmos greet Alice
atmos weather --location LAX

```

--------------------------------

### Examples: Start or reuse emulator

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/emulator/up.mdx

Three example invocations: start the aws emulator in the plat-ue2-dev stack, start a throwaway instance with --ephemeral, and use the emu alias.

```shell
# Start (or reuse) the aws emulator in the plat-ue2-dev stack
atmos emulator up aws --stack=plat-ue2-dev

# Start a throwaway instance that does not persist state
atmos emulator up aws --stack=plat-ue2-dev --ephemeral

# Using the emu alias
atmos emu up aws --stack=plat-ue2-dev
```

--------------------------------

### Initialize and Start Podman Machine on Windows

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/devcontainer/devcontainer.mdx

Initialize and start the Podman machine on Windows after installing Podman Desktop for Windows.

```bash
podman machine init
podman machine start
```

--------------------------------

### WithExample - Add configuration or code examples

Source: https://github.com/cloudposse/atmos/blob/main/docs/errors.md

Adds configuration or code examples displayed in a dedicated 'Example' section. Use for YAML, JSON, HCL, or code snippets that would clutter hints.

```go
builder.WithExample(`components:
  devcontainer:
    default:
      spec:
        image: "ubuntu:22.04"`)
```

--------------------------------

### Start and manage local k3s sandbox with atmos emulator

Source: https://github.com/cloudposse/atmos/blob/main/examples/emulator-k8s/README.md

Requires a container runtime (Docker or Podman). Starts the local k3s sandbox, deploys the nginx release, removes it, and stops the sandbox. The Helmfile component declares its dependencies so Atmos installs and adds them to PATH before running Helmfile.

```shell
atmos emulator up kubernetes -s local   # start the local k3s sandbox
atmos helmfile apply demo -s local       # deploy the nginx release to it

atmos helmfile destroy demo -s local     # remove the release
atmos emulator down kubernetes -s local  # stop and remove the sandbox container
```

--------------------------------

### Before: Manual Environment Setup

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2025-12-06-native-devcontainer-support.mdx

Shows the manual process of installing and managing multiple CLI tools (Terraform, AWS CLI, kubectl, Helmfile) with version conflicts and repeated setup steps. Use this as a contrast to the automated Atmos devcontainer approach.

```bash
# Install Terraform
brew install terraform
# Wait, wrong version for this project...
tfenv install 1.10.0
tfenv use 1.10.0

# Install AWS CLI
pip install awscli
# Conflicts with other Python packages...

# Install kubectl
brew install kubectl
# Different version than CI uses...

# Install Helmfile
brew install helmfile

# Repeat for every tool...
# Repeat for every team member...
# Repeat when versions change...
# Repeat when you switch projects...
```

--------------------------------

### WithExample(example string) *ErrorBuilder

Source: https://github.com/cloudposse/atmos/blob/main/docs/errors.md

Adds configuration or code examples - displayed in dedicated "Example" section.

```APIDOC
## WithExample(example string) *ErrorBuilder

### Description
Adds configuration or code examples - displayed in dedicated "Example" section.

### Method
WithExample

### Parameters
- **example** (string) - Required - The configuration or code example.

### Example
```go
builder.WithExample(`components:
  devcontainer:
    default:
      spec:
        image: "ubuntu:22.04"`)
```
```

--------------------------------

### Copy an official example without a scaffold configuration

Source: https://github.com/cloudposse/atmos/blob/main/cmd/markdown/atmos_init_usage.md

Initializes a project from an official Atmos example repository and lists the stacks. Use when you want a simple starting point without additional scaffold configuration.

```bash
$ atmos init github.com/cloudposse/atmos//examples/quick-start-simple
$ cd quick-start-simple
$ atmos list stacks
```

--------------------------------

### atmos ai skill install examples

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/ai/skill.mdx

Examples of installing skills: by name, all bundled, from GitHub, with version, force, yes, custom path, client selection, and user scope.

```shell
# Install an official skill by name (offline)
atmos ai skill install atmos-terraform

# Install every bundled skill at once (offline)
atmos ai skill install

# Install a skill from GitHub
atmos ai skill install github.com/user/skill-name

# Install a specific version
atmos ai skill install github.com/user/skill-name@v1.2.3

# Force reinstall
atmos ai skill install github.com/user/skill-name --force

# Install without confirmation
atmos ai skill install github.com/user/skill-name --yes

# Install to a custom directory (skips auto-distribution)
atmos ai skill install atmos-terraform --path .github/skills

# Distribute to a specific AI client
atmos ai skill install atmos-terraform --client vscode

# Distribute to every supported AI client
atmos ai skill install atmos-terraform --all-clients

# Distribute into each client's personal, user-level directory
atmos ai skill install atmos-terraform --scope user
```

--------------------------------

### Install pinned tools with atmos toolchain install

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2026-01-01-toolchain-management.mdx

Installs the tools pinned in the example's toolchain configuration. Requires network access for downloads.

```shell
atmos toolchain install
```

--------------------------------

### Install a third-party skill

Source: https://github.com/cloudposse/atmos/blob/main/cmd/ai/skill/markdown/atmos_ai_skill_install_usage.md

Installs a third-party skill from the GitHub repository 'yourorg/your-skill'.

```bash
$ atmos ai skill install yourorg/your-skill
```

--------------------------------

### Install tools and run toolchain demos

Source: https://github.com/cloudposse/atmos/blob/main/examples/toolchain/README.md

Commands to install tools from .tool-versions and run custom command and workflow demos. The demo commands cover implicit, pinned, constrained, and multi-tool dependency patterns.

```shell
cd examples/toolchain

# Install tools from .tool-versions
atmos toolchain install

# Run custom command demos
atmos demo which         # Implicit deps from .tool-versions
atmos demo pinned        # Exact version pinning
atmos demo constrained   # SemVer constraints
atmos demo convert       # Multi-tool pipeline

# Run workflow demos
atmos workflow which -f toolchain-demo
atmos workflow convert -f toolchain-demo
```

--------------------------------

### Initialize and run an Atmos example locally

Source: https://github.com/cloudposse/atmos/blob/main/examples/README.md

Use `atmos init` to copy an example from the official repository and then run `atmos list stacks` to see the stacks. Replace `quick-start-simple` with any example directory; the `//` separates the repository from the directory. No scaffold configuration is required; `init.repository` defaults to the official repository at `main`, and you can use `--ref` to select another revision or a second positional argument for the target directory.

```shell
atmos init github.com/cloudposse/atmos//examples/quick-start-simple
cd quick-start-simple
atmos list stacks
```

--------------------------------

### Install opentofu and tfmigrate with Homebrew

Source: https://github.com/cloudposse/atmos/blob/main/examples/hooks-tfmigrate/README.md

Optional setup for managing tools manually instead of relying on the Atmos toolchain. Installs opentofu and tfmigrate on PATH.

```bash
brew install opentofu minamijoyo/tfmigrate/tfmigrate
```

--------------------------------

### Get Started with file-scoped locals

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2025-12-17-file-scoped-locals.mdx

Minimal example showing how to define file-scoped locals and reference them in vars.

```yaml
locals:
  project: myproject
  env: dev

vars:
  name: "{{ .locals.project }}-{{ .locals.env }}"
```

--------------------------------

### Run Atmos commands to list stacks, describe component, and plan

Source: https://github.com/cloudposse/atmos/blob/main/examples/quick-start-simple/README.md

Commands to run from the example directory: list all stacks, describe the station component in dev, and plan every component in dev. No cloud credentials are required.

```shell
# List all stacks
atmos list stacks

# Describe the station component in dev
atmos describe component station -s dev

# Plan every component in dev (there is one in this minimal quick start).
atmos terraform plan --all -s dev
```

--------------------------------

### atmos devcontainer start - examples

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/devcontainer-command.md

Examples for starting devcontainers: start the default instance and start a named instance with attach.

```bash
# Start default instance
atmos devcontainer start default

# Start named instance and attach
atmos devcontainer start default --instance prod --attach
```

--------------------------------

### Basic TryExample usage with mdx

Source: https://github.com/cloudposse/atmos/blob/main/website/src/components/TryExample/README.md

Use this component in changelog posts and command documentation with an associated runnable example. Add a '## Try it out' section before closing feedback or related documentation links. In changelog posts, keep it below the '<!--truncate-->' marker. Pass the complete project path relative to 'examples/', without a leading slash or the 'examples/' prefix. Optional children appear after the initialization commands in the example tab.

```mdx
import TryExample from '@site/src/components/TryExample';

## Try it out

<TryExample example="cloudformation">

Install Docker or Podman and Python 3, then follow the example's local deployment walkthrough.

```shell
atmos validate stacks
```

</TryExample>
```

--------------------------------

### Quick start devcontainer shell commands

Source: https://github.com/cloudposse/atmos/blob/main/examples/devcontainer-build/README.md

Build and launch the devcontainer from the example directory, with an option to force rebuild using --replace.

```bash
# From this directory, build and launch the devcontainer
cd examples/devcontainer-build
atmos devcontainer shell geodesic

# Force rebuild (when Dockerfile changes)
atmos devcontainer shell geodesic --replace
```

--------------------------------

### Run the container-component example

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2026-06-23-container-components.mdx

Commands to try the 'examples/container-component' example: change into the directory, bring up the 'api' service in the 'local' stack, and list all container components. Requires Docker or Podman installed.

```shell
cd examples/container-component
atmos container up api -s local
atmos container list
```

--------------------------------

### Copy an official example and list stacks

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/init.mdx

Copies the quick-start-simple example from the atmos repository, changes into the new directory, and lists stacks to verify the initialization.

```shell
# Copy an official example, then try it.
atmos init github.com/cloudposse/atmos//examples/quick-start-simple
cd quick-start-simple
atmos list stacks
```

--------------------------------

### Install, start, and test AWS MCP servers with atmos mcp aws commands

Source: https://github.com/cloudposse/atmos/blob/main/gists/mcp-with-aws/README.md

Use these commands to install, start, and test AWS MCP servers. Install a specific server with `atmos mcp aws install pricing`, install all 21 servers with `atmos mcp aws install all`, start a server with automatic AWS auth using `atmos mcp aws start pricing`, and verify authentication with `atmos mcp aws test all`.

```bash
# Install a specific MCP server package
atmos mcp aws install pricing

# Install all 21 AWS MCP server packages
atmos mcp aws install all

# Start a specific server with automatic AWS auth
atmos mcp aws start pricing

# Test that authentication is working
atmos mcp aws test all
```

--------------------------------

### Examples: Start, attach, instance, and custom runtime

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/devcontainer/start.mdx

Provides common usage examples for the atmos devcontainer start command. Use --attach to open an interactive shell immediately, --instance to run multiple instances of the same configuration, and set ATMOS_CONTAINER_RUNTIME to use a different container runtime like podman.

```shell
# Start a devcontainer
atmos devcontainer start geodesic
```

```shell
# Start and immediately attach
atmos devcontainer start geodesic --attach
```

```shell
# Start a specific instance
atmos devcontainer start terraform --instance project-a
```

```shell
# Start with custom runtime (via environment variable)
export ATMOS_CONTAINER_RUNTIME=podman
atmos devcontainer start geodesic
```

--------------------------------

### atmos mcp install examples

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/mcp/install.mdx

Example invocations covering default detection, explicit client selection, user scope, the --global alias, and dry-run preview. Use --dry-run to verify which file would be written before making changes.

```shell
# Install all configured MCP servers into detected project clients.
atmos mcp install

# Install one server into Cursor and Claude Code project configs.
atmos mcp install aws-docs --client cursor --client claude-code

# Install into user-level config.
atmos mcp install --scope user --client codex

# Alias for --scope user.
atmos mcp install --global --client claude-code

# Preview what would be installed without writing files.
atmos mcp install --dry-run
```

--------------------------------

### Getting started with PR artifact installation

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2026-02-17-pr-artifact-installation.mdx

Authenticate with GitHub CLI and test a PR or commit. Requires GitHub authentication via ATMOS_GITHUB_TOKEN, GITHUB_TOKEN, or gh CLI.

```bash
# Authenticate with GitHub CLI (if not already)
gh auth login

# Test a PR
atmos --use-version pr:2040 version

# Test a specific commit
atmos --use-version sha:ceb7526 version
```

--------------------------------

### Fresh Installation Scenario (No .tool-versions)

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/toolchain-implementation.md

Test a fresh installation without an existing `.tool-versions` file. Run `atmos toolchain list` to see an onboarding message, then add a tool, install, and execute.

```bash
cd /tmp/test-toolchain
rm -rf .tool-versions .tools
atmos toolchain list  # Should show helpful onboarding message
atmos toolchain add terraform@1.9.8  # Creates .tool-versions
atmos toolchain install
atmos toolchain exec terraform -- version
```

--------------------------------

### Installing k9s (Kubernetes CLI Dashboard)

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/toolchain-implementation.md

Search for k9s in the registry, get available versions, view tool information, add to `.tool-versions`, or install directly. Verify installation with `atmos toolchain which` and `atmos toolchain exec`.

```bash
# Search for k9s in the registry
atmos toolchain registry search k9s

# Get available versions
atmos toolchain get k9s
atmos toolchain get derailed/k9s --all --limit 10

# View tool information
atmos toolchain info k9s

# Add to .tool-versions
atmos toolchain add k9s@0.32.7

# Or install directly without adding to .tool-versions
atmos toolchain install k9s@0.32.7
atmos toolchain install derailed/k9s@0.32.7  # Using full owner/repo format

# Verify installation
atmos toolchain which k9s
atmos toolchain exec k9s -- version

# List to confirm status
atmos toolchain list
```

--------------------------------

### Run Atmos policy validation and tests

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2026-10-20-try-runnable-examples.mdx

Quick start commands to validate the local policy bundle and run its offline fixtures. No Terraform installation or cloud credentials are required.

```shell
atmos policy check
atmos policy test tests/cases.json
```

--------------------------------

### Verify: Build and run all tests

Source: https://github.com/cloudposse/atmos/blob/main/specs/003-fix-upload-component-name/quickstart.md

Run the full verification suite after applying the fix. All tests should pass, including the previously failing ones and the unchanged Pact tests.

```bash
go build ./...
go test ./internal/exec/ -run 'TestUploadStatus' -v      # now PASS
go test ./cmd/terraform/ -run 'ExecMetadata' -v          # now PASS
go test ./pkg/pro/ -run 'Pact' -v                        # unchanged, PASS
atmos test                                               # short suite
atmos lint --changed
atmos test --full                                        # before opening the PR
```

--------------------------------

### atmos config get logs.level example

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/config/config-get.mdx

Reads the logging level from the example CLI configuration.

```shell
atmos config get logs.level
```

--------------------------------

### Run Atmos example hello

Source: https://github.com/cloudposse/atmos/blob/main/website/blog/2026-06-23-native-container-steps.mdx

Run the Atmos example hello command. Requires Docker or Podman to be installed before running the container step.

```shell
atmos example hello
```

--------------------------------

### Provision CLI command usage examples

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/provisioner-system.md

Shows the basic syntax for the atmos provision command and three concrete examples for backend, component, and network provisioner types.

```bash
# Provision resources explicitly
atmos provision <provisioner-type> <component> --stack <stack>

# Examples
atmos provision backend vpc --stack dev
atmos provision component app --stack prod
atmos provision network vpc --stack test
```

--------------------------------

### Example: List all configured servers with sample output

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/mcp/list.mdx

Shows the command to list all configured servers and an example of the expected output table with server names, statuses, and descriptions.

```shell
# List all configured servers
atmos mcp list

# Example output:
# NAME              STATUS    DESCRIPTION
# aws-docs          stopped   AWS Documentation — search and fetch AWS docs
# aws-knowledge     stopped   AWS Knowledge — managed AWS knowledge base (remote)
# aws-pricing       stopped   AWS Pricing — real-time pricing and cost analysis
# aws-api           stopped   AWS API — direct AWS CLI access with security controls
# aws-security      stopped   AWS Security — Well-Architected security posture assessment
```

--------------------------------

### Install CLI provider and start AI chat

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/configuration/ai/index.mdx

Installs the `claude-code` CLI via Homebrew, authenticates with `claude auth login`, and starts the AI chat session. This is the CLI provider quick start that does not require an API key.

```bash
brew install --cask claude-code && claude auth login
atmos ai chat

```

--------------------------------

### Change to the example directory

Source: https://github.com/cloudposse/atmos/blob/main/examples/hooks-tfmigrate/README.md

Start in the example directory before running the Atmos commands.

```bash
cd examples/hooks-tfmigrate
```

--------------------------------

### Run Atmos from container instead of install step

Source: https://github.com/cloudposse/atmos/blob/main/agent-skills/skills/atmos-migration/references/to-native-ci.md

Replace any Atmos installation step (e.g., cloudposse/github-action-setup-atmos, mise, aqua, Homebrew, curl) with a job-level container using ghcr.io/cloudposse/atmos. Pin ATMOS_VERSION via a repository or organization variable; avoid 'latest' in CI. This container is the base for all other examples in this reference.

```yaml
jobs:
  plan:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}

```

--------------------------------

### Run the deploy-all workflow with atmos workflow

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/tutorials/atmos-getting-started.mdx

Invokes the `deploy-all` workflow defined in `example.yaml` for the `example` stack. Executes sequential `init`, `plan`, and `apply` for each component in the workflow.

```bash
atmos workflow deploy-all -f example.yaml -s example

```

--------------------------------

### Apply Helm release

Source: https://github.com/cloudposse/atmos/blob/main/examples/helm/README.md

Installs or upgrades the release on the current kubecontext with `atmos helm apply`. The second option starts the local K3s emulator used by the CI smoke test and applies with the `local-k3s` identity.

```shell
# Install/upgrade the release on the current kubecontext.
atmos helm apply demo -s dev

# Or deploy directly to the local K3s emulator used by the CI smoke test.
atmos emulator up kubernetes -s dev
atmos helm apply demo -s dev --identity local-k3s
```

--------------------------------

### Custom Dockerfile additions

Source: https://github.com/cloudposse/atmos/blob/main/examples/devcontainer-build/README.md

Example Dockerfile additions to install tools, add shell configuration, and install VS Code extensions.

```dockerfile
# Install additional tools
RUN apk add --no-cache \
    terraform \
    kubectl \
    helm

# Add custom shell configuration
COPY .bashrc /root/.bashrc

# Install VS Code extensions (if using VS Code)
RUN code-server --install-extension hashicorp.terraform
```

--------------------------------

### Example output for basic search

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/toolchain/registry/search.mdx

Example output showing matching tools with installation status indicators. The ● symbol indicates installed tools, while blank indicates available (not installed) tools.

```text
Found 15 tools matching 'terraform':

  ┌───┬──────────────┬────────────┬───────────────┐
  │   │ OWNER        │ REPO       │ TYPE          │
  ├───┼──────────────┼────────────┼───────────────┤
  │ ● │ hashicorp    │ terraform  │ github_release│
  │ ● │ opentofu     │ opentofu   │ github_release│
  │   │ gruntwork-io │ terragrunt │ github_release│
  └───┴──────────────┴────────────┴───────────────┘
```

--------------------------------

### ExecuteAbout Help/Documentation

Source: https://github.com/cloudposse/atmos/blob/main/docs/io-and-ui-output.md

Renders Markdown help content via ui.Markdown. One line, renders beautifully, and degrades gracefully when piped.

```go
func ExecuteAbout(cmd *cobra.Command, args []string) error {
    return ui.Markdown(markdown.AboutMarkdown)
}
```

--------------------------------

### Run the whole round trip in one step

Source: https://github.com/cloudposse/atmos/blob/main/examples/demo-helmfile/README.md

Runs the full Helmfile demo lifecycle (emulator up, deploy, status, cleanup) with a single command.

```shell
atmos test

```

--------------------------------

### Install Node.js dependencies with pnpm install

Source: https://github.com/cloudposse/atmos/blob/main/website/README.md

Installs Node.js dependencies using pnpm. Requires pnpm to be installed.

```bash
pnpm install
```

--------------------------------

### atmos stack get examples

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/stack/stack-get.mdx

Two example invocations reading vars.region and settings.spacelift.workspace_enabled from the plat-ue2-prod stack for the vpc component.

```shell
atmos stack get vars.region -s plat-ue2-prod -c vpc
```

```shell
atmos stack get settings.spacelift.workspace_enabled -s plat-ue2-prod -c vpc
```

--------------------------------

### Run the custom command

Source: https://github.com/cloudposse/atmos/blob/main/examples/custom-components/README.md

Executes the custom 'example' command for the 'deploy-app' component on the 'dev' stack.

```bash
cd examples/custom-components
atmos example deploy-app --stack dev
```

--------------------------------

### atmos ai skill list examples

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/ai/skill.mdx

Examples of listing skills: all skills, only installed ones, and detailed information. The `--installed` flag filters to installed skills; `--detailed` shows extra info.

```shell
# List all skills (available and installed)
atmos ai skill list

# Show only installed skills
atmos ai skill list --installed

# Show detailed information
atmos ai skill list --detailed
```

--------------------------------

### Start the default devcontainer

Source: https://github.com/cloudposse/atmos/blob/main/cmd/markdown/atmos_devcontainer_start_usage.md

Starts the default devcontainer instance using the atmos CLI.

```bash
$ atmos devcontainer start default
```

--------------------------------

### Run demo workflows with atmos workflow commands

Source: https://github.com/cloudposse/atmos/blob/main/examples/demo-workflows/README.md

Change into the examples/demo-workflows directory, list available workflows with `atmos workflow list`, and run the `deploy` workflow for the `dev` stack with `atmos workflow deploy -s dev`.

```shell
cd examples/demo-workflows

# List available workflows
atmos workflow list

# Run a workflow
atmos workflow deploy -s dev
```

--------------------------------

### Initialize and enter the policies example directory

Source: https://github.com/cloudposse/atmos/blob/main/examples/policies/README.md

Run `atmos init examples/policies` to create the example directory, then change into it. Atmos automatically discovers the included `policy.d/` directory unless `ATMOS_POLICY_DIR` overrides discovery.

```shell
atmos init examples/policies
cd policies
```

--------------------------------

### Install a specific tool version

Source: https://github.com/cloudposse/atmos/blob/main/cmd/markdown/atmos_toolchain_install.md

Use `atmos toolchain install <tool>@<version>` to install a specific version of a tool.

```bash
 $ atmos toolchain install <tool>@<version>
```

--------------------------------

### Development/Testing: Memory Backend Setup

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/keyring-backends.md

Use the memory backend for fast testing by setting ATMOS_KEYRING_TYPE to memory, then run tests with go test.

```bash
# Use memory backend for fast testing
export ATMOS_KEYRING_TYPE=memory

# Run tests
go test ./...
```

--------------------------------

### Try It commands

Source: https://github.com/cloudposse/atmos/blob/main/examples/remote-stack-imports/README.md

Commands to view the stack configuration and describe the component from the example directory.

```bash
cd examples/remote-stack-imports

# View the stack configuration (includes remote imports)
atmos describe stacks

# Describe the component
atmos describe component myapp -s demo
```

--------------------------------

### Start and attach to the devcontainer

Source: https://github.com/cloudposse/atmos/blob/main/cmd/markdown/atmos_devcontainer_start_usage.md

Starts the default devcontainer and attaches to it using the --attach flag.

```bash
$ atmos devcontainer start default --attach
```

--------------------------------

### Run the cloudposse/tutorials Docker image

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/tutorials/atmos-getting-started.mdx

Runs the tutorials Docker image with the home directory and current directory mounted. The container is named sweetops-tutorials and is removed after exit.

```bash
# Run our docker image
docker run -it \
          --rm \
          --volume "$HOME":/localhost \
          --volume "$PWD":/tutorials \
          --name sweetops-tutorials \
          cloudposse/tutorials:latest;
```

--------------------------------

### Install dependencies with brew bundle install

Source: https://github.com/cloudposse/atmos/blob/main/website/README.md

Installs dependencies listed in the Brewfile. Run from the website directory.

```bash
brew bundle install
```

--------------------------------

### atmos lsp start examples

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/lsp/start.mdx

Examples of starting the LSP server with different transport protocols: stdio (default), TCP, and WebSocket. The --transport flag selects the protocol, and --address sets the host:port for tcp/websocket (default localhost:7777).

```shell
# Start LSP server with stdio transport (default, for IDE integration)
atmos lsp start
```

```shell
# Start LSP server with TCP transport
atmos lsp start --transport=tcp
```

```shell
# Start LSP server with TCP on a custom address
atmos lsp start --transport=tcp --address=localhost:9999
```

```shell
# Start LSP server with WebSocket transport
atmos lsp start --transport=websocket --address=localhost:8080
```

--------------------------------

### Run atmos describe commands to inspect inheritance

Source: https://github.com/cloudposse/atmos/blob/main/examples/demo-stacks/README.md

Commands to run from the examples/demo-stacks directory. Use --query to focus on the vars section and --sections to compare resolved configuration across environments. Drop --query/--sections to see the full resolved configuration including imports, inheritance chain, and deps.

```shell
cd examples/demo-stacks

# See how configuration is inherited (--query focuses on the vars section)
atmos describe component myapp -s dev --query .vars
atmos describe component myapp -s prod --query .vars

# Compare the resolved configuration across environments
atmos describe stacks --components myapp --sections vars
```

--------------------------------

### atmos config get examples

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/config/config-get.mdx

Provides multiple examples of reading configuration values, including specifying custom config files with the --config flag.

```shell
atmos config get logs.level
atmos config get components.terraform.base_path
atmos config get logs.level --config ./atmos.yaml
atmos config get stacks.included_paths --config ./main.yaml,./overrides.yaml
```

--------------------------------

### Select an example revision using the official examples alias

Source: https://github.com/cloudposse/atmos/blob/main/cmd/markdown/atmos_init_usage.md

Initializes from the official examples alias at a specific Git ref. Use --ref to pin the revision.

```bash
$ atmos init examples/quick-start-simple --ref main
```

--------------------------------

### Install golangci-lint using installer

Source: https://github.com/cloudposse/atmos/blob/main/docs/development.md

Alternative method to install golangci-lint using the official installer script, placing the binary in the Go bin directory.

```bash
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
```

--------------------------------

### Clone the Atmos advanced quick-start example repository

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/quick-start/advanced/advanced.mdx

Clones the Atmos repository and changes into the advanced quick-start example directory. Requires Git and network access.

```bash
git clone https://github.com/cloudposse/atmos.git
cd atmos/examples/quick-start-advanced
```

--------------------------------

### Run Atmos commands for Ansible example

Source: https://github.com/cloudposse/atmos/blob/main/examples/demo-ansible/README.md

Commands to list stacks, describe the hello-world component in dev, and run the Ansible playbook in dev and prod environments. Run from the examples/demo-ansible directory.

```shell
cd examples/demo-ansible

# List all stacks
atmos list stacks

# Describe the hello-world component in dev
atmos describe component hello-world -s dev

# Run the playbook in dev
atmos ansible playbook hello-world -s dev

# Run the playbook in prod (different vars)
atmos ansible playbook hello-world -s prod

```

--------------------------------

### Complete workflow example with interactive steps

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/workflow-step-types.md

Shows a full Atmos workflow configuration using various step types (markdown, choose, filter, info, confirm, spin, atmos, shell) with output modes and Go template variable references. Demonstrates the proposed configuration for interactive deployments.

```yaml
# stacks/workflows/deploy.yaml
workflows:
  interactive-deploy:
    description: "Interactive deployment workflow with prompts and status messages"
    output: log  # Default output mode for command steps
    steps:
      # Show welcome message with markdown
      - name: welcome
        type: markdown
        content: |
          # Deployment Workflow

          This workflow will guide you through deploying infrastructure.

      # Interactive: Select environment
      - name: select_env
        type: choose
        prompt: "Select target environment"
        options:
          - development
          - staging
          - production
        default: development

      # Interactive: Select component with fuzzy filter
      - name: select_component
        type: filter
        prompt: "Select component to deploy"
        options:
          - vpc
          - eks
          - rds
          - s3-bucket
          - cloudfront

      # UI Message: Show summary
      - name: summary
        type: info
        content: "Deploying {{ .steps.select_component.value }} to {{ .steps.select_env.value }}"

      # Interactive: Confirm before proceeding
      - name: confirm_deploy
        type: confirm
        prompt: "Proceed with deployment?"

      # Output: Spinner while running command
      - name: plan
        type: spin
        title: "Running terraform plan..."
        command: atmos terraform plan {{ .steps.select_component.value }} -s {{ .steps.select_env.value }}

      # Command: Apply with viewport output
      - name: apply
        type: atmos
        command: terraform apply {{ .steps.select_component.value }} -s {{ .steps.select_env.value }} -auto-approve
        output: viewport

      # UI Message: Success
      - name: complete
        type: success
        content: "Deployment of {{ .steps.select_component.value }} completed!"

      # Shell command with environment variables from previous steps
      - name: notify
        type: shell
        command: |
          curl -X POST "$WEBHOOK_URL" \
            -d "component=$COMPONENT&env=$DEPLOY_ENV"
        env:
          COMPONENT: "{{ .steps.select_component.value }}"
          DEPLOY_ENV: "{{ .steps.select_env.value }}"
          WEBHOOK_URL: "https://hooks.example.com/deploy"
```

--------------------------------

### Install with a specific version

Source: https://github.com/cloudposse/atmos/blob/main/cmd/ai/skill/markdown/atmos_ai_skill_install_usage.md

Installs the skill from the GitHub repository 'cloudposse/atmos' at version v1.200.0.

```bash
$ atmos ai skill install cloudposse/atmos@v1.200.0
```

--------------------------------

### Hardcoded stack name example

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/functions/template/atmos.Component.mdx

Example of using a hardcoded stack name to get an output from a component in a different, well-known stack. Here, the 'tgw' component in 'plat-ue2-dev' gets the 'vpc_id' output from the 'vpc' component in 'plat-ue2-prod'.

```yaml
  components:
    terraform:
      tgw:
        vars:
          vpc_id: '{{ (atmos.Component "vpc" "plat-ue2-prod").outputs.vpc_id }}'
```

--------------------------------

### Automatic Download Configuration Example

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/saml-browser-driver-integration.md

Markdown documentation snippet showing how to configure Atmos to automatically download browser drivers on first use.

```markdown
## SAML Browser Driver Installation

### Recommended: Automatic Download

Configure Atmos to automatically download browser drivers on first use:

yaml
auth:
  providers:
    my-saml:
      download_browser_driver: true

Atmos will download the Chromium browser driver (~140 MB) to your system's cache directory on first SAML authentication. No PATH configuration needed.
```

--------------------------------

### Install Docker Desktop via Homebrew on macOS

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/devcontainer/devcontainer.mdx

Install Docker Desktop for Mac using Homebrew. After installation, start Docker Desktop from Applications or Launchpad.

```bash
# Or via Homebrew
brew install --cask docker
```

--------------------------------

### Configuration example for list output

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/list-commands-configurable-output.md

Shows how to configure `list` sections for `components`, `stacks`, `workflows`, and `vendor` in `atmos.yaml`. Includes column definitions with templates and sorting options.

```yaml
# atmos.yaml
components:
  list:
    format: table
    columns:
      - name: Component
        value: '{{ .atmos_component }}'
        width: 30
      - name: Type
        value: '{{ .atmos_component_type }}'
      - name: Stack
        value: '{{ .atmos_stack }}'
        width: 25
      - name: Region
        value: '{{ .vars.region }}'
      - name: Enabled
        value: '{{ ternary .enabled "✓" "✗" }}'
      - name: Locked
        value: '{{ ternary .locked "🔒" "" }}'
    sort:
      - column: Stack
        order: asc
      - column: Component
        order: asc

stacks:
  list:
    columns:
      - name: Stack
        value: '{{ .stack }}'
      - name: Terraform Components
        value: '{{ len .components.terraform }}'
      - name: Helmfile Components
        value: '{{ len .components.helmfile }}'

workflows:
  list:
    columns:
      - name: File
        value: '{{ .file }}'
      - name: Workflow
        value: '{{ .name }}'
      - name: Description
        value: '{{ .description }}'

vendor:
  list:
    columns:
      - name: Component
        value: '{{ .atmos_component }}'
      - name: Type
        value: '{{ .atmos_vendor_type }}'
      - name: Manifest
        value: '{{ .atmos_vendor_file }}'
      - name: Folder
        value: '{{ .atmos_vendor_target }}'
```

--------------------------------

### Variable system example with step output references

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/workflow-step-types.md

Illustrates how step outputs are captured and referenced via Go templates using the step's name as key. Shows usage in prompts, command arguments, and environment variables for shell commands.

```yaml
steps:
  - name: select_env
    type: choose
    prompt: "Select environment"
    options: [staging, production]

  # Reference previous step output in templates
  - name: confirm
    type: confirm
    prompt: "Deploy to {{ .steps.select_env.value }}?"

  # Use in command arguments
  - name: deploy
    type: atmos
    command: terraform apply vpc -s {{ .steps.select_env.value }}

  # Export to environment variables for shell commands
  - name: notify
    type: shell
    command: echo "Deployed to $DEPLOY_ENV"
    env:
      DEPLOY_ENV: "{{ .steps.select_env.value }}"
```

--------------------------------

### Force reinstall (overwrite existing installation)

Source: https://github.com/cloudposse/atmos/blob/main/cmd/ai/skill/markdown/atmos_ai_skill_install_usage.md

Forces reinstallation, overwriting any existing installation of the skill.

```bash
$ atmos ai skill install cloudposse/atmos --force
```

--------------------------------

### Fetch a custom repository with full Git history

Source: https://github.com/cloudposse/atmos/blob/main/cmd/markdown/atmos_init_usage.md

Fetches a custom repository with full Git history. Use --depth 0 to disable shallow cloning.

```bash
$ atmos init github.com/example/project//starter --depth 0
```

--------------------------------

### Example ATMOS.md Project Instructions

Source: https://github.com/cloudposse/atmos/blob/main/docs/prd/atmos-ai.md

Markdown template for project instructions including context and common commands.

```markdown
# Atmos Project Instructions

## Project Context

**Organization:** acme-corp
**Environments:** dev, staging, prod
**Primary Regions:** us-east-1, us-west-2

**Stack Naming:** {org}-{env}-{region}-{stage}

## Common Commands

### Deploy VPC
```bash
atmos terraform plan vpc -s acme-prod-use1-network
atmos terraform apply vpc -s acme-prod-use1-network
```
```

--------------------------------

### Reference current stack example

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/functions/template/atmos.Component.mdx

Example of using .stack to get an output from a component in the same stack as the current component.

```yaml
  components:
    terraform:
      tgw:
        vars:
          vpc_id: '{{ (atmos.Component "vpc" .stack).outputs.vpc_id }}'
```

--------------------------------

### Manual steps for atmos gitops up

Source: https://github.com/cloudposse/atmos/blob/main/examples/local-gitops/README.md

These commands replicate what `atmos gitops up` does, letting you watch each stage. They start the Gitea and k3s emulators, install Flux, and push the demo app manifests to Gitea.

```shell
# 1. Start the Git server emulator (Gitea bootstraps admin + `deployments` repo)
atmos emulator up gitserver -s local

# 2. Start the Kubernetes emulator (k3s)
atmos emulator up kubernetes -s local

# 3. Install Flux into the cluster, then point it at the local Gitea repository.
#    The flux component pulls its install manifest just-in-time from the pinned
#    Flux release (via its `source:` field) the first time it is applied.
atmos kubernetes apply flux -s local --identity local-k3s
atmos kubernetes apply flux-sync -s local --identity local-k3s

# 4. Render the demo app's manifests and PUSH them to Gitea (no cluster contact)
atmos kubernetes apply demo-app -s local --target deployments
```

--------------------------------

### Install and Verify LSP Servers

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/ai/troubleshooting.mdx

Install yaml-language-server and terraform-ls, then verify their versions.

```bash
npm install -g yaml-language-server && yaml-language-server --version
brew install terraform-ls && terraform-ls version
```

--------------------------------

### MCP Server Integration Examples

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/ai/exec.mdx

Shows how to use `atmos ai exec` with MCP servers, including auto-routing, specifying servers directly, and using an environment variable.

```bash
# Auto-routing selects the right server
atmos ai exec "Check security posture in us-east-1" --format json

# Specify servers directly
atmos ai exec --mcp aws-iam "List all admin roles" --format json
atmos ai exec --mcp aws-security,aws-iam "Audit our security posture" --format markdown

# Environment variable
ATMOS_AI_MCP=aws-billing atmos ai exec "Monthly cost report" --format json > costs.json
```

--------------------------------

### Examples: install all, specific hooks, and force overwrite

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/git/hooks/install.mdx

Common invocations: install all configured hooks, install only specific hooks, and overwrite existing hooks with --force.

```shell
# Install all hooks configured under git.hooks
atmos git hooks install

# Install only specific hooks
atmos git hooks install pre-commit commit-msg

# Overwrite existing hooks
atmos git hooks install --force

```

--------------------------------

### atmos packer init usage examples

Source: https://github.com/cloudposse/atmos/blob/main/agent-skills/skills/atmos-packer/SKILL.md

Shows basic init, init with a specific template file using `--template`, and init with shorthand flags `-t`.

```shell
# Basic init
atmos packer init aws/bastion --stack nonprod

# Init with a specific template file
atmos packer init aws/bastion -s prod --template main.pkr.hcl

# Init with shorthand flags
atmos packer init aws/bastion -s nonprod -t main.nonprod.pkr.hcl

```

--------------------------------

### Install Podman on macOS via Homebrew

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/devcontainer/devcontainer.mdx

Install Podman using Homebrew. Optionally install Podman Desktop for GUI management. Then initialize and start the Podman machine.

```bash
brew install podman
```

```bash
podman machine init
podman machine start
```

--------------------------------

### atmos ai chat examples

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/cli/commands/ai/chat.mdx

Examples of starting anonymous, named, and resuming sessions, and using specific MCP servers.

```shell
# Start anonymous session (auto-generated name)
atmos ai chat

# Start or resume named session
atmos ai chat --session vpc-refactor

# Resume existing session
atmos ai chat --session my-session

# Start with specific MCP servers
atmos ai chat --mcp aws-billing
atmos ai chat --mcp aws-iam,aws-security
```

--------------------------------

### Run the myapp script

Source: https://github.com/cloudposse/atmos/blob/main/website/docs/automation/automation.mdx

Make the script executable and run it with an argument. Output is `Hello, platform!`.

```shell
chmod +x myapp
./myapp platform
```

--------------------------------

### Skip confirmation prompt

Source: https://github.com/cloudposse/atmos/blob/main/cmd/ai/skill/markdown/atmos_ai_skill_install_usage.md

Skips the confirmation prompt during installation.

```bash
$ atmos ai skill install cloudposse/atmos --yes
```

--------------------------------

### Install every bundled skill at once (offline)

Source: https://github.com/cloudposse/atmos/blob/main/cmd/ai/skill/markdown/atmos_ai_skill_install_usage.md

Installs all skills bundled with Atmos from the embedded catalog without network access.

```bash
$ atmos ai skill install
```
Tokens:
Raw