cmd

All states also accept the full set of requisite parameters and Salt-parity state attributes — see Dependencies & Requisites.

Parameter Types

StringList

A list of strings. Accepts a single string (a one-element list), a list of strings, or a mixed scalar list whose elements are rendered to strings. A nested list or map element is rejected rather than dropped.

StringMap

A map of string keys to string values. Scalar values are rendered to strings; a nested map or list value is rejected. Not expressible as a CLI key=value argument.

cmd.run

Execute a command on the target system and capture its output.

Source: pkg/state/modules/cmd/cmd_run.go

cmd.run executes a command (command, defaulting to the state ID) on the target and captures its output. For Salt compatibility command also accepts the name alias, so cmd.run: - name: apt-get update runs apt-get update (a declared command wins over name). Commands are not inherently idempotent, so the creates parameter provides an idempotency mechanism: a file path that, when it already exists, means the command has already run and is skipped.

When args is empty the command string is run through the shell (sh -c), so shell features (pipes, redirection, &&) work; when args is non-empty the command is executed directly with those arguments (no shell). cwd sets the working directory and env sets environment variables (merged with the peel process's environment).

cmd.run is ALSO a remote-execution module of the same name: the state module documented here is the primary surface, and the execmod sibling is reachable from templates via salt['cmd.run'](...) and from the CLI as an ad-hoc zester '<target>' cmd.run '<command>'.

Parameters

Effects

Check

When creates is set and the path already exists, reports no change (the command is considered already run); a stat error other than not-exist fails the phase rather than re-running. Otherwise always reports a change — the command needs to run.

Apply

Re-evaluates the creates guard independently of Check (a watch-forced Apply bypasses Check, and a creates-guarded one-shot must not re-run just because a watched dependency changed): when the path exists, the command is not run and Apply is a no-op. Otherwise it runs the command — through the shell (sh -c) when args is empty, directly with the arguments otherwise — in cwd with env merged into the process environment, capturing stdout, stderr, and the exit code into its details. A non-zero exit is returned as an error (with the captured output still in details).

Revert

Commands are not revertible: Revert is a no-op (Changed: false). Manage any undo logic with a separate state.

Examples

Run a command ad hoc

The bare positional argument is the command string.

zester 'web*' cmd.run 'df -h'

One-shot command guarded by creates

creates makes the command idempotent — it is skipped once the marker path exists.

initialize_database:
  cmd.run:
    - command: /usr/local/bin/init-db --setup
    - creates: /var/lib/myapp/.db-initialized

Command with arguments and a working directory

A non-empty args list runs the command directly (no shell) in cwd.

build_application:
  cmd.run:
    - command: make
    - args:
      - build
      - "-j4"
    - cwd: /opt/myapp/src

Command with environment variables after a dependency

env is merged with the process environment; require orders this after the package install.

run_migrations:
  cmd.run:
    - command: python manage.py migrate --noinput
    - cwd: /opt/webapp
    - env:
        DJANGO_SETTINGS_MODULE: myproject.settings.production
    - creates: /opt/webapp/.migrations-done
    - require:
      - "pkg.installed:python3"

See Also

• module.run