dependencies

The dependencies field declares tool dependencies that Atmos installs automatically before a command runs, and the named commands and workflows that must complete first. 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

The project's .tool-versions file is a baseline for custom commands too. Under every install policy, installed versions selected by the file are added to PATH, just as for every Atmos command. Under auto and declared, Atmos does not download missing defaults for a custom command. Set toolchain.install: always to install them, or never to install nothing, including the command's own dependencies.tools. A command's dependencies.tools entry overrides the .tool-versions entry for the same tool, even when one uses a short name or alias and the other the qualified owner/repo name. See Project Defaults.

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. Pinned versions that are already installed are added to PATH when your command executes; the toolchain.install policy controls whether missing ones are installed.

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 with the default toolchain.install: auto:

1. Atmos reads .tool-versions to identify the project's tools
2. Tools that are already installed (for example by atmos toolchain install) are added to PATH; missing tools are not downloaded
3. Command steps execute with the pinned versions of the installed tools

To have Atmos install missing .tool-versions tools for custom commands, set toolchain.install: always, or declare the tools in the command's dependencies.tools.

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.

Named command and workflow dependencies

dependencies.commands and dependencies.workflows declare other named custom commands and workflows that must complete before this command runs its own steps. They resolve and run concurrently by default — like go-task's deps: — through the same generic DAG scheduler used by parallel/matrix needs: and Terraform's dependencies.components:

commands:
  - name: build
    steps:
      - command: go build ./...

  - name: test
    dependencies:
      commands: [build]
    steps:
      - command: go test ./...

  - name: lint
    dependencies:
      commands: [build]
    steps:
      - command: golangci-lint run ./...

  - name: release
    dependencies:
      commands: [test, lint]
    steps:
      - type: atmos
        command: terraform apply infra -s dev

Running atmos release resolves the full dependency closure: build runs once (even though both test and lint depend on it — a shared dependency is deduped, not run twice), then test and lint run concurrently once build finishes, then release's own steps run.

commands

List of custom command names. Entries can be a plain string (build) or an object with flags/args overrides for a parameterized invocation. Commands run in-process, reusing the already-registered Cobra command — no subprocess is spawned. Resolved globally: Atmos deep-merges every atmos.d-imported command definition into one list before any command runs, so there's no file boundary to specify.

workflows

List of workflow names, each as an object with a required file: — a custom command has no "current workflow file" to default a bare name against, so the file is always explicit, resolved the same way the CLI's atmos workflow <name> -f <file> resolves it. Workflow dependencies run in-process within internal/exec.

Parameterized dependencies

An entry with flags/args runs the target with those overrides. Two entries with the same name and parameters collapse into one execution; entries with different parameters are distinct and both run:

commands:
  - name: build
    flags:
      - name: env
        default: dev
    steps:
      - command: go build -o bin/{{ .Flags.env }}/handler ./cmd/handler

  - name: release
    dependencies:
      commands:
        - name: build
          flags: { env: dev }
        - name: build
          flags: { env: prod }
    steps:
      - command: ./scripts/publish.sh

Failure propagation

By default (wait_all), a failed dependency skips everything that transitively depends on it. fail reuses the exact same modes parallel uses, derived from every direct dependency entry on this command (best_effort wins if any sets it, else fail_fast if any sets it, else wait_all):

dependencies:
  commands:
    - name: test
      fail: best_effort   # wait_all (default) | fail_fast | best_effort

Related Documentation

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