pypyr.steps.cmd

execute arbitrary external commands, applications & scripts

Run a program, run an external script, application or command. Execute the context value cmd as a sub-process.

In cmd, you cannot use things like exit, return, shell pipes, filename wildcards, environment variable expansion, and expansion of ~ to a user’s home directory. Use pypyr.steps.shell for this instead. cmd runs a command, it does not invoke the shell.

set command input

Input context can take one of two forms:

- name: pypyr.steps.cmd
  description: passing cmd as a string does not save the output to context.
               it prints stdout in real-time.
  in:
    cmd: 'echo ${PWD}'
- name: pypyr.steps.cmd
  description: passing cmd as a dict allows you to specify if you want to
               save the output to context.
               it prints command output only AFTER it has finished running.
  in:
    cmd:
      run: 'echo ${PWD}'
      save: False # optional. Set True to save cmd output to context.
      cwd: './current/working/dir/here' # optional. Default to pypyr execution dir.

Supports string substitutions.

changing the working directory

If you specify cwd, pypyr will change the current working directory to cwd to execute this command. The directory change is only for the duration of this step, not any subsequent steps. If you specify cwd, the executable or program set in run is relative to the cwd if the run cmd specifies a relative path.

If you do not specify cwd, it defaults to the current working directory, which is from wherever you are running pypyr.

save cmd output stdout & stderr

Set save: True to capture the command’s output.

Be aware that if save is True, all of the command output ends up in memory. Don’t specify it unless your pipeline uses the stdout/stderr response in subsequent steps.

Keep in mind that if the invoked command return-code is non-zero pypyr will automatically raise a CalledProcessError and stop the pipeline, so assuming the command returns a non-zero error code you do not have to do anything special to get the pipeline to fail automatically. If this is not the behavior you want, you can suppress errors with the swallow decorator and use the runErrors list on subsequent steps. Only use save: True when you actually need the stdout or stderr output.

If save: True, pypyr will save the output to context as follows:

cmdOut:
  returncode: 0
  stdout: 'stdout str here. None if empty.'
  stderr: 'stderr str here. None if empty.'

cmdOut.returncode is the exit status of the called process. Typically 0 means OK. A negative value -N indicates that the child was terminated by signal N (POSIX only).

You can use cmdOut in subsequent steps like this:

- name: pypyr.steps.echo
  run: !py "cmdOut['returncode'] == 0"
  in:
    echoMe: "you'll only see me if cmd ran successfully with return code 0.
            the command output was: {cmdOut[stdout]}"

example

Example pipeline yaml:

steps:
  - name: pypyr.steps.cmd
    in:
      cmd: ls -a

See a worked example for cmd.