# 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`
  .
- **`description`**
  Required. Help text shown in 
  `atmos help`
   and 
  `atmos <command> --help`
  . Supports multi-line YAML for usage examples.
- **[`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`
  .