win_shell - Execute shell commands on target hosts.

New in version 2.2.

Synopsis

The win_shell module takes the command name followed by a list of space-delimited arguments. It is similar to the win_command module, but runs the command via a shell (defaults to PowerShell) on the target host.
For non-Windows targets, use the shell module instead.

Options

parameter	required	comments
chdir	no	set the specified path as the current working directory before executing a command
creates	no	a path or path filter pattern; when the referenced path exists on the target host, the task will be skipped.
executable	no	change the shell used to execute the command (eg, `cmd`). The target shell must accept a `/c` parameter followed by the raw command line to be executed.
free_form	yes	The `win_shell` module takes a free form command to run. There is no parameter actually named 'free form'. See the examples!
removes	no	a path or path filter pattern; when the referenced path does not exist on the target host, the task will be skipped.

Examples

# Execute a command in the remote shell; stdout goes to the specified
# file on the remote.
- win_shell: C:\somescript.ps1 >> c:\somelog.txt

# Change the working directory to somedir/ before executing the command.
- win_shell: C:\somescript.ps1 >> c:\somelog.txt chdir=c:\somedir

# You can also use the 'args' form to provide the options. This command
# will change the working directory to somedir/ and will only run when
# somedir/somelog.txt doesn't exist.
- win_shell: C:\somescript.ps1 >> c:\somelog.txt
  args:
    chdir: c:\somedir
    creates: c:\somelog.txt

# Run a command under a non-Powershell interpreter (cmd in this case)
- win_shell: echo %HOMEDIR%
  args:
    executable: cmd
  register: homedir_out

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name	description	returned	type	sample
cmd	The command executed by the task	always	string	rabbitmqctl join_cluster rabbit@master
delta	The command execution delta time	always	string	0:00:00.325771
end	The command execution end time	always	string	2016-02-25 09:18:26.755339
msg	changed	always	boolean	True
rc	The command return code (0 means success)	always	int	0
start	The command execution start time	always	string	2016-02-25 09:18:26.429568
stderr	The command standard error	always	string	ls: cannot access foo: No such file or directory
stdout	The command standard output	always	string	Clustering node rabbit@slave1 with rabbit@master ...
stdout_lines	The command standard output split in lines	always	list	["u'Clustering node rabbit@slave1 with rabbit@master ...'"]

Notes

Note

If you want to run an executable securely and predictably, it may be better to use the win_command module instead. Best practices when writing playbooks will follow the trend of using win_command unless win_shell is explicitly required. When running ad-hoc commands, use your best judgement.
WinRM will not return from a command execution until all child processes created have exited. Thus, it is not possible to use win_shell to spawn long-running child or background processes. Consider creating a Windows service for managing background processes.
For non-Windows targets, use the shell module instead.
See also win_command, raw

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance Info

For more information about Red Hat’s this support of this module, please refer to this knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/win_shell_module.html

Docs

Docs4dev

Title here