shell

The shell step type runs a shell command or script, letting your custom commands and workflows reach beyond Atmos to repository scripts, make targets, test commands, and any other tooling in your stack.

steps:
  - name: test
    type: shell
    working_directory: !repo-root
    command: make test

Fields

command

Required. Shell command text.

working_directory

Optional directory where the command runs.

env

Optional environment variables for this step.

timeout

Optional duration such as 30s, 5m, or a bare number of seconds. When it elapses, Atmos cancels the command and fails the step with step timed out. The timeout bounds the whole step, including every retry attempt and the wait between attempts, so retries never extend it.

tty

Allocate a pseudo-terminal for terminal-native commands.

interactive

Attach host stdin so the command can read from the terminal.

Non-interactive shell steps can use output modes. Steps with tty or interactive attach directly to the terminal and do not produce capturable stdout.

Timeout and cancellation

When a shell step times out or is canceled, for example with Ctrl-C, Atmos ends the whole process tree the command started, including grandchildren, and not only the shell. The same applies to every place Atmos runs a shell command: custom commands, workflows, the !exec YAML function, and hook commands. A timeout overrun reads step timed out, and its explanation names the step and its type: Step '<name>' (type shell) did not finish within its timeout of <duration>.

A child whose stdin is a terminal, such as an editor or a prompt, stays in the terminal's foreground process group so it can keep reading the terminal. Atmos signals only that direct child. On Windows, Atmos stops only the direct child.