# command

A `command` is one entry in the [`commands`](/cli/configuration/commands) list. It defines a custom `atmos` subcommand — its name, help text, the arguments and flags it accepts, the environment it runs in, and the steps it executes.

The example below uses the most common keys. Each key has its own reference page linked in [Fields](#fields).

```yaml
commands:
  - name: deploy
    description: Deploy a component to a stack
    verbose: false                 # set true to see verbose execution output
    identity: superadmin           # authenticate before running
    working_directory: !repo-root . # where steps run
    arguments:
      - name: component
        description: Component to deploy
        required: true
    flags:
      - name: stack
        shorthand: s
        description: Stack to deploy to
        required: true
    env:
      - key: ATMOS_COMPONENT
        value: "{{ .Arguments.component }}"
    dependencies:
      tools:
        terraform: "1.9.8"
    steps:
      - atmos terraform apply {{ .Arguments.component }} -s {{ .Flags.stack }} -auto-approve
```

Run it with:

```shell
atmos deploy vpc -s plat-ue2-prod
```

## Fields

- **`name`**
  Required. The command name as typed after 
  `atmos`
   (for example, 
  `deploy`
  ). For nested commands, this is the subcommand name. Names appear in 
  `atmos help`
  , unless the command is marked 
  `internal`
  .
- **`description`**
  Required. Help text shown in 
  `atmos help`
   and 
  `atmos <command> --help`
  . Supports multi-line YAML for usage examples.
- **`default`**
  Optional. Name of the subcommand to run when this command is invoked without an explicit subcommand.
- **[`arguments`](/cli/configuration/commands/arguments)**
  Positional arguments the command accepts.
- **[`flags`](/cli/configuration/commands/flags)**
  Long/short flags the command accepts.
- **[`env`](/cli/configuration/commands/env)**
  Environment variables exported to every step.
- **[`steps`](/cli/configuration/commands/steps)**
  The work the command performs. Custom commands support the same step types as 
  [workflows](/workflows)
  .
- **[`component`](/cli/configuration/commands/component)**
  Bind the command to a custom component type so it can read stack configuration.
- **[`dependencies`](/cli/configuration/commands/dependencies)**
  Tools that must be installed (via the toolchain) before the command runs.
- **[`working_directory`](/cli/configuration/commands/working-directory)**
  The directory the command's steps execute in.
- **[`identity`](/cli/configuration/commands/identity)**
  An Atmos auth identity to authenticate as before running.
- **[`commands`](/cli/configuration/commands/commands)**
  Nested subcommands.
- **`verbose`**
  Set to 
  `true`
   to print verbose execution output for the command. Defaults to 
  `false`
  .
- **`aliases`**
  Alternative names this command is also invocable under, registered natively and in-process (the same underlying command object, just with extra names) — distinct from the top-level 
  [`aliases`](/cli/configuration/aliases)
   config, which redirects to a possibly-unrelated command via a subprocess. See 
  [Aliases](#aliases)
  .
- **`internal`**
  Set to 
  `true`
   to exclude the command from 
  `atmos --help`
   listings and completion suggestions while keeping it directly runnable (
  `atmos <name> ...`
  ) and its own 
  `--help`
   output intact — useful for a command meant to be called only as a 
  [dependency](/cli/configuration/commands/dependencies)
   of another command, not run directly. Defaults to 
  `false`
  . List a parent's internal subcommands with 
  `atmos <parent> --help=hidden`
  .

## Aliases

```yaml
commands:
  - name: deploy
    aliases: [dep, d]
    description: Deploy a component to a stack
    steps:
      - atmos terraform apply {{ .Arguments.component }} -s {{ .Flags.stack }} -auto-approve
```

`atmos dep vpc -s plat-ue2-prod` and `atmos d vpc -s plat-ue2-prod` both run the same command as `atmos deploy vpc -s plat-ue2-prod`. Aliases appear in `atmos --help` and in `atmos list aliases` (categorized `custom`, distinct from Atmos's own built-in command aliases and the top-level [`aliases`](/cli/configuration/aliases) config).