cmdmod#

State module for executing commands on a posix systems.

async idem_posix.states.cmdmod.run(hub, ctx, name: str, cmd: str, cwd: str = None, shell: bool = False, env: Dict[str, Any] = None, umask: str = None, timeout: int = None, render_pipe: str = None, is_string_output: bool = False, success_retcodes: List[int] = None, **kwargs) → Dict[str, Any][source]#

Execute the passed command and return the output as a string

Parameters:

  • name (str) – The state name.

  • cmd (str or list[str]) – The command to run. ex: ls -lart /home

  • cwd (str, Optional) – The directory from which to execute the command. Defaults to the home directory of the user specified by runas (or the user under which Salt is running if runas is not specified).

  • shell (bool) – If False, let python handle the positional arguments. Set to True to use shell features, such as pipes or redirection. Defaults to False.

  • env (dict[str], Optional) –

    Environment variables to be set prior to execution. Defaults to None.

    Note

    When passing environment variables on the CLI, they should be passed as the string representation of a dictionary.

    idem exec cmd.run 'some command' env='{"FOO": "bar"}'

  • umask (str, Optional) – The umask (in octal) to use when running the command.

  • timeout (int or float, Optional) – A timeout in seconds for the executed process to return. Defaults to None.

  • render_pipe (str, Optional) – The render pipe to use on the output. Defaults to None.

  • is_string_output (bool) – Give the output in string format irrespective of format the command executed returns. Defaults to False.

  • success_retcodes (list[int], Optional) – The result will be True if the command’s return code is in this list. Defaults to [0].

  • kwargs – kwargs that will be forwarded to subprocess.

Returns:

Dict[str, Any]

Example

# Execute "ls -l" command
my_state_name:
  cmd.run:
    - cmd: ls -l
    - cwd: /
    - shell: False
    - env:
       ENV_VAR_1: ENV_VAL_1
       ENV_VAR_2: ENV_VAL_2
    - timeout: 100
    - render_pipe:
    - kwargs:

The “new_state” will have the following keys:

“stdout”: The plaintext output of the command

“stderr”: The plaintext error/logging output of the command

“retcode”: The return code from the command

“state”: The output as rendered from the render_pipe (if one was given), for use in arg_binding