cmdmod#

Exec module for executing commands on a posix systems.

async idem_posix.exec.cmdmod.run(hub, cmd: str, cwd: str = None, shell: bool = False, stdin: str = None, stdout: int = -1, stderr: int = -1, render_pipe: str = None, env: Dict[str, Any] = None, timeout: int = None, is_string_output: bool = False, success_retcodes: List[int] = None, *args, **kwargs) → Dict[str, Any][source]#

Execute the passed command and return the output as a string

Parameters:

  • 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.

  • stdin (str, Optional) – A string of standard input can be specified for the command to be run using the stdin parameter. This can be useful in cases where sensitive information must be read from standard input.

  • stdout (int) – A string of standard input can be specified for the command to be run using the stdout parameter.

  • stderr (int) – A string of standard input can be specified for the command to be run using the stderr parameter.

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

  • 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"}'

  • timeout (int or float, Optional) – A timeout in seconds for the executed process to return. 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].

  • args – args that will be forwarded to subprocess.

  • kwargs – kwargs that will be forwarded to subprocess.

Returns:

Returns command output

  • stdout(str): The plaintext output of the command.

  • stderr(str): The plaintext error/logging output of the command.

  • retcode(str): The return code from the command.

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

Return type:

Dict[str, Any]

Example

idem exec cmd.run "shell command --with-flags" cwd=/home render_pipe=json timeout=10