# cmd

run a command

Without creates or unless, the check result is unknown, and apply runs the command each time. A secret in the command does not show in the process list of the host. A program that the command starts with the secret as an argument, such as psql -c, does show it.

## Keys

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`command`](#cmd.command) | string | required | shell script |
| [`creates`](#cmd.creates) | string | - | path that marks the work as done |
| [`unless`](#cmd.unless) | string | - | check command; exit 0 skips the step |
| [`user`](#cmd.user) | string | root | account that runs command |
| [`dir`](#cmd.dir) | string | / | working directory |
| [`timeout`](#cmd.timeout) | integer | 600 | limit in seconds, also for unless |

### `cmd.command` {#cmd.command}

string, required

Shell script. It runs through sh -e as root, in /, with stdin from /dev/null. A script of several lines stops at its first failed line. Without creates or unless, the check result is unknown.

### `cmd.creates` {#cmd.creates}

string

Path that marks the work as done. The step is ok when the path exists. When the command exits 0 and the path is still missing, the step fails. The path has no glob characters. A step has at most one of creates and unless.

### `cmd.unless` {#cmd.unless}

string

Check command; exit 0 skips the step. It runs at the check as root, in /, with the timeout of the step. user and dir do not apply to it. A step has at most one of creates and unless.

### `cmd.user` {#cmd.user}

string, default root

Account that runs command. Its home is HOME. The step starts no login session: PAM does not run, so the login umask and limits of the account do not apply, and the umask is 022.

### `cmd.dir` {#cmd.dir}

string, default /

Working directory.

### `cmd.timeout` {#cmd.timeout}

integer, default 600

Limit in seconds, also for unless. After it, winch stops the command and the step fails.

## Example

```yaml
- name: Build the alias database
  cmd:
    command: newaliases
    creates: /etc/aliases.db
```