pypyr.steps.shell
run commands in default shell
Runs the context value cmd
in the default shell. On a sensible O/S, this is
/bin/sh
, or more recently zsh
.
Do all the things you can’t do with cmd. cmd
runs a
program or executable, shell
invokes the actual system shell. This means
all your shell expressions are available, such as your favorite bashisms.
If you are just looking to run a command with arguments, you do not need to use
shell
, you can use cmd
instead, which will incur less processing overhead.
set shell commands
Input context can take one of two forms:
- name: pypyr.steps.shell
description: passing cmd as a string doesn't save the output to context.
prints stdout in real-time.
in:
cmd: 'echo ${PWD}'
- name: pypyr.steps.shell
description: passing cmd as a dict allows you to specify if you want to
save the output to context.
prints command output only AFTER it has finished running.
in:
cmd:
run: 'echo ${PWD}'
save: True
cwd: './set/current/working/dir/here'
All inputs support substitutions.
changing working directory
If you specify cwd
, it 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.
When you do set cwd
, the executable or program specified in run
is relative
to the cwd
. cwd
itself is relative to the over-all pypyr working directory.
If you do not specify cwd
, it defaults to the current working directory,
which is from wherever you are running pypyr
.
capture shell output
Be aware that if save
is True
, all of the command output ends up in
memory. Don’t specify it unless your pipeline actually uses the stdout/stderr
response in subsequent steps.
Keep in mind that if the invoked command has a non-zero return code pypyr will
automatically raise a CalledProcessError
and stop the pipeline - in other
words, you do not have to set save
to True
to handle the output in
case of error, the pipeline will stop and report the error 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
is 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]}"
examples
Example pipeline yaml using a pipe:
steps:
- name: pypyr.steps.shell
comment: if you have something pipey in working dir it should show up
in:
cmd: ls | grep pipe
- name: pypyr.steps.shell
comment: if you want to pass curlies to the shell, use sic strings
in:
cmd: !sic echo ${PWD};
See a worked example for shell pipeline power.
multiple inline shell statements
Friendly reminder of the difference between separating your shell statements
with ;
or &&
:
;
will continue to the next statement even if the previous command errored. It won’t exit with an error code if it wasn’t the last statement.&&
stops and exits reporting error on first error.
You can change directory multiple times during this shell step using
cd
, but dir changes are only in scope for subsequent commands in this
step, not for subsequent steps. Instead prefer using the cwd
input as
described above for an easy life, which sets the working directory for
the entire step without you having to code it in with chained shell
commands.
- name: pypyr.steps.shell
comment: hop one up from current working dir.
sic means won't attempt to
substitute {PWD} from context, so
shell will interpret it as the $ENV.
in:
cmd: !sic echo ${PWD}; cd ../; echo ${PWD}
- name: pypyr.steps.shell
comment: back to your current working dir
in:
cmd: !sic echo ${PWD}