dependencies

The dependencies field declares tool dependencies that Atmos installs automatically before a command runs. This ensures any CLI tools your command requires are available at the correct version, leveraging Atmos's toolchain management.

Basic Usage

Specify tool dependencies using the dependencies.tools section within your command:

commands:
  - name: lint
    description: Run tflint on terraform components
    dependencies:
      tools:
        tflint: "0.54.0"
    arguments:
      - name: component
        description: Component to lint
        required: true
    flags:
      - name: stack
        shorthand: s
        description: Stack name
        required: true
    steps:
      - atmos terraform generate varfile {{ .Arguments.component }} -s {{ .Flags.stack }}
      - tflint --chdir=components/terraform/{{ .Arguments.component }}

When you run atmos lint vpc -s plat-ue2-dev, Atmos will:

1. Check if tflint 0.54.0 is installed in the toolchain directory
2. Install it from the toolchain registry if missing
3. Execute the command steps with the tool available in PATH

Multiple Tool Dependencies

Commands can declare multiple tool dependencies:

commands:
  - name: security-scan
    description: Run security scans on infrastructure code
    dependencies:
      tools:
        tflint: "0.54.0"
        checkov: "3.0.0"
        tfsec: "1.28.0"
    steps:
      - tflint --chdir=components/terraform
      - checkov -d components/terraform
      - tfsec components/terraform

Version Specification

Tool versions can be specified in several formats:

dependencies:
  tools:
    # Exact version
    terraform: "1.9.8"

    # Latest available version
    kubectl: "latest"

Integration with Toolchain Configuration

Tool dependencies in custom commands work with your toolchain configuration in atmos.yaml. Tools are installed to the configured install_path and resolved using your configured registries.

# atmos.yaml
toolchain:
  install_path: ".tools"
  registries:
    - name: aqua
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10

commands:
  - name: lint
    dependencies:
      tools:
        tflint: "0.54.0"  # Installed to .tools/, resolved via aqua registry
    steps:
      - tflint --version

tip

Use tool dependencies in custom commands to ensure all team members and CI/CD pipelines use consistent tool versions without manual installation steps.

Using Toolchain Tools

Custom commands automatically have access to tools defined in your project's .tool-versions file. The toolchain ensures the correct versions are installed and available in PATH when your command executes.

Automatic Tool Access

If your project has a .tool-versions file:

terraform 1.10.0
kubectl 1.32.0
helm 3.16.0

Custom commands can use these tools directly:

commands:
  - name: deploy
    description: Deploy infrastructure
    steps:
      - terraform init
      - terraform plan
      - kubectl apply -f manifests/

When you run atmos deploy:

1. Atmos reads .tool-versions to identify required tools
2. Missing tools are automatically installed
3. PATH is updated to include toolchain binaries
4. Command steps execute with the correct tool versions

Declaring Additional Dependencies

Use the dependencies field to require additional tools or override versions from .tool-versions:

commands:
  - name: validate
    description: Validate with specific tool versions
    dependencies:
      tools:
        tflint: "^0.54.0"      # Additional tool not in .tool-versions
        terraform: "1.9.8"     # Override .tool-versions version
    steps:
      - terraform validate
      - tflint --recursive

Dependencies declared in the command take precedence over .tool-versions.

Version Constraints

Dependencies support SemVer constraints:

Constraint	Meaning	Example
1.10.3	Exact version	Only version 1.10.3
~> 1.10.0	Pessimistic (patch)	Includes 1.10.x but not 1.11.0
^1.10.0	Compatible (minor)	Includes 1.x.x but not 2.0.0
latest	Latest available	Most recent version

tip

The combination of .tool-versions for project-wide defaults and per-command dependencies for overrides gives you flexibility while maintaining consistency across your team.

Related Documentation

• Toolchain Configuration - Configure tool version management
• Workflows - Workflows also support toolchain integration