# Custom Commands

Atmos can be extended to support any number of custom CLI commands. Custom commands are exposed through the `atmos` CLI and appear in `atmos help`. They are a great way to centralize how operational tools are run and improve developer experience.

_\[Video: Atmos Custom Commands]_

One great way to use custom commands is to tie all your miscellaneous scripts into one consistent CLI interface. Then you can kiss those ugly, inconsistent arguments to bash scripts goodbye — just wire up the commands in `atmos` to call the script. Developers can then run `atmos help` and discover every available command.

## Simple Example

Adding the following to `atmos.yaml` introduces a new `hello` command:

```yaml
# Custom CLI commands
commands:
  - name: hello
    description: This command says Hello world
    steps:
      - "echo Hello world!"
```

Run it like this:

```shell
atmos hello
```

## The `commands` section

`commands` is a list of command objects. Each entry defines one custom command (which can
itself contain nested [`commands`](/cli/configuration/commands/commands) for subcommands).
See the [`command`](/cli/configuration/commands/command) reference for every key a command
supports.

```yaml
commands:
  - name: hello
    description: This command says Hello world
    steps:
      - "echo Hello world!"
  - name: greet
    description: This command greets the provided name
    arguments:
      - name: name
        description: Name to greet
        default: John Doe
    steps:
      - "echo Hello {{ .Arguments.name }}!"
```

## Reference

- **[`command`](/cli/configuration/commands/command)**
  The structure of a single custom command and all of its keys.
- **[`arguments`](/cli/configuration/commands/arguments)**
  Positional arguments, including trailing arguments and typed (component/stack) arguments.
- **[`flags`](/cli/configuration/commands/flags)**
  Long and short flags, boolean flags, defaults, and semantic types.
- **[`env`](/cli/configuration/commands/env)**
  Environment variables exported to the command's steps.
- **[`steps`](/cli/configuration/commands/steps)**
  What the command runs. Custom commands support the same step types as 
  [workflows](/workflows)
  .
- **[`component`](/cli/configuration/commands/component)**
  Custom component types that bring stack configuration into a command.
- **[`dependencies`](/cli/configuration/commands/dependencies)**
  Tool dependencies 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)**
  Authenticate an Atmos auth identity before the command runs.
- **[`commands`](/cli/configuration/commands/commands)**
  Nested subcommands for grouping related commands.

## Try It

Explore working examples that demonstrate custom commands in action.