Custom Commands

Atmos can be extended to support any number of custom CLI commands. Custom commands are exposed through the atmos CLI and appear in atmos help. They are a great way to centralize how operational tools are run and improve developer experience.

One great way to use custom commands is to tie all your miscellaneous scripts into one consistent CLI interface. Then you can kiss those ugly, inconsistent arguments to bash scripts goodbye — just wire up the commands in atmos to call the script. Developers can then run atmos help and discover every available command.

Simple Example

Adding the following to atmos.yaml introduces a new hello command:

# Custom CLI commands
commands:
  - name: hello
    description: This command says Hello world
    steps:
      - "echo Hello world!"

Run it like this:

atmos hello

The commands section

commands is a list of command objects. Each entry defines one custom command (which can itself contain nested commands for subcommands). See the command reference for every key a command supports.

commands:
  - name: hello
    description: This command says Hello world
    steps:
      - "echo Hello world!"
  - name: greet
    description: This command greets the provided name
    arguments:
      - name: name
        description: Name to greet
        default: John Doe
    steps:
      - "echo Hello {{ .Arguments.name }}!"

Reference

command

The structure of a single custom command and all of its keys.

arguments

Positional arguments, including trailing arguments and typed (component/stack) arguments.

flags

Long and short flags, boolean flags, defaults, and semantic types.

env

Environment variables exported to the command's steps.

steps

What the command runs. Custom commands support the same step types as workflows.

component

Custom component types that bring stack configuration into a command.

dependencies

Tool dependencies installed via the toolchain before the command runs.

working_directory

The directory the command's steps execute in.

identity

Authenticate an Atmos auth identity before the command runs.

commands

Nested subcommands for grouping related commands.

Try It

Explore working examples that demonstrate custom commands in action.

custom-commandsView full example

Custom Commands

This example demonstrates how to extend Atmos with custom CLI commands, making it easier for teams to use your toolchain through a single, consistent interface.

Quick Start

# View available custom commands
atmos --help

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

Example Structure

custom-commands/ ├── atmos.yaml # Basic custom commands ├── .atmos.d/ │ ├── interactive.yaml # Interactive step types (choose, confirm, input, etc.) │ └── advanced.yaml # Boolean flags, component config, working directory └── README.md

Basic Commands (atmos.yaml)

Hello World

The simplest custom command:

atmos hello

Get Your IP

Returns your current public IP address:

atmos ip

Nested Commands (GitHub)

Commands can be nested under parent commands:

# Check GitHub status
atmos github status

# Get stargazer count for a repository
atmos github stargazers cloudposse/atmos

Positional Arguments

Pass arguments to commands:

# Uses default "John Doe"
atmos greet

# Pass a custom name
atmos greet Alice

Flags

Use long or short flags:

atmos weather --location LAX
atmos weather -l NYC

Interactive Commands (.atmos.d/interactive.yaml)

Interactive commands create CLI wizards using various step types.

Note: Interactive commands require a TTY (terminal) and won't work in CI/CD pipelines.

Deploy Wizard

Interactive deployment with environment selection and confirmation:

atmos deploy-wizard

Component Selection

Multi-select components with filtering:

atmos select-components

Create Ticket

Collect information with various input types:

atmos create-ticket

Collect Credentials

Secure credential collection with password masking:

atmos collect-credentials

File Selection

Interactive file picker:

atmos select-config

Show Environments

Display data in a formatted table:

atmos show-environments

Build with Progress

Show progress spinner during command execution:

atmos build-with-progress

Advanced Commands (.atmos.d/advanced.yaml)

Boolean Flags

Commands with boolean flags and conditional execution:

# Default behavior (clean=true, verbose=false)
atmos build

# Enable verbose output
atmos build --verbose
# or
atmos build -v

# Disable clean step
atmos build --clean=false

# Dry run mode
atmos build --dry-run

Environment Variables

Commands that set environment variables:

atmos deploy-component vpc -s dev
atmos deploy-component eks -s prod --auto-approve

Component Configuration

Access component configuration in command steps:

# Requires stacks to be configured
atmos show-component vpc -s dev

Working Directory

Run commands from specific directories:

# Run from repository root
atmos run-from-root

Nested Subcommands

Multiple levels of command nesting:

atmos ops status
atmos ops health --verbose
atmos ops restart my-service --force

Trailing Arguments

Pass additional arguments after --:

atmos run myscript.sh -- --arg1 value1 --arg2 value2

Configuration Structure

Custom commands are defined in the commands section of atmos.yaml or any file in .atmos.d/:

commands:
  - name: my-command
    description: Description shown in help
    arguments:
      - name: arg-name
        description: Argument description
        required: true
        default: default-value
    flags:
      - name: flag-name
        shorthand: f
        description: Flag description
        type: bool  # or string (default)
        default: false
    env:
      - key: MY_VAR
        value: "{{ .Arguments.arg-name }}"
    steps:
      - echo "Running command"
      - "{{ if .Flags.flag-name }}echo 'Flag enabled'{{ end }}"

Available Step Types

Custom commands support various step types for building interactive CLIs:

Type	Description
Shell command (string)	Execute a shell command
markdown	Display formatted markdown
choose	Single-select dropdown
filter	Filterable multi-select
input	Single-line text input
write	Multi-line text editor
confirm	Yes/No confirmation
file	File picker
toast	Styled status message
spin	Progress spinner
table	Tabular data display
style	Styled bordered content

Template Variables

Steps can access various template variables:

• {{ .Arguments.name }} - Positional argument value
• {{ .Flags.name }} - Flag value
• {{ .TrailingArgs }} - Arguments after --
• {{ .steps.step_name.value }} - Value from a previous step
• {{ .steps.step_name.values }} - Array of values (multi-select)
• {{ .ComponentConfig.vars.xxx }} - Component configuration (requires component_config)
• {{ .env.VAR }} - Environment variable

Learn More

• Custom Commands Documentation
• Workflows Documentation
• Interactive Workflows Example

• custom-commands/.atmos.d/advanced.yaml
• custom-commands/.atmos.d/interactive.yaml
• custom-commands/atmos.yaml
• custom-commands/README.md

Browse all files