Skip to main content

atmos scaffold list

List all scaffold templates configured in your atmos.yaml file. This helps you discover available templates and their details before generating code.

atmos scaffold list --help

Usage​

atmos scaffold list

This command reads the scaffold.templates section from your atmos.yaml and displays all configured templates in a formatted table.

Examples​

List All Templates​

$ atmos scaffold list

Available scaffold templates:

Name              Source                                          Version    Description
────────────────  ──────────────────────────────────────────────  ─────────  ────────────────────────────────
vpc-component     ./scaffolds/vpc                                 1.0.0      AWS VPC component template
eks-cluster       ./scaffolds/eks                                 2.1.0      EKS cluster template
rds-instance      github.com/acme/scaffolds/rds.git               1.5.0      RDS database template
microservice      github.com/acme/scaffolds/microservice.git      2.0.0      Standard microservice template

Output Format​

The list command displays a table with the following columns:

Name
Template identifier used with atmos scaffold generate
Source

Template location:

  • Local path: ./scaffolds/vpc
  • Git repository: github.com/org/repo.git
Version
Template version number
Description
Human-readable template description

Configuration​

Templates must be configured in atmos.yaml:

scaffold:
  # Optional: base path for local templates
  base_path: "./scaffolds"

  # Template definitions
  templates:
    # Local template
    vpc-component:
      description: "AWS VPC component template"
      source: "./scaffolds/vpc"
      version: "1.0.0"

    # Remote Git template
    eks-cluster:
      description: "EKS cluster template"
      source: "github.com/cloudposse/atmos-scaffolds/eks.git"
      version: "2.1.0"
      ref: "tags/v2.1.0"

    # Another local template
    rds-instance:
      description: "RDS database template"
      source: "./scaffolds/rds"
      version: "1.5.0"

Use Cases​

Discover Available Templates​

Before generating code, see what templates are available:

# List templates
atmos scaffold list

# Pick one and generate
atmos scaffold generate vpc-component ./components/terraform/vpc

Verify Template Configuration​

Check that your templates are properly configured:

$ atmos scaffold list

# If empty or missing templates, check atmos.yaml

Team Onboarding​

New team members can quickly see standard templates:

# Show what templates the team maintains
atmos scaffold list

# Generate using team standard
atmos scaffold generate team-vpc ./components/terraform/vpc

Documentation​

Generate documentation of available scaffolds:

# Redirect to file for documentation
atmos scaffold list > docs/available-scaffolds.txt

Troubleshooting​

No Templates Found​

No scaffold templates configured in atmos.yaml.
Add a 'scaffold.templates' section to your atmos.yaml to configure available templates.

Solution: Add templates to your atmos.yaml:

scaffold:
  templates:
    my-template:
      description: "My template"
      source: "./scaffolds/my-template"
      version: "1.0.0"

Invalid Configuration​

Error: templates section is not a valid configuration

Solutions:

  1. Check YAML syntax in atmos.yaml
  2. Ensure scaffold.templates is a map/object
  3. Validate each template has required fields

atmos.yaml Not Found​

Error: failed to read scaffold section from atmos.yaml

Solutions:

  1. Run command from your Atmos project root
  2. Verify atmos.yaml exists
  3. Check file permissions

Tips and Best Practices​

Organize Templates by Category​

Group related templates in configuration:

scaffold:
  templates:
    # Networking templates
    vpc-component:
      description: "AWS VPC component"
      source: "./scaffolds/networking/vpc"
      version: "1.0.0"

    subnet-component:
      description: "AWS Subnet component"
      source: "./scaffolds/networking/subnet"
      version: "1.0.0"

    # Compute templates
    eks-cluster:
      description: "EKS cluster"
      source: "./scaffolds/compute/eks"
      version: "2.0.0"

    ec2-instance:
      description: "EC2 instance"
      source: "./scaffolds/compute/ec2"
      version: "1.5.0"

Use Descriptive Names​

Choose clear, searchable template names:

# Good - descriptive and clear
vpc-component:
  description: "AWS VPC component with NAT gateway"

eks-cluster-private:
  description: "EKS cluster in private subnets"

# Avoid - unclear and generic
template1:
  description: "Template"

my-template:
  description: "Something"

Document Template Requirements​

Add detailed descriptions:

vpc-component:
  description: "AWS VPC component. Requires: vpc_name, cidr_block. Optional: enable_nat_gateway, enable_dns_hostnames"
  source: "./scaffolds/vpc"
  version: "1.0.0"

Version Your Templates​

Use semantic versioning:

vpc-component:
  source: "./scaffolds/vpc"
  version: "1.2.3"  # major.minor.patch

Update version when making changes:

  • Major: Breaking changes (incompatible API changes)
  • Minor: New features (backward-compatible)
  • Patch: Bug fixes (backward-compatible)

Example Workflow​

# 1. List available templates
$ atmos scaffold list

Name              Description
────────────────  ────────────────────────
vpc-component     AWS VPC component
eks-cluster       EKS cluster template

# 2. Choose a template
$ atmos scaffold generate vpc-component ./components/terraform/vpc

# 3. Customize generated code
$ cd components/terraform/vpc
$ vim main.tf

# 4. Commit
$ git add .
$ git commit -m "Add VPC component from scaffold"

Learn More​