Atmos Custom Commands

Atmos Custom Commands

Use this skill when users define or modify project-specific Atmos CLI commands in the top-level commands section of atmos.yaml.

Custom commands replace scattered scripts with discoverable CLI commands that can use arguments, flags, environment variables, authentication identities, tool dependencies, component config, nested subcommands, and typed execution steps.

When a task is mainly about steps, step type, working_directory, step env, output, scripts, workdirs, or hook-compatible step payloads, also load atmos-steps.

Quick Shape

commands:
  - name: hello
    description: Say hello
    arguments:
      - name: name
        default: World
    steps:
      - type: say
        text: "Hello {{ .Arguments.name }}"

atmos hello
atmos hello Erik

For full field syntax, read references/command-syntax.md.

Agent Workflow

1. Inspect existing commands in atmos.yaml and imported config before adding a new command.
2. Prefer native typed steps over large shell blocks.
3. Add flags and arguments with clear names and defaults.
4. Use dependencies.tools for tools the command needs in its execution context.
5. Use identity when the command needs Atmos Auth credentials.
6. Verify with atmos <command> --help and a dry-run or read-only invocation when possible.

Native Step Preference

Default to structured steps before shell:

Shell is still appropriate for short glue commands, terminal-native tools, checked-in scripts, or commands that genuinely need shell semantics.

Common Patterns

Flags and Arguments

commands:
  - name: deploy-one
    arguments:
      - name: component
        required: true
    flags:
      - name: stack
        shorthand: s
        required: true
    steps:
      - type: atmos
        command: terraform deploy {{ .Arguments.component }} -s {{ .Flags.stack }}

Tool Dependencies

commands:
  - name: scan
    dependencies:
      tools:
        checkov: "latest"
    steps:
      - type: shell
        command: checkov --directory .

Authentication

commands:
  - name: prod-whoami
    dependencies:
      tools:
        aws-cli: "^2.0.0"
    identity: prod-readonly
    steps:
      - type: shell
        command: aws sts get-caller-identity

Custom Component Types

Use component_config when a custom command should resolve a component and stack before running:

commands:
  - name: render-app
    arguments:
      - name: component
        required: true
    flags:
      - name: stack
        shorthand: s
        required: true
    component_config:
      component: "{{ .Arguments.component }}"
      stack: "{{ .Flags.stack }}"
    steps:
      - type: shell
        command: ./scripts/render-app.sh

Routing

Guardrails

• Do not override built-in commands unless the user explicitly wants that behavior.
• Do not hide complex business logic inside inline YAML shell blocks. Move it to a checked-in script or use native step types.
• Do not use custom commands for long-lived reusable orchestration when an Atmos workflow is a better fit.
• Keep command names stable; they become user-facing CLI API.